OpenHarmony ArkUI 仓颉版 CheckboxGroup 组件详解:多选框群组的创建、全选控制与 onChange 回调实践

原创2026-10-15 16:36:531,815 阅读
文章标签:文档知识库

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)
            }
        }
    }
}

该示例体现的要点:

  1. 三处 group: "checkboxGroup" 构成同一群组:CheckboxGroup 与 checkbox1、checkbox2 两个 Checkbox 的 group 命名一致,是绑定关系成立的前提;
  2. .selectAll(false) 声明初始状态下群组内无全选(初始值本身也是 false,此处为显式声明);
  3. .onChange({ val => ... }) 中 val 即 CheckboxGroupResult,通过 val.name 拿到当前所有被选中项的名称数组,formatNames 将其拼接为 "checkbox1;checkbox2;" 这类字符串后走 Hilog.info(domain 0、tag CangjieTest)输出日志;
  4. 子项 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 的配合要点与常见注意事项

  1. group 命名必须严格一致:CheckboxGroup(group: "x") 与 Checkbox(group: "x") 大小写、拼写完全相同才会被识别为同一群组,否则全选控制不生效。
  2. 优先级:Checkbox.select 显式设置 > CheckboxGroup.selectAll。需要对个别项做"例外"处理时,在子项上显式调用 select。
  3. 名称是回调数据的唯一标识:CheckboxGroupResult.name 返回的是 Checkbox 的 name 参数值,因此务必给每个子项设置有意义的 name,否则回调中无法区分具体项。
  4. 三态判断:onChange 中建议结合 val.status(All/Part/None)与 val.name 做业务分支,例如 status == SelectStatus.All 时展示"全选成功"提示,Part 时展示已选数量。
  5. 带缓存容器场景:Checkbox 放入 List 等带缓存/按需创建的组件时,未被创建的项的选中状态需要应用层手动控制(如把选中集合维护在状态数据中,创建节点时按数据初始化 select)。
  6. 默认值回顾: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 参考文档。

登录后查看全文
CangjieCorpus