按钮

按钮是基本组件,可让用户触发已定义的操作。按钮有五种类型。下表介绍了五种按钮类型的外观以及应在何处使用它们:

类型 外观 用途
实心 纯色背景,文字颜色与背景颜色形成对比。 高强调度按钮。这些按钮用于应用中的主要操作,例如“提交”和“保存”。阴影效果可突出按钮的重要性。
填充色调 背景颜色会根据表面颜色而变化。 也适用于主要或重要操作。填充色调按钮具有更高的视重,适合“添加到购物车”和“登录”等功能。
过高 通过阴影效果脱颖而出。 用途与色调按钮类似。提高高度可使按钮更加突出。
加边框 具有边框,但没有填充。 中度强调按钮,包含重要但非主要的操作。它们与其他按钮搭配使用,可表示“取消”或“返回”等替代性次要操作。
文本 显示没有背景或边框的文本。 低强调按钮,非常适合不太重要的操作(例如导航链接)或次要功能(例如“了解详情”或“查看详情”)。

此图片展示了 Material Design 中的五种按钮类型:

五个按钮组件的示例,其中突出显示了各自的独特特征。
图 1. 五个按钮组件。

API Surface

  • onClick:用户按下按钮时系统调用的函数。
  • enabled:如果为 false,此参数会使按钮显示为不可用和不活跃。
  • colors:ButtonColors 的实例,用于确定按钮中使用的颜色。
  • contentPadding:按钮内的内边距。

填充按钮

填充按钮组件使用基本的 Button 可组合项。默认情况下,它会填充纯色。该代码段展示了如何实现该组件并以互动方式预览:

@Composable
fun FilledButtonExample(onClick: () -> Unit) {
    Button(onClick = { onClick() }) {
        Text("Filled")
    }
}

填充色调按钮

填充色调按钮组件使用 FilledTonalButton 可组合项。默认情况下,它会填充色调颜色。

以下代码段展示了如何实现该组件并以互动方式预览:

@Composable
fun FilledTonalButtonExample(onClick: () -> Unit) {
    FilledTonalButton(onClick = { onClick() }) {
        Text("Tonal")
    }
}

描边按钮

描边按钮组件使用 OutlinedButton 可组合项。默认情况下,它会显示轮廓。

以下代码段展示了如何实现该组件并以互动方式预览:

@Composable
fun OutlinedButtonExample(onClick: () -> Unit) {
    OutlinedButton(onClick = { onClick() }) {
        Text("Outlined")
    }
}

浮起按钮

凸起按钮组件使用 ElevatedButton 可组合项。默认情况下,它具有表示高度效果的阴影。这是一种带阴影的填充按钮。

以下代码段展示了如何实现该组件并以互动方式预览:

@Composable
fun ElevatedButtonExample(onClick: () -> Unit) {
    ElevatedButton(onClick = { onClick() }) {
        Text("Elevated")
    }
}

文本按钮

文本按钮组件使用 TextButton 可组合项。在按下之前,它仅显示为文本。默认情况下,它没有纯色填充或轮廓。

以下代码段展示了如何实现该组件并以互动方式预览:

@Composable
fun TextButtonExample(onClick: () -> Unit) {
    TextButton(
        onClick = { onClick() }
    ) {
        Text("Text Button")
    }
}

M3 Expressive 更新

按钮现在有更多形状和大小,并具有切换功能,在选中时可以改变形状。

按钮的尺寸和形状
图 7. Material 3 Expressive 按钮尺寸和形状变体。

如需详细了解按钮的 M3 Expressive 更新,请参阅 Material Design 3 按钮指南。

切换按钮

有四种切换按钮样式可供选择:填充、凸起、色调和轮廓。

实心

填充按钮样式具有仅次于悬浮操作按钮 (FAB) 的视觉冲击力,应将其用于完成流程的重要最终操作,例如保存、立即加入或确认。

以下代码段演示了如何实现填充式切换按钮:

@Composable
fun ToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    ToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Button")
    }
}

过高

浮起按钮可与视觉上突出的背景区分开来。

以下代码段演示了如何实现浮凸切换按钮:

@Composable
fun ElevatedToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    ElevatedToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Elevated Button")
    }
}

Tonal

默认情况下,色调按钮样式会填充色调颜色。在需要稍微强调低优先级按钮(比轮廓按钮更突出)的情况下,这种按钮非常有用。

以下代码段演示了如何使用 FilledTonalToggleButton 实现色调切换按钮:

@Composable
fun TonalToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    FilledTonalToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Tonal Button")
    }
}

加边框

描边样式非常适合中等强调度的按钮,这些按钮包含重要但并非产品中主要操作的操作。

以下代码段演示了如何实现描边切换按钮:

@Composable
fun OutlinedToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    OutlinedToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Outlined Button")
    }
}

大小选项

除了默认的小尺寸外,Material 3 Expressive 还添加了四种尺寸选项:超小、中、大和超大。表现力按钮重载需要一个 shapes 参数,或者您也可以通过设置 ButtonDefaults.contentPaddingFor(...) 将表现力大小应用于标准 Button,如以下示例所示:

小(现有默认值)

小按钮尺寸:

  • 高度:40dp

默认按钮

以下代码段演示了如何实现带图标的小按钮:

@Composable
fun ButtonWithIconSample() {
    Button(
        onClick = { /* Do something! */ },
        contentPadding = ButtonDefaults.contentPaddingFor(ButtonDefaults.MinHeight, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.FavoriteFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(ButtonDefaults.MinHeight)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(ButtonDefaults.MinHeight)))
        Text("Like")
    }
}

切换按钮

以下代码段演示了如何实现带有图标的小切换按钮:

@Composable
fun ToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    ToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.FavoriteFilled else AppIcons.Favorite),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.IconSize),
        )
        Spacer(Modifier.size(ButtonDefaults.IconSpacing))
        Text("Like")
    }
}

特小

特小按钮尺寸:

  • 高度:32dp

默认按钮

以下代码段演示了如何实现带有图标的超小按钮:

@Composable
fun XSmallButtonWithIconSample() {
    val size = ButtonDefaults.ExtraSmallContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label")
    }
}

切换按钮

以下代码段演示了如何实现带有图标的超小切换按钮:

@Composable
fun XSmallToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.ExtraSmallContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label")
    }
}

中

中号按钮尺寸:

  • 高度:56dp

默认按钮

以下代码段演示了如何实现带有图标的中型按钮:

@Composable
fun MediumButtonWithIconSample() {
    val size = ButtonDefaults.MediumContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

切换按钮

以下代码段演示了如何实现带图标的中型切换按钮:

@Composable
fun MediumToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.MediumContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

大

大按钮尺寸:

  • 高度:96dp

默认按钮

以下代码段演示了如何实现带图标的大按钮:

@Composable
fun LargeButtonWithIconSample() {
    val size = ButtonDefaults.LargeContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

切换按钮

以下代码段演示了如何实现带有图标的大型切换按钮:

@Composable
fun LargeToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.LargeContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

特大

超大按钮尺寸:

  • 高度:136dp

默认按钮

以下代码段演示了如何实现带有图标的超大按钮:

@Composable
fun XLargeButtonWithIconSample() {
    val size = ButtonDefaults.ExtraLargeContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

切换按钮

以下代码段演示了如何实现带有图标的超大切换按钮:

@Composable
fun XLargeToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.ExtraLargeContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

形状选项

有两种形状选项可供选择:方形和圆形。

方形按钮大小发生变化。
图 8. 方形按钮圆角半径随尺寸变化而缩放。

方形按钮具有容器,容器的圆角会根据按钮大小进行缩放。

圆角按钮示例。
图 9. 圆角按钮。

圆形按钮类型具有全圆角容器。选中后,方形切换按钮的形状会变为圆形。

以下代码段演示了如何实现一个方形切换按钮,该按钮在选中时会变为圆形:

@Composable
fun SquareToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    val shapes =
        ToggleButtonShapes(
            shape = ToggleButtonDefaults.checkedShape,
            pressedShape = ToggleButtonDefaults.pressedShape,
            checkedShape = ToggleButtonDefaults.shape,
        )
    ToggleButton(checked = checked, onCheckedChange = { checked = it }, shapes = shapes) {
        Text("Button")
    }
}

其他资源