复选框可让用户从列表中选择一项或多项。您可以使用复选框来让用户执行以下操作:
- 开启或关闭某项内容。
- 从列表中选择多个选项。
- 表示同意或接受。
解剖学
复选框由以下元素组成:
- 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" ) }
说明
此代码会创建一个最初未选中的复选框。当用户点击该复选框时,onCheckedChange
lambda 会更新 checked
状态。
结果
如果未选中,此示例会生成以下组件:
![带有标签的未勾选复选框。其下方的文本为“复选框未选中”](https://developer.android.com/static/develop/ui/compose/images/components/checkbox-minimal-unchecked.png?hl=zh-cn)
以下是选中复选框时同一复选框的显示方式:
![带有标签的选中复选框。其下方的文本为“复选框已选中”](https://developer.android.com/static/develop/ui/compose/images/components/checkbox-minimal-checked.png?hl=zh-cn)
高级示例
以下示例较为复杂,展示了如何在应用中实现复选框。此代码段中有一个父级复选框和一系列子级复选框。当用户点按父级复选框时,应用会检查所有子级复选框。
@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") } }
说明
在此示例中,您应注意以下几点:
- 状态管理:
childCheckedStates
:布尔值列表,使用mutableStateOf()
跟踪每个子复选框的选中状态。parentState
:一个ToggleableState
,其值派生自子复选框的状态。
- 界面组件:
TriStateCheckbox
:对父级复选框而言是必需的,因为它具有state
参数,可让您将其设置为“不确定”。Checkbox
:用于每个子复选框,其状态与childCheckedStates
中的相应元素相关联。Text
:显示标签和消息(“全选”“选项 X”“已选择所有选项”)。
- 逻辑:
- 父级复选框的
onClick
会将所有子级复选框更新为与当前父级复选框相反。 - 每个子复选框的
onCheckedChange
都会在childCheckedStates
列表中更新其相应的状态。 - 当所有子复选框都被选中时,代码会显示“
All options selected
”。
- 父级复选框的
结果
当所有复选框都处于未选中状态时,此示例会生成以下组件。
![一系列未勾选的带有标签的复选框。](https://developer.android.com/static/develop/ui/compose/images/components/checkbox-parent-unchecked.png?hl=zh-cn)
同样,以下是选中所有选项(当用户点按“全选”)时组件的显示方式:
![一系列已勾选的带有标签的复选框。第一项标记为“全选”。下方有一个文本组件,显示“已选择所有选项”。](https://developer.android.com/static/develop/ui/compose/images/components/checkbox-parent-checked.png?hl=zh-cn)
当只选中一个选项时,父级复选框会显示不确定状态:
![一系列未勾选的带有标签的复选框。仅保留一项,其余所有项都未选中。标为“全选”的复选框是不确定的,只显示一条短划线。](https://developer.android.com/static/develop/ui/compose/images/components/checkbox-parent-indeterminate.png?hl=zh-cn)