本頁面由 Cloud Translation API 翻譯而成。

核取方塊

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

開啟或關閉項目。
從清單中的多個選項中選取。
表示同意或接受。

圖解

核取方塊由下列元素組成：

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

狀態

勾選方塊可處於下列三種狀態：

未選取：核取方塊未選取。該方塊是空的。
未定：核取方塊處於未定狀態。方塊中含有破折號。
已選取：已勾選核取方塊。方塊中含有勾號。

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

核取方塊元件在三種狀態 (未選取、已選取和未知) 的示例。 — **圖 1.** 核取方塊的三種狀態。未選取、未知和已選取。

實作

您可以使用 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 狀態。

結果

在未勾選的情況下，這個範例會產生下列元件：

未勾選的核取方塊，並附有標籤。下方的文字顯示「核取方塊已取消勾選」 — **圖 2.** 未勾選的核取方塊

以下是勾選後的核取方塊：

已勾選的核取方塊，並附有標籤。下方文字顯示「核取方塊已勾選」 — **圖 3.** 已勾選的核取方塊

進階範例

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

@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」、「已選取所有選項」)。
邏輯：
- 父項核取方塊的 onClick 會將所有子核取方塊更新為目前父項狀態的相反情況。
- 每個子項核取方塊的 onCheckedChange 會更新 childCheckedStates 清單中的對應狀態。
- 勾選所有子項核取方塊後，程式碼會顯示「All options selected」。

結果

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

同樣地，當使用者輕觸「全部選取」時，元件也會以以下方式顯示：

一系列已勾選的標籤核取方塊，其中包含標籤。第一個標示為「選取全部」。下方有一個文字元件，顯示「all options selected」。 — **圖 5.** 已勾選的核取方塊

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

一系列未勾選的標籤核取方塊，其中包含標籤。除了其中一個以外，所有選項都已取消勾選。標示為「選取全部」的核取方塊為未定義狀態，顯示破折號。 — **圖 6.** 未定核取方塊

其他資源

Material Design 核取方塊