HarmonyOS6 ArkTS CheckboxGroup

组件

1. 组件定义

CheckboxGroup是多选框群组控制器，用于统一管理一组Checkbox组件的选中状态，实现全选、反选、部分选中、状态联动等核心功能，是表单、列表批量选择、筛选功能的核心组件。

2. 核心特性

• 与同组Checkbox自动双向联动
• 支持全选/部分选中/未选中三种状态自动识别
• 统一配置群组样式、颜色、形状
• 实时返回选中的选项名称列表
• 适配HarmonyOS全端设备（手机、平板、智慧屏等）

完整代码

// CheckboxGroupDemo.ets @Entry @Component struct CheckboxGroupDemo { // 控制全选状态（由CheckboxGroup自动维护，不要手动改） @State isSelectAll: boolean = false; // 记录选中的选项名称 @State selectedNames: Array<string> = []; build() { Column({ space: 20 }) { Text("CheckboxGroup 全选群组示例") .fontSize(22) .fontWeight(FontWeight.Bold) .margin({ top: 20 }); // ========== 全选按钮（CheckboxGroup） ========== Flex({ alignItems: ItemAlign.Center }) { CheckboxGroup({ group: "myGroup" }) .selectedColor("#007DFF") .unselectedColor("#999") .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) .mark({ strokeColor: Color.White, strokeWidth: 2, size: 16 }) .onChange((result: CheckboxGroupResult) => { // 接收群组状态：All/Part/None console.info("群组状态：" + JSON.stringify(result)); this.selectedNames = result.name; // 同步全选状态 this.isSelectAll = result.status === SelectStatus.All; }); Text("全选") .fontSize(18) // 去掉了手动改isSelectAll逻辑，避免冲突！ } .width("100%") .padding({ left: 15 }); // 分割线 Divider() .width("90%") .color("#eee") .margin(10); // ========== 同组 Checkbox ========== Flex({ direction: FlexDirection.Column }) { // 选项1 Flex({ alignItems: ItemAlign.Center }) { Checkbox({ name: "item1", group: "myGroup" }) .selectedColor("#007DFF") .unselectedColor("#999") .shape(CheckBoxShape.ROUNDED_SQUARE) .mark({ strokeColor: Color.White }) .onChange((value: boolean) => { console.info("item1 状态：" + value); }); Text("选项 1").fontSize(17); } // 选项2 Flex({ alignItems: ItemAlign.Center }) { Checkbox({ name: "item2", group: "myGroup" }) .selectedColor("#007DFF") .unselectedColor("#999") .shape(CheckBoxShape.ROUNDED_SQUARE) .mark({ strokeColor: Color.White }) .onChange((value: boolean) => { console.info("item2 状态：" + value); }); Text("选项 2").fontSize(17); } // 选项3 Flex({ alignItems: ItemAlign.Center}) { Checkbox({ name: "item3", group: "myGroup" }) .selectedColor("#007DFF") .unselectedColor("#999") .shape(CheckBoxShape.ROUNDED_SQUARE) .mark({ strokeColor: Color.White }) .onChange((value: boolean) => { console.info("item3 状态：" + value); }); Text("选项 3").fontSize(17); } } .padding({ left: 15 }); // ========== 显示选中结果 ========== Column({ space: 8 }) { Text(`当前全选状态：${this.isSelectAll ? "已全选" : "未全选"}`) .fontSize(16) .fontColor("#333"); Text(`已选中：${this.selectedNames.length > 0 ? this.selectedNames.join("、") : "无"}`) .fontSize(16) .fontColor("#007DFF"); } .width("100%") .padding(15) .backgroundColor("#f8f8f8") .borderRadius(12) .margin(10); } .width("100%") .height("100%") .backgroundColor("#fff"); } }

运行效果如图：

核心API与属性

1. 构造参数

CheckboxGroup({ group: "myGroup" })

• group：群组唯一标识，字符串类型
• 所有需要归为一组的Checkbox，必须设置相同的group值

2. 核心样式属性（官方标准属性）

3. 形状枚举CheckBoxShape

• CIRCLE：圆形多选框
• ROUNDED_SQUARE：圆角方形多选框（示例默认使用）

4. 状态监听onChange

.onChange((result: CheckboxGroupResult) => { this.selectedNames = result.name; this.isSelectAll = result.status === SelectStatus.All; })

返回值CheckboxGroupResult

• result.name：已选中的Checkbox名称数组
• result.status：群组整体状态，枚举值SelectStatus

群组状态SelectStatus

• All：全部选中
• Part：部分选中
• None：全部未选中

核心功能

1. 群组绑定规则

1. CheckboxGroup+ 多个Checkbox设置相同group名称
2. 系统自动建立关联，无需额外代码
3. 状态双向联动：全选控制子项，子项控制全选

2. 全选/部分选中/取消全选 自动逻辑

• 所有子项选中 →status = All→ 全选框勾选
• 部分子项选中 →status = Part→ 全选框半选（系统自动）
• 无选中 →status = None→ 全选框取消

3. 状态同步规范

• 禁止手动修改selectAll绑定变量
• 全选状态必须由onChange返回的status自动赋值
• 这是避免状态错乱、选项全部取消的核心规范

总结

1. group必须唯一且一致
   不同群组必须使用不同名称，避免状态冲突。
2. 禁止手动强制修改全选状态
   全选状态必须由CheckboxGroup.onChange自动维护，否则会出现状态错乱。
3. Checkbox必须配置name
   用于在result.name中识别选中项，是业务逻辑的核心标识。
4. 样式优先级
   子Checkbox可单独配置样式，会覆盖CheckboxGroup的统一样式。
5. 版本要求
   所有属性仅支持API 11+ / HarmonyOS 6。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力