按钮组

按钮组可对按钮和图标按钮应用协调的形状、动作和宽度变化,从而整理按钮并添加按钮之间的互动。按钮组有两种变体:

  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)
            }
        }
    }
}