复选框

复选框可让用户从列表中选择一个或多个项目。您可以使用复选框来让用户执行以下操作：

• 开启或关闭某项内容。
• 从列表中的多个选项中进行选择。
• 表明同意或接受。

注意 ：如果可以从列表中选择多个选项，请使用复选框，而不是开关或单选按钮

解剖学

复选框由以下元素组成：

• Box：这是复选框的容器。
• Check：这是一个视觉指示器，显示复选框是否处于选中状态。
• 标签：这是描述复选框的文本。

状态

复选框有三种状态：

• 未选中：未选中该复选框。框中没有任何内容。
• 不确定：复选框处于不确定状态。方框包含一个短划线。
• Selected：已选定复选框。该方框包含一个对勾标记。

下图演示了复选框的三种状态。

图 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，其值派生自子复选框的状态。
• 界面组件：
  • TriStateCheckbox：对于父复选框来说是必要的，因为它具有 state 参数，可让您将其设置为不确定。
  • Checkbox：用于每个子复选框（其状态链接到 childCheckedStates 中的相应元素）。
  • Text：显示标签和邮件（“全选”“选项 X”“已选择所有选项”）。
• 逻辑：
  • 父级复选框的 onClick 会将所有子级复选框更新为与当前父级状态相反。
  • 每个子复选框的 onCheckedChange 都会更新其在 childCheckedStates 列表中的相应状态。
  • 勾选所有子复选框后，代码会显示“All options selected”。

注意 ：如果您想要为复选框添加不确定状态，则必须使用 TriStateCheckbox。这是因为它包含类型为 ToggleState 的 state 参数，而 Checkbox 没有。

结果

当所有复选框均未选中时，此示例会生成以下组件。

图 4. 未选中的复选框

同样，当所有选项都勾选后，也就是用户点按“全选”时，该组件的显示方式如下：

图 5. 选中的复选框

如果仅选中一个选项，父级复选框会显示不确定状态：

图 6. 不确定型复选框

其他资源

• Material Design 复选框