核取方塊

核取方塊可讓使用者從清單中選取一或多個項目。您可以使用核取方塊讓使用者執行下列操作：

• 開啟或關閉項目。
• 可選取清單中的多個選項。
• 請指出協議或接受。

圖解

核取方塊包含下列元素：

• Box：這是核取方塊的容器。
• 「Check」：這是視覺指標，顯示是否已勾選核取方塊。
• 標籤：這是描述核取方塊的文字。

狀態

核取方塊的狀態可能是下列三種：

• 未選取：未勾選這個核取方塊。方塊是空的。
• 未定：核取方塊處於未定狀態。包裝盒內有一個破折號。
• 已選取：已勾選核取方塊。包裝盒上有勾號。

下圖顯示核取方塊的三個狀態。

導入作業

您可以使用 Checkbox 可組合函式，在應用程式中建立核取方塊。請注意以下幾個重要參數：

• checked：用來擷取已勾選或未勾選核取方塊的布林值。
• onCheckedChange()：使用者輕觸核取方塊時應用程式呼叫的函式。

下列程式碼片段說明如何使用 Checkbox 可組合項：

@Composable
fun CheckboxMinimalExample() {
    var checked by remember { mutableStateOf(true) }

    Row(
        verticalAlignment = Alignment.CenterVertically,
    ) {
        Text(
            "Minimal checkbox"
        )
        Checkbox(
            checked = checked,
            onCheckedChange = { checked = it }
        )
    }

    Text(
        if (checked) "Checkbox is checked" else "Checkbox is unchecked"
    )
}
Checkbox.kt

說明

這段程式碼會建立原先未勾選的核取方塊。當使用者按一下核取方塊時，onCheckedChange lambda 會更新 checked 狀態。

結果

此範例會在未勾選時產生下列元件：

這是勾選時出現的相同核取方塊：

進階範例

以下為更複雜的範例，說明如何在應用程式中實作核取方塊。在這個程式碼片段中，有一個父項核取方塊和一系列子項核取方塊。當使用者輕觸父項核取方塊時，應用程式會勾選所有子項核取方塊。

@Composable
fun CheckboxParentExample() {
    // Initialize states for the child checkboxes
    val childCheckedStates = remember { mutableStateListOf(false, false, false) }

    // Compute the parent state based on children's states
    val parentState = when {
        childCheckedStates.all { it } -> ToggleableState.On
        childCheckedStates.none { it } -> ToggleableState.Off
        else -> ToggleableState.Indeterminate
    }

    Column {
        // Parent TriStateCheckbox
        Row(
            verticalAlignment = Alignment.CenterVertically,
        ) {
            Text("Select all")
            TriStateCheckbox(
                state = parentState,
                onClick = {
                    // Determine new state based on current state
                    val newState = parentState != ToggleableState.On
                    childCheckedStates.forEachIndexed { index, _ ->
                        childCheckedStates[index] = newState
                    }
                }
            )
        }

        // Child Checkboxes
        childCheckedStates.forEachIndexed { index, checked ->
            Row(
                verticalAlignment = Alignment.CenterVertically,
            ) {
                Text("Option ${index + 1}")
                Checkbox(
                    checked = checked,
                    onCheckedChange = { isChecked ->
                        // Update the individual child state
                        childCheckedStates[index] = isChecked
                    }
                )
            }
        }
    }

    if (childCheckedStates.all { it }) {
        Text("All options selected")
    }
}
Checkbox.kt

說明

以下是您應該注意的幾個重點：

• 狀態管理：
  • childCheckedStates：使用 mutableStateOf() 追蹤每個子項核取方塊已勾選狀態的布林值清單。
  • parentState：ToggleableState 值衍生自子項核取方塊的狀態。
• UI 元件：
  • TriStateCheckbox：這是父項核取方塊的必要項目，因為當中的 state 參數可讓您設為不確定。
  • Checkbox：用於每個子項核取方塊，且其狀態已連結至 childCheckedStates 中的對應元素。
  • Text：顯示標籤和訊息 (「全選」、「選項 X」、「已選取所有選項」)。
• Logic：
  • 父項核取方塊的 onClick 會將所有子核取方塊更新為目前父項狀態的相反情況。
  • 每個子項核取方塊的 onCheckedChange 都會更新 childCheckedStates 清單中的對應狀態。
  • 已勾選所有子項核取方塊時，程式碼會顯示「All options selected」。

結果

這個範例會在所有核取方塊都取消勾選的情況下產生以下元件。

同樣地，以下是勾選所有選項後，元件顯示方式，如使用者輕觸全選：

只勾選一個選項時，父項核取方塊會顯示待定狀態：

其他資源

• Material Design 核取方塊