单选按钮

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

图 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]) 会将状态初始化为列表中的第一项。“通话”是第一个项目，因此系统会默认选中该单选按钮。
• Modifier.selectableGroup() 可确保屏幕阅读器的无障碍功能行为正常。它会告知系统此 Column 中的元素属于可选择的组，从而实现适当的屏幕阅读器支持。
• Modifier.selectable() 会使整个 Row 充当一个可选择项。
  • selected 指示当前 Row 是否已根据 selectedOption 状态被选中。
  • 当用户点击 Row 时，onClick lambda 函数会将 selectedOption 状态更新为所点击的选项。
  • role = Role.RadioButton 会通知无障碍服务 Row 用作单选按钮。
• RadioButton(...) 会创建 RadioButton 可组合项。
  • RadioButton 上的 onClick = null 可提升无障碍功能。这可防止单选按钮直接处理点击事件，并允许 Row 的 selectable 修饰符管理选择状态和无障碍行为。

结果

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

其他资源

• Material Design：按钮