圓形按鈕

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

兩個沒有標籤的圓形按鈕。選取左側按鈕，圓圈會填滿，表示已選取。未填寫右側按鈕
圖 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 表示目前 Row 是否根據 selectedOption 狀態選取。
    • 點選 Row 時，onClick lambda 函式會將 selectedOption 狀態更新為所點選的選項。
    • role = Role.RadioButton 會通知無障礙服務，Row 函式會做為圓形按鈕。
  • RadioButton(...) 會建立 RadioButton 可組合函式。
    • onClick = null，RadioButton可提升無障礙體驗。這樣可防止單選按鈕直接處理點擊事件，並允許 Row 的 selectable 修飾符管理選取狀態和無障礙功能行為。

結果

三個圓形按鈕的清單，標示為「通話」、「未接」和「好友」。選取「好友」圓形按鈕。
圖 2. 三個圓形按鈕，其中「朋友」選項已選取。

其他資源