Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

核取方塊

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

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

圖解

核取方塊包含下列元素：

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

州

核取方塊可以處於下列三種狀態之一：

未選取：未勾選核取方塊。盒子是空的。
Indeterminate：核取方塊處於不確定狀態。方塊中會顯示破折號。
已選取：已勾選核取方塊。方塊內有勾號。

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

核取方塊元件的三種狀態範例：未選取、已選取和不確定。 — **圖 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」。