OpenHarmony ArkUI 仓颉版 CheckboxGroup 组件详解:多选框群组的创建、全选控制与 onChange 回调实践
OpenHarmony ArkUI 仓颉版 CheckboxGroup 组件详解:多选框群组的创建、全选控制与 onChange 回调实践
本文基于 CangjieCorpus 仓库中 CheckboxGroup 组件参考文档,系统讲解 OpenHarmony ArkUI(仓颉版)中 CheckboxGroup 多选框群组组件的创建方式、group 分组机制、selectAll/selectedColor 属性、onChange 事件回调以及 CheckboxGroupResult 数据结构,并结合示例代码演示如何实现"全选/反选"交互与自定义勾选样式,帮助开发者在仓颉 UI 工程(ohos_app_cangjie_entry 包)中快速落地多选框群组功能。
一、组件定位:为什么需要 CheckboxGroup
在 ArkUI 中,Checkbox 是单个多选框组件,通常用于某选项的打开或关闭,参见 Checkbox 组件文档。当页面存在多个同类选项、需要"一键全选/取消全选"的交互时(例如批量勾选、批量操作列表),就需要 CheckboxGroup 组件来统一控制群组内所有 Checkbox 的选中状态。
CheckboxGroup 的定位是:多选框群组,用于控制多选框全选或者不全选状态。它本身不承载具体业务选项,而是通过 group 名称把若干 Checkbox 组织进同一个逻辑群组,从而:
- 通过
selectAll(true)/selectAll(false)让群组内所有多选框全选或全不选; - 通过
selectedColor统一设置群组"被选中或部分选中"状态的颜色; - 通过
onChange事件获取群组当前的整体选中状态(全选/部分选/全不选)以及被选中项的名称列表。
所有能力均要求系统能力 SystemCapability.ArkUI.ArkUI.Full,起始版本为 22(与仓颉版 ArkUI 组件体系的起始版本一致),这也是后文所有 API 的适用前提。
二、导入模块与组件声明
使用 CheckboxGroup 前,需要在仓颉源文件中导入 ArkUI Kit:
import kit.ArkUI.*
CheckboxGroup 没有子组件(文档中"子组件"一节标注为"无"),它作为容器类组件直接声明在布局树中。其声明形式为带命名参数的 init:
public init(group!: ?String = None)
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| group | ?String | 否 | None | 命名参数。 多选框的群组名称。 |
分组匹配规则:group 值相同的 Checkbox 和 CheckboxGroup 属于同一群组。换言之,把若干 Checkbox 的 group 参数设置为 "checkboxGroup",再把 CheckboxGroup 的 group 也设置为 "checkboxGroup",它们就被逻辑绑定在一起。Checkbox 侧的 group 参数在 Checkbox 文档 中说明为"用于指定多选框所属群组的名称(即所属 CheckboxGroup 的名称)",且"未配合使用 CheckboxGroup 组件时,此值无用"——这印证了分组是 Checkbox 与 CheckboxGroup 之间的显式契约。
与带缓存组件配合的注意事项:文档明确指出,"在结合带缓存组件使用时(如 List),未被创建的 Checkbox 选中状态需要应用手动控制"。可以推断,当 Checkbox 位于 List/LazyForEach 这类按需创建、离屏回收的容器中时,尚未被创建的项不会自动跟随 selectAll 生效,需要在数据源层面自行维护选中状态。这是使用群组组件时最容易被忽略的边界情况。
三、组件属性详解
CheckboxGroup 支持全部通用属性与通用事件(参见 通用属性文档、通用事件文档),此外还有两个专属组件属性。
3.1 selectAll:设置是否全选
public func selectAll(value: ?Bool): This
功能:设置是否全选。若同组的 Checkbox 显式设置了 select 属性,则 Checkbox 的优先级高。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| value | ?Bool | 是 | - | 是否全选。初始值:false。 值为 true 时,多选框群组都被选中。值为 false 时,多选框群组都不被选中。 |
这一条优先级规则是理解 CheckboxGroup 行为的关键:群组级 selectAll 是"默认值/批量指令",而单个 Checkbox.select 是"显式覆盖"。例如先 selectAll(true) 再对某个 Checkbox 执行 select(false),则该多选框保持未选中,其余群组内多选框为选中状态。从 selectAll 返回 This 的签名也可以看出,ArkUI 仓颉版组件方法普遍采用链式调用风格,便于在声明处连续设置多个属性。
3.2 selectedColor:设置选中/部分选中颜色
public func selectedColor(value: ?ResourceColor): This
功能:设置被选中或部分选中状态的颜色。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| value | ?ResourceColor | 是 | - | 被选中或部分选中状态的颜色。 |
参数类型为 ResourceColor 接口,根据 通用类型文档,Color、UInt32、Int64、AppResource 均实现了该接口,因此十六进制字面量(如 0xed6f21)、颜色常量或资源引用都可以直接传入。示例代码中使用的 .selectedColor(0xed6f21) 即通过 UInt32 扩展实现传入主题橙色。注意与 Checkbox 自身的 selectedColor(控制单个多选框选中颜色)区分:CheckboxGroup.selectedColor 控制的是群组组件在被选中或部分选中状态下呈现的颜色(例如全选框本体被点选时的着色)。
四、组件事件 onChange 与回调数据结构
4.1 onChange 事件
public func onChange(callback: ?OnCheckboxGroupChangeCallback): This
功能:CheckboxGroup 的选中状态或群组内的 Checkbox 的选中状态发生变化时,触发回调。
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| callback | ?OnCheckboxGroupChangeCallback | 是 | - | 多选框群组的信息。初始值:{ _ => } |
回调签名是一个函数类型别名:
public type OnCheckboxGroupChangeCallback = (CheckboxGroupResult) -> Unit
也就是说,每次状态变化都会携带一个 CheckboxGroupResult 对象,描述此刻群组的完整选中情况,而不是像 Checkbox.onChange((Bool) -> Unit)那样只传一个布尔值。这使得"全选/部分选/全不选"三态以及"具体哪些项被选中"都能在事件层直接获取。
4.2 CheckboxGroupResult 结构
public class CheckboxGroupResult {
public var status: SelectStatus
public var name: Array<String>
public init(
status: SelectStatus,
name: Array<String>
)
}
功能:多选框群组选中状态信息。包含两个可读写字段:
-
var status: SelectStatus—— 选中状态,取值为 SelectStatus 枚举。根据 通用类型定义,该枚举为:public enum SelectStatus <: Equatable<SelectStatus> { | All // 群组多选框全部选择 | Part // 群组多选框部分选择 | None // 群组多选框全部没有选择 | ... }All/Part/None三个状态正好对应全选框组件常见的三态显示逻辑:全部选中显示勾选、部分选中显示半选、全部未选显示空白。 -
var name: Array<String>—— 群组内所有被选中的多选框名称。名称即各Checkbox构造时传入的name参数值,业务侧可据此与数据源做映射,无需自己维护勾选集合。
CheckboxGroupResult 的 init(status: SelectStatus, name: Array<String>) 构造函数用于显式构造该信息对象,一般用于测试或数据模拟场景,UI 回调中由框架填充。
五、示例代码分析
5.1 示例一:设置多选框群组(全选控制)
官方示例演示了一个"Select All"总控框加两个子项的典型布局:CheckboxGroup 作为全选框,与两个 Checkbox 通过 group: "checkboxGroup" 绑定,点击全选框即可批量改变子项状态,onChange 回调中打印当前所有被选中项的名称。
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.hilog.*
import ohos.arkui.state_macro_manage.*
import std.collection.ArrayList
func loggerInfo(str: String) {
Hilog.info(0, "CangjieTest", str)
}
func formatNames(names: Array<String>): String {
var result = ""
for(name in names) {
result += name + ";"
}
result
}
@Entry
@Component
class EntryView {
func build() {
Column(){
Flex(justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center) {
CheckboxGroup(group:"checkboxGroup")
.size(width: 50.vp, height: 50.vp)
.selectedColor(0xed6f21)
.selectAll(false)
.onChange({ val =>
loggerInfo("checkboxGroup onChange names:" + formatNames(val.name))
})
Text("Select All").fontSize(50)
}
Flex(justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center) {
Checkbox(name: "checkbox1", group:"checkboxGroup")
.size(width: 50.vp, height: 50.vp)
Text("checkbox1").fontSize(50)
}
Flex(justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center) {
Checkbox(name: "checkbox2", group:"checkboxGroup")
.size(width: 50.vp, height: 50.vp)
Text("checkbox2").fontSize(50)
}
}
}
}
该示例体现的要点:
- 三处
group: "checkboxGroup"构成同一群组:CheckboxGroup与checkbox1、checkbox2两个Checkbox的 group 命名一致,是绑定关系成立的前提; .selectAll(false)声明初始状态下群组内无全选(初始值本身也是false,此处为显式声明);.onChange({ val => ... })中val即CheckboxGroupResult,通过val.name拿到当前所有被选中项的名称数组,formatNames将其拼接为"checkbox1;checkbox2;"这类字符串后走Hilog.info(domain 0、tagCangjieTest)输出日志;- 子项
Checkbox仅设置name与group,未显式调用select,因此其初始选中状态完全由CheckboxGroup.selectAll主导,符合"未显式设置select时群组优先"的语义。
说明:原文档为两个示例分别配有效果演示图(
figures/checkbox_group.gif、figures/checkbox_group2.gif),该图片文件在当前仓库中不存在,故本文不插入配图,交互效果可直接运行示例代码观察。
5.2 示例二:自定义勾选样式(selectAll(true))
第二个示例与示例一布局相同,但把全选框初始状态改为 selectAll(true),并增加第三个子项 checkbox3,用于验证群组初始即全选时的表现以及回调名称列表的变化过程:
package ohos_app_cangjie_entry
import kit.ArkUI.*
import ohos.hilog.*
import ohos.arkui.state_macro_manage.*
import std.collection.ArrayList
func loggerInfo(str: String) {
Hilog.info(0, "CangjieTest", str)
}
func formatNames(names: Array<String>): String {
var result = ""
for(name in names) {
result += name + ";"
}
result
}
@Entry
@Component
class EntryView {
func build() {
Column(){
Flex(justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center) {
CheckboxGroup(group:"checkboxGroup1")
.size(width: 50.vp, height: 50.vp)
.selectedColor(0xed6f21)
.selectAll(true)
.onChange({ val =>
loggerInfo("checkboxGroup1 onChange names:" + formatNames(val.name))
})
Text("Select All").fontSize(50)
}
Flex(justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center) {
Checkbox(name: "checkbox1", group:"checkboxGroup1")
.size(width: 50.vp, height: 50.vp)
Text("checkbox1").fontSize(50)
}
Flex(justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center) {
Checkbox(name: "checkbox2", group:"checkboxGroup1")
.size(width: 50.vp, height: 50.vp)
Text("checkbox2").fontSize(50)
}
Flex(justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center) {
Checkbox(name: "checkbox3", group:"checkboxGroup1")
.size(width: 50.vp, height: 50.vp)
Text("checkbox3").fontSize(50)
}
}
}
}
对比示例一,该示例将 selectAll(true) 设为初始状态,群组内三个子项在首帧即全部选中,CheckboxGroup 呈现选中/部分选中着色(0xed6f21),取消其中任一项后群组状态从 All 迁移到 Part,val.name 中不再包含被取消项的名称。文档称该示例"通过配置 mark 实现自定义多选框群组的勾选样式",即在默认勾选标记之外的样式调整演示。
六、与 Checkbox 的配合要点与常见注意事项
- group 命名必须严格一致:
CheckboxGroup(group: "x")与Checkbox(group: "x")大小写、拼写完全相同才会被识别为同一群组,否则全选控制不生效。 - 优先级:
Checkbox.select显式设置 >CheckboxGroup.selectAll。需要对个别项做"例外"处理时,在子项上显式调用select。 - 名称是回调数据的唯一标识:
CheckboxGroupResult.name返回的是Checkbox的name参数值,因此务必给每个子项设置有意义的name,否则回调中无法区分具体项。 - 三态判断:
onChange中建议结合val.status(All/Part/None)与val.name做业务分支,例如status == SelectStatus.All时展示"全选成功"提示,Part时展示已选数量。 - 带缓存容器场景:
Checkbox放入List等带缓存/按需创建的组件时,未被创建的项的选中状态需要应用层手动控制(如把选中集合维护在状态数据中,创建节点时按数据初始化select)。 - 默认值回顾:
selectAll初始值为false;selectedColor在Checkbox上的默认值为0xff007dff(群组组件文档未给出独立默认色,建议显式指定以对齐主题);onChange初始回调为{ _ => }空实现,不注册事件时不影响渲染。
七、小结
CheckboxGroup 以 group 名称为纽带把多个 Checkbox 组织为逻辑群组,提供了 selectAll 批量选中控制、selectedColor 群组级选中着色、onChange + CheckboxGroupResult(SelectStatus 三态 + 名称数组)的完整状态回传机制。在 OpenHarmony 仓颉版 ArkUI 应用中,按"声明同 group 的 CheckboxGroup 与 Checkbox → 配置 selectAll/selectedColor → 在 onChange 中根据 status 与 name 驱动业务逻辑"的三步即可实现可靠的全选交互;在 List 等带缓存场景中,则需额外注意未创建子项的选中状态需要应用手动维护。完整 API 细节可查阅 CheckboxGroup 参考文档 与 Checkbox 参考文档。