# CheckboxGroup 多选框群组，用于控制多选框全选或者不全选状态。 > **说明：** > > 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 ## 子组件 无 ## 接口 CheckboxGroup(options?: CheckboxGroupOptions) 创建多选框群组，用于控制群组内Checkbox的全选或取消全选状态，具有相同group值的Checkbox和CheckboxGroup属于同一群组。 在结合带缓存组件使用时(如List)，未被创建的Checkbox选中状态需要应用手动控制。详细示例请参考[示例3](#示例3设置全选)。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------- | ----------------------------------------------------- | ---- | -------------------- | | options | [CheckboxGroupOptions](#checkboxgroupoptions对象说明) | 否 | 配置多选框群组参数。 | ## CheckboxGroupOptions对象说明 多选框群组的信息。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 只读 | 可选 | 说明 | | -------- | -------- | -------- | -------- | -------- | | group | string | 否 | 是 | 群组名称。
**说明：**
具有相同群组名称的多个CheckboxGroup，仅第一个CheckboxGroup生效。 | ## 属性 除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： ### selectAll selectAll(value: boolean) 设置是否全选。若同组的[Checkbox](ts-basic-components-checkbox.md)显式设置了select属性，则Checkbox的优先级高。 在与带有缓存功能的组件（如[List](ts-container-list.md)）配合使用时，未创建的Checkbox选中状态需由开发者控制。 从API version 10开始，该属性支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。 从API version 18开始，该属性支持[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------- | ---- | ------------------------------------------------------------ | | value | boolean | 是 | 是否全选。
默认值：false
值为true时，多选框群组将全部被选中；值为false时，多选框群组将全部取消选中。 | ### selectAll18+ selectAll(isAllSelected: Optional\) 设置是否全选。若同组的[Checkbox](ts-basic-components-checkbox.md)显式设置了select属性，则Checkbox的优先级高。与[selectAll](#selectall)相比，isAllSelected参数新增了对undefined类型的支持。 在与带有缓存功能的组件（如[List](ts-container-list.md)）配合使用时，未创建的Checkbox选中状态需由开发者控制。 该属性支持[$$](../../../ui/state-management/arkts-two-way-sync.md)、[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。 **卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | isAllSelected | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\ | 是 | 是否全选。
当isAllSelected的值为undefined时取默认值false。
值为true时，多选框群组将全部被选中；值为false时，多选框群组将全部取消选中。 | ### selectedColor selectedColor(value: ResourceColor) 设置被选中或部分选中状态的颜色。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | | value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 被选中或部分选中状态的颜色。
默认值：$r('sys.color.ohos_id_color_text_primary_activated')
异常值按照默认值处理。 | ### selectedColor18+ selectedColor(resColor: Optional\) 设置被选中或部分选中状态的颜色。与[selectedColor](#selectedcolor)相比，resColor参数新增了对undefined类型的支持。 **卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | resColor | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 被选中或部分选中状态的颜色。
当resColor的值为undefined时，默认值：$r('sys.color.ohos_id_color_text_primary_activated')
异常值按照默认值处理。 | ### unselectedColor10+ unselectedColor(value: ResourceColor) 设置非选中状态边框颜色。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | | value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 非选中状态边框颜色。
默认值：$r('sys.color.ohos_id_color_switch_outline_off')。 | ### unselectedColor18+ unselectedColor(resColor: Optional\) 设置非选中状态边框颜色。与[unselectedColor](#unselectedcolor10)10+相比，resColor参数新增了对undefined类型的支持。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | resColor | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 非选中状态边框颜色。
当resColor的值为undefined时，默认值：$r('sys.color.ohos_id_color_switch_outline_off')。 | ### mark10+ mark(value: MarkStyle) 设置多选框内部图标样式。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------------------------------------- | ---- | -------------------- | | value | [MarkStyle](ts-types.md#markstyle10对象说明) | 是 | 多选框内部图标样式。 | ### mark18+ mark(style: Optional\) 设置多选框内部图标样式。与[mark](#mark10)10+相比，style参数新增了对undefined类型的支持。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | style | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[MarkStyle](ts-types.md#markstyle10对象说明)> | 是 | 多选框内部图标样式。
当style的值为undefined时，维持上次取值。 | ### checkboxShape12+ checkboxShape(value: CheckBoxShape) 设置CheckboxGroup组件形状，包括圆形和圆角方形。 **卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | | value | [CheckBoxShape](ts-appendix-enums.md#checkboxshape11) | 是 | 设置CheckboxGroup组件形状，包括圆形和圆角方形。
默认值：CheckBoxShape.CIRCLE
**说明：**
CheckboxGroup组件将按照设置的形状显示。
CheckboxGroup内所有未单独设置shape类型的Checkbox，其形状将与CheckboxGroup保持一致。
CheckboxGroup内已单独设置shape类型的Checkbox，其形状将优先于CheckboxGroup的设置，按照自身设置显示。 | ### checkboxShape18+ checkboxShape(shape: Optional\) 设置CheckboxGroup组件形状，包括圆形和圆角方形。与[checkboxShape](#checkboxshape12)12+相比，shape参数新增了对undefined类型的支持。 **卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | shape | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[CheckBoxShape](ts-appendix-enums.md#checkboxshape11)> | 是 | 设置CheckboxGroup组件形状，包括圆形和圆角方形。
当shape的值为undefined时，默认值为CheckBoxShape.CIRCLE。
**说明：**
CheckboxGroup组件将按照设置的形状显示。
CheckboxGroup内所有未单独设置shape类型的Checkbox，其形状将与CheckboxGroup保持一致。
CheckboxGroup内已单独设置shape类型的Checkbox，其形状将优先于CheckboxGroup的设置，按照自身设置显示。 | ## 事件 除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： ### onChange onChange(callback: OnCheckboxGroupChangeCallback) CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------ | | callback | [OnCheckboxGroupChangeCallback](#oncheckboxgroupchangecallback18) | 是 | 多选框群组的信息。 | ### onChange18+ onChange(callback: Optional\) CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。与[onChange](#onchange)相比，callback参数新增了对undefined类型的支持。 **卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | callback | [Optional](ts-universal-attributes-custom-property.md#optionalt12)\<[OnCheckboxGroupChangeCallback](#oncheckboxgroupchangecallback18)> | 是 | 多选框群组的信息。
当callback的值为undefined时，不使用回调函数。 | ## OnCheckboxGroupChangeCallback18+ type OnCheckboxGroupChangeCallback = (value: CheckboxGroupResult) => void 多选框群组的信息。 **卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | --------------------------------------------------- | ---- | ------------------ | | value | [CheckboxGroupResult](#checkboxgroupresult对象说明) | 是 | 多选框群组的信息。 | ## CheckboxGroupResult对象说明 多选框群组的名称和状态。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 类型 | 只读 | 可选 | 说明 | | ------ | ------ | ------- | ------- | ------- | | name | Array<string> | 否 | 否 | 群组内所有被选中的多选框名称。 | | status | [SelectStatus](#selectstatus枚举说明) | 否 | 否 | 选中状态。 | ## SelectStatus枚举说明 多选框群组的选中状态。 **卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 **原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 **系统能力：** SystemCapability.ArkUI.ArkUI.Full | 名称 | 说明 | | ----- | -------------------- | | All | 群组多选择框全部选择。 | | Part | 群组多选择框部分选择。 | | None | 群组多选择框全部没有选择。 | ## 示例 ### 示例1（设置多选框群组） 该示例用于控制多选框全选或者不全选状态。 ```ts // xxx.ets @Entry @Component struct CheckboxExample { build() { Scroll() { Column() { // 全选按钮 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { CheckboxGroup({ group: 'checkboxGroup' }) .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) .selectedColor('#007DFF') .onChange((itemName: CheckboxGroupResult) => { console.info("checkbox group content" + JSON.stringify(itemName)); }) Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) } // 选项1 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) .selectedColor('#007DFF') .shape(CheckBoxShape.ROUNDED_SQUARE) .onChange((value: boolean) => { console.info('Checkbox1 change is' + value); }) Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) }.margin({ left: 36 }) // 选项2 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) .selectedColor('#007DFF') .shape(CheckBoxShape.ROUNDED_SQUARE) .onChange((value: boolean) => { console.info('Checkbox2 change is' + value); }) Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) }.margin({ left: 36 }) // 选项3 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) .selectedColor('#007DFF') .shape(CheckBoxShape.ROUNDED_SQUARE) .onChange((value: boolean) => { console.info('Checkbox3 change is' + value); }) Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) }.margin({ left: 36 }) } } } } ``` ![checkboxGroup](figures/checkboxGroup.gif) ### 示例2（自定义勾选样式） 该示例通过配置mark实现自定义多选框群组的勾选样式。 ```ts // xxx.ets @Entry @Component struct Index { build() { Row() { Column() { Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { CheckboxGroup({ group: 'checkboxGroup' }) .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) .selectedColor(Color.Orange) .onChange((itemName: CheckboxGroupResult) => { console.info("checkbox group content" + JSON.stringify(itemName)); }) .mark({ strokeColor:Color.Black, size: 40, strokeWidth: 5 }) .unselectedColor(Color.Red) .width(30) .height(30) Text('Select All').fontSize(20) }.margin({right:15}) Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) .selectedColor(0x39a2db) .shape(CheckBoxShape.ROUNDED_SQUARE) .onChange((value: boolean) => { console.info('Checkbox1 change is'+ value); }) .mark({ strokeColor:Color.Black, size: 50, strokeWidth: 5 }) .unselectedColor(Color.Red) .width(30) .height(30) Text('Checkbox1').fontSize(20) } Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) .selectedColor(0x39a2db) .shape(CheckBoxShape.ROUNDED_SQUARE) .onChange((value: boolean) => { console.info('Checkbox2 change is' + value); }) .width(30) .height(30) Text('Checkbox2').fontSize(20) } Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) .selectedColor(0x39a2db) .shape(CheckBoxShape.ROUNDED_SQUARE) .onChange((value: boolean) => { console.info('Checkbox3 change is' + value); }) .width(30) .height(30) Text('Checkbox3').fontSize(20) } } .width('100%') } .height('100%') } } ``` ![checkboxGroup](figures/checkboxGroup2.gif) ### 示例3（设置全选） 该示例实现了在结合带缓存功能的组件使用时(如List)，未被创建的Checkbox全选的功能。 ```ts class BasicDataSource implements IDataSource { private listeners: DataChangeListener[] = []; private originDataArray: checkboxItemData[] = []; public totalCount(): number { return this.originDataArray.length; } public getData(index: number): checkboxItemData { return this.originDataArray[index]; } registerDataChangeListener(listener: DataChangeListener): void { if (this.listeners.indexOf(listener) < 0) { console.info('add listener'); this.listeners.push(listener); } } unregisterDataChangeListener(listener: DataChangeListener): void { const pos = this.listeners.indexOf(listener); if (pos >= 0) { console.info('remove listener'); this.listeners.splice(pos, 1); } } notifyDataReload(): void { this.listeners.forEach(listener => { listener.onDataReloaded(); }); } notifyDataAdd(index: number): void { this.listeners.forEach(listener => { listener.onDataAdd(index); }); } notifyDataChange(index: number): void { this.listeners.forEach(listener => { listener.onDataChange(index); }); } notifyDataDelete(index: number): void { this.listeners.forEach(listener => { listener.onDataDelete(index); }); } notifyDataMove(from: number, to: number): void { this.listeners.forEach(listener => { listener.onDataMove(from, to); }); } notifyDatasetChange(operations: DataOperation[]): void { this.listeners.forEach(listener => { listener.onDatasetChange(operations); }); } } interface checkboxItemData { isCheck: boolean; itemName: string; } class MyDataSource extends BasicDataSource { private dataArray: checkboxItemData[] = []; public totalCount(): number { return this.dataArray.length; } public getData(index: number): checkboxItemData { return this.dataArray[index]; } public pushData(data: checkboxItemData): void { this.dataArray.push(data); this.notifyDataAdd(this.dataArray.length - 1); } public operateData(isSelect: boolean): void { this.dataArray.forEach((item) => { item.isCheck = isSelect }) this.notifyDataReload() } public operateItem(isSelect: boolean, index: number): void { this.dataArray[index].isCheck = isSelect this.notifyDataChange(index) } public getDataSource(): checkboxItemData[] { return this.dataArray } } @Entry @Component struct MyComponent { private data: MyDataSource = new MyDataSource(); aboutToAppear() { for (let i = 0; i <= 100; i++) { this.data.pushData({ isCheck: false, itemName: `checkbox ${i}` }); } } @State isSelectAll: boolean = false build() { Column() { Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { CheckboxGroup({ group: "group" }) .selectAll(this.isSelectAll) .hitTestBehavior(HitTestMode.None) Text("全选").fontSize(25) }.onClick(() => { this.isSelectAll = !this.isSelectAll this.data.operateData(this.isSelectAll) }).padding({ left: 10 }) List({ space: 3 }) { LazyForEach(this.data, (item: checkboxItemData, index: number) => { ListItem() { Row() { Checkbox({ name: `checkbox-${item}` }) .select(item.isCheck) .onChange((value: boolean) => { this.data.operateItem(value, index) let dataSource = this.data.getDataSource() this.isSelectAll = dataSource.every((item) => item.isCheck === true) }) Text(item.itemName).fontSize(20) }.margin({ left: 10, right: 10 }) } }, (item: checkboxItemData) => item.itemName + item.isCheck) }.cachedCount(5) } } } ``` ![checkboxgroup04](figures/checkboxgroup04.gif)