按鈕是基本元件,可讓使用者觸發定義的動作。按鈕共有五種類型。下表說明五種按鈕類型的外觀,以及使用時機:
| 類型 | 外觀 | 目的 |
|---|---|---|
| 實心 | 純色背景,搭配對比色文字。 | 高強調按鈕。這些按鈕用於應用程式中的主要動作,例如「提交」和「儲存」。陰影效果可突顯按鈕的重要性。 |
| 實心同色系 | 背景顏色會隨表面而變化。 | 也適用於主要或重要動作。填滿色調按鈕可提供更多視覺權重,適合「加入購物車」和「登入」等功能。 |
| 偏高 | 有陰影,因此較為醒目。 | 用途與色調按鈕類似。提高高度,讓按鈕更醒目。 |
| 有外框 | 有邊框,但沒有填滿。 | 中強調按鈕,包含重要但非主要的動作。這類按鈕適合與其他按鈕搭配使用,用於指出「取消」或「返回」等次要動作。 |
| 文字 | 顯示沒有背景或邊框的文字。 | 低強調按鈕,適合用於較不重要的動作,例如導覽連結,或「瞭解詳情」或「查看詳細資料」等次要功能。 |
下圖顯示 Material Design 的五種按鈕類型:
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 更新
按鈕現在有更多形狀、大小和切換功能,且選取時會改變形狀。

如要進一步瞭解按鈕的 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)) } }
形狀選項
有兩種形狀可供選擇:正方形和圓形。

方形按鈕的容器有細微的圓角,會根據按鈕大小縮放。

圓形按鈕類型的容器具有全圓角。勾選後,方形切換鈕的形狀會變成圓形。
下列程式碼片段示範如何實作方形切換鈕,並在勾選時變更為圓形:
@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") } }