按鈕群組可整理按鈕,並對按鈕和圖示按鈕套用協調的形狀、動作和寬度變化,藉此在按鈕之間加入互動。按鈕群組有兩種變化版本:
- 標準按鈕群組:在相鄰按鈕之間新增互動,讓按鈕在按下時互相回應。
- 連結按鈕群組:將切換鈕分組,讓使用者選取選項、切換檢視畫面,或排序頁面上的元素。
使用按鈕群組
- 在按下或選取按鈕時,套用形狀變形效果。
- 相連按鈕群組會取代分段按鈕。
- 適用於所有按鈕尺寸:特小 (XS)、小 (S)、中 (M)、大 (L) 和特大 (XL)。
- 支援單選、多選和必選模式。
標準按鈕群組
使用 ButtonGroup 可組合項,將按鈕水平排列,展開按下的項目、壓縮相鄰項目,並在空間有限時將額外項目移至溢位選單。按鈕群組應保持在同一行,而非換行。
下列程式碼片段示範如何實作含有溢位選單指標的標準按鈕群組:
@Composable fun ButtonGroupSample() { val numButtons = 10 ButtonGroup( overflowIndicator = { menuState -> ButtonGroupDefaults.OverflowIndicator(menuState = menuState) } ) { for (i in 0 until numButtons) { clickableItem(onClick = {}, label = "$i") } } }
已連結的按鈕群組
使用 ToggleButton 可組合項和 ButtonGroupDefaults 連結形狀建構單選或多選模式,並使用連結按鈕群組。

選取單個
當使用者從互斥組合中選擇一個選項時,請使用單選連結按鈕群組。下列程式碼片段使用 ToggleButton 和 Role.RadioButton 實作單選連結按鈕群組:
@Composable fun SingleSelectConnectedButtonGroupSample() { val options = listOf("Work", "Restaurant", "Coffee", "Search", "Home") val unCheckedIcons = listOf( AppIcons.Work, AppIcons.Restaurant, AppIcons.Coffee, AppIcons.Search, AppIcons.Home, ) val checkedIcons = listOf( AppIcons.WorkFilled, AppIcons.Restaurant, AppIcons.CoffeeFilled, AppIcons.Search, AppIcons.HomeFilled, ) var selectedIndex by remember { mutableIntStateOf(0) } FlexBox( modifier = Modifier.padding(horizontal = 8.dp).fillMaxWidth(), config = { direction(FlexDirection.Row) wrap(FlexWrap.Wrap) columnGap(ButtonGroupDefaults.ConnectedSpaceBetween) rowGap(2.dp) }, ) { options.forEachIndexed { index, label -> ToggleButton( checked = selectedIndex == index, onCheckedChange = { selectedIndex = index }, shapes = when (index) { 0 -> ButtonGroupDefaults.connectedLeadingButtonShapes() options.lastIndex -> ButtonGroupDefaults.connectedTrailingButtonShapes() else -> ButtonGroupDefaults.connectedMiddleButtonShapes() }, modifier = Modifier.semantics { role = Role.RadioButton }, ) { Icon( painter = rememberVectorPainter( if (selectedIndex == index) checkedIcons[index] else unCheckedIcons[index] ), contentDescription = null, ) Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing)) Text(label) } } } }
多選
如果使用者可以獨立切換零或多個選項,請使用多選連結按鈕群組。以下程式碼片段使用 ToggleButton 和 mutableStateListOf 實作多選連結按鈕群組:
@Composable fun MultiSelectConnectedButtonGroupSample() { val options = listOf("Work", "Restaurant", "Coffee", "Search", "Home") val unCheckedIcons = listOf( AppIcons.Work, AppIcons.Restaurant, AppIcons.Coffee, AppIcons.Search, AppIcons.Home, ) val checkedIcons = listOf( AppIcons.WorkFilled, AppIcons.Restaurant, AppIcons.CoffeeFilled, AppIcons.Search, AppIcons.HomeFilled, ) val checked = remember { mutableStateListOf(false, false, false, false, false) } FlexBox( modifier = Modifier.padding(horizontal = 8.dp).fillMaxWidth(), config = { direction(FlexDirection.Row) wrap(FlexWrap.Wrap) columnGap(ButtonGroupDefaults.ConnectedSpaceBetween) rowGap(2.dp) }, ) { options.forEachIndexed { index, label -> ToggleButton( checked = checked[index], onCheckedChange = { checked[index] = it }, shapes = when (index) { 0 -> ButtonGroupDefaults.connectedLeadingButtonShapes() options.lastIndex -> ButtonGroupDefaults.connectedTrailingButtonShapes() else -> ButtonGroupDefaults.connectedMiddleButtonShapes() }, ) { Icon( painter = rememberVectorPainter( if (checked[index]) checkedIcons[index] else unCheckedIcons[index] ), contentDescription = null, ) Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing)) Text(label) } } } }