单选按钮

单选按钮可让用户从一组选项中选择一个选项。当只能从列表中选择一项时，您可以使用单选按钮。如果用户需要选择多项内容，请改用开关。

图 1. 一对单选按钮，其中一个选项处于选中状态。

API Surface

使用 RadioButton 可组合项列出可用选项。将每个 RadioButton 选项及其标签封装在 Row 组件中，以便将它们分组在一起。

RadioButton 包含以下关键参数：

• selected：指示是否选中了单选按钮。
• onClick：用户点击单选按钮时应用执行的 lambda 函数。如果此值为 null，则用户无法直接与单选按钮互动。
• enabled：控制单选按钮是处于启用状态还是停用状态。用户无法与停用的单选按钮互动。
• interactionSource：可让您观察按钮的互动状态，例如按钮是否被按下、悬停或聚焦。

创建基本单选按钮

以下代码段在 Column 中呈现单选按钮列表：

@Composable
fun RadioButtonSingleSelection(modifier: Modifier = Modifier) {
    val radioOptions = listOf("Calls", "Missed", "Friends")
    val (selectedOption, onOptionSelected) = remember { mutableStateOf(radioOptions[0]) }
    // Note that Modifier.selectableGroup() is essential to ensure correct accessibility behavior
    Column(modifier.selectableGroup()) {
        radioOptions.forEach { text ->
            Row(
                Modifier
                    .fillMaxWidth()
                    .height(56.dp)
                    .selectable(
                        selected = (text == selectedOption),
                        onClick = { onOptionSelected(text) },
                        role = Role.RadioButton
                    )
                    .padding(horizontal = 16.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                RadioButton(
                    selected = (text == selectedOption),
                    onClick = null // null recommended for accessibility with screen readers
                )
                Text(
                    text = text,
                    style = MaterialTheme.typography.bodyLarge,
                    modifier = Modifier.padding(start = 16.dp)
                )
            }
        }
    }
}
RadioButton.kt

代码要点

• radioOptions 表示单选按钮的标签。
• remember 可组合函数会创建一个状态变量 selectedOption 和一个用于更新该状态的函数 onOptionSelected。此状态会保留所选的单选按钮选项。
  • mutableStateOf(radioOptions[0]) 会将状态初始化为列表中的第一项。“Calls”是第一项，因此它是默认选中的单选按钮。
• Modifier.selectableGroup() 可确保屏幕阅读器具有正确的无障碍行为。它会告知系统，此 Column 中的元素属于可选择组，从而实现适当的屏幕阅读器支持。
• Modifier.selectable() 会使整个 Row 充当单个可选内容。
  • selected 指示是否根据 selectedOption 状态选择当前 Row。
  • 当点击 Row 时，onClick lambda 函数会将 selectedOption 状态更新为所点击的选项。
  • role = Role.RadioButton 会告知无障碍服务，Row 的功能类似于单选按钮。
• RadioButton(...) 会创建 RadioButton 可组合项。
  • RadioButton上的 onClick = null 可提高无障碍性。这样可以防止单选按钮直接处理点击事件，并允许 Row 的 selectable 修饰符管理选择状态和无障碍行为。

结果

图 2. 三个单选按钮，其中“好友”选项处于选中状态。

其他资源

• Material Design：按钮