圓形按鈕

圓形按鈕可讓使用者從一組選項中選取一個選項。當清單中只能選取一個項目時，請使用圓形按鈕。如果使用者需要選取多個項目，請改用切換鈕。

圖 1. 一組圓形按鈕，其中一個選項已選取。

API 介面

使用 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 會指出系統是否根據 selectedOption 狀態選取目前的 Row。
  • 當使用者點選 Row 時，onClick lambda 函式會將 selectedOption 狀態更新為已點選的選項。
  • role = Role.RadioButton 會通知無障礙服務，Row 會做為圓形按鈕運作。
• RadioButton(...) 會建立 RadioButton 可組合函式。
  • RadioButton 上的 onClick = null 可改善無障礙功能。這可避免圓形按鈕直接處理點擊事件，並允許 Row 的 selectable 修飾符管理選取狀態和無障礙功能行為。

結果

圖 2. 三個圓形按鈕，其中「朋友」選項已選取。

其他資源

• Material Design：按鈕