按鈕群組

按鈕群組可整理按鈕,並對按鈕和圖示按鈕套用協調的形狀、動作和寬度變化,藉此在按鈕之間加入互動。按鈕群組有兩種變化版本:

  1. 標準按鈕群組:在相鄰按鈕之間新增互動,讓按鈕在按下時互相回應。
  2. 連結按鈕群組:將切換鈕分組,讓使用者選取選項、切換檢視畫面,或排序頁面上的元素。
左側為標準按鈕群組,右側為相連按鈕群組。
圖 1. 標準按鈕群組 (1,左) 和連結按鈕群組 (2,右)。

使用按鈕群組

  • 在按下或選取按鈕時,套用形狀變形效果。
  • 相連按鈕群組會取代分段按鈕。
  • 適用於所有按鈕尺寸:特小 (XS)、小 (S)、中 (M)、大 (L) 和特大 (XL)。
  • 支援單選、多選和必選模式。
包含各種形狀和大小按鈕的按鈕群組。
圖 2. 包含各種形狀和大小按鈕的按鈕群組。

標準按鈕群組

使用 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 連結形狀建構單選或多選模式,並使用連結按鈕群組。

已連結的按鈕群組行為。
圖 3. 回應式連結按鈕群組行為。

選取單個

當使用者從互斥組合中選擇一個選項時,請使用單選連結按鈕群組。下列程式碼片段使用 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)
            }
        }
    }
}