按鈕

按鈕是基本元件,可讓使用者觸發定義的動作。按鈕共有五種類型。下表說明五種按鈕類型的外觀,以及使用時機:

類型 外觀 目的
實心 純色背景,搭配對比色文字。 高強調按鈕。這些按鈕用於應用程式中的主要動作,例如「提交」和「儲存」。陰影效果可突顯按鈕的重要性。
實心同色系 背景顏色會隨表面而變化。 也適用於主要或重要動作。填滿色調按鈕可提供更多視覺權重,適合「加入購物車」和「登入」等功能。
偏高 有陰影,因此較為醒目。 用途與色調按鈕類似。提高高度,讓按鈕更醒目。
有外框 有邊框,但沒有填滿。 中強調按鈕,包含重要但非主要的動作。這類按鈕適合與其他按鈕搭配使用,用於指出「取消」或「返回」等次要動作。
文字 顯示沒有背景或邊框的文字。 低強調按鈕,適合用於較不重要的動作,例如導覽連結,或「瞭解詳情」或「查看詳細資料」等次要功能。

下圖顯示 Material Design 的五種按鈕類型:

五種按鈕元件的範例,並醒目顯示其獨特特徵。
圖 1. 五個按鈕元件。

API 介面

  • 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 還提供四種尺寸選項:特小、中、大和特大。Expressive 按鈕超載需要 shapes 參數,您也可以設定 ButtonDefaults.contentPaddingFor(...),將 Expressive 大小套用至標準 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")
    }
}

其他資源