核取方塊

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

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

注意： 如果清單中可選取多個選項，請使用核取方塊，而非切換鈕或圓形按鈕

圖解

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

• 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」。

注意： 如要讓核取方塊顯示未知狀態，您必須使用 TriStateCheckbox。這是因為它具有 ToggleState 類型的 state 參數，而 Checkbox 則沒有。

結果

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

圖 4. 未勾選的核取方塊

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

圖 5. 已勾選的核取方塊

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

圖 6. 未定核取方塊

其他資源

• Material Design 核取方塊