输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
RelativeContainer
CustomDialogController
animateTo
CTRL+K
文档管理中心

HarmonyOS 5.0.0(12)

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
RelativeContainer
CustomDialogController
animateTo
CTRL+K
API参考
高级筛选
Created with Pixso.
元服务API集不筛选
您当前浏览的HarmonyOS 5.0.0(API 12)文档归档不再维护，推荐您使用最新版本。详细请参考文档维护策略变更。
API参考应用框架ArkUI（方舟UI框架）ArkTS组件按钮与选择CheckboxGroup

CheckboxGroup

更新时间: 2025-03-17 00:08
本文导读
展开章节

多选框群组，用于控制多选框全选或者不全选状态。

说明

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

CheckboxGroup(options?: CheckboxGroupOptions)

创建多选框群组，可以控制群组内的Checkbox全选或者不全选，group值相同的Checkbox和CheckboxGroup为同一群组。

在结合带缓存组件使用时(如List)，未被创建的Checkbox选中状态需要应用手动控制。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
options CheckboxGroupOptions 否 配置多选框群组参数。

CheckboxGroupOptions对象说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
group string 否

群组名称。

说明：

多个相同群组名称的CheckboxGroup，仅第一个CheckboxGroup生效。

属性

除支持通用属性外，还支持以下属性：

selectAll

selectAll(value: boolean)

设置是否全选。若同组的Checkbox显式设置了select属性，则Checkbox的优先级高。

从API version 10开始，该属性支持$$双向绑定变量。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value boolean 是

是否全选。

默认值：false

selectedColor

selectedColor(value: ResourceColor)

设置被选中或部分选中状态的颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value ResourceColor 是

被选中或部分选中状态的颜色。

默认值：$r('sys.color.ohos_id_color_text_primary_activated')

异常值按照默认值处理。

unselectedColor10+

unselectedColor(value: ResourceColor)

设置非选中状态边框颜色。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value ResourceColor 是

非选中状态边框颜色。

默认值：$r('sys.color.ohos_id_color_switch_outline_off')。

mark10+

mark(value: MarkStyle)

设置多选框内部图标样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value MarkStyle 是 多选框内部图标样式。

checkboxShape12

checkboxShape(value: CheckBoxShape)

设置CheckboxGroup组件形状， 包括圆形和圆角方形。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value CheckBoxShape 是

设置CheckboxGroup组件形状， 包括圆形和圆角方形。

默认值:CheckBoxShape.CIRCLE。

说明：

CheckboxGroup组件形状按照设置显示。

CheckboxGroup内所有没有单独设置shape类型的Checkbox形状和CheckboxGroup的保持一致。

CheckboxGroup内有单独设置shape类型的Checkbox形状则优先于CheckboxGroup，按照设置形状显示。

事件

除支持通用事件外，还支持以下事件：

onChange

onChange(callback: (event: CheckboxGroupResult) => void )

CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
event CheckboxGroupResult 是 多选框群组的信息。

CheckboxGroupResult对象说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
name Array<string> 否 否 群组内所有被选中的多选框名称。
status SelectStatus 否 否 选中状态。

SelectStatus枚举说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 描述
All 群组多选择框全部选择。
Part 群组多选择框部分选择。
None 群组多选择框全部没有选择。

示例

示例1（设置多选框群组）

该示例用于控制多选框全选或者不全选状态。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct CheckboxExample {
  5.   build() {
  6.     Scroll() {
  7.       Column() {
  8.         // 全选按钮
  9.         Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
  10.           CheckboxGroup({ group: 'checkboxGroup' })
  11.             .checkboxShape(CheckBoxShape.ROUNDED_SQUARE)
  12.             .selectedColor('#007DFF')
  13.             .onChange((itemName: CheckboxGroupResult) => {
  14.               console.info("checkbox group content" + JSON.stringify(itemName))
  15.             })
  16.           Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
  17.         }
  18. 

  19.         // 选项1
  20.         Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
  21.           Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
  22.             .selectedColor('#007DFF')
  23.             .shape(CheckBoxShape.ROUNDED_SQUARE)
  24.             .onChange((value: boolean) => {
  25.               console.info('Checkbox1 change is' + value)
  26.             })
  27.           Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
  28.         }.margin({ left: 36 })
  29. 

  30.         // 选项2
  31.         Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
  32.           Checkbox({ name: 'checkbox2', group: 'checkboxGroup' })
  33.             .selectedColor('#007DFF')
  34.             .shape(CheckBoxShape.ROUNDED_SQUARE)
  35.             .onChange((value: boolean) => {
  36.               console.info('Checkbox2 change is' + value)
  37.             })
  38.           Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
  39.         }.margin({ left: 36 })
  40. 

  41.         // 选项3
  42.         Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
  43.           Checkbox({ name: 'checkbox3', group: 'checkboxGroup' })
  44.             .selectedColor('#007DFF')
  45.             .shape(CheckBoxShape.ROUNDED_SQUARE)
  46.             .onChange((value: boolean) => {
  47.               console.info('Checkbox3 change is' + value)
  48.             })
  49.           Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
  50.         }.margin({ left: 36 })
  51.       }
  52.     }
  53.   }
  54. }

示例2（自定义勾选样式）

该示例通过配置mark实现自定义多选框群组的勾选样式。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct Index {
  5. 

  6.   build() {
  7.     Row() {
  8.       Column() {
  9.         Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
  10.           CheckboxGroup({ group: 'checkboxGroup' })
  11.             .checkboxShape(CheckBoxShape.ROUNDED_SQUARE)
  12.             .selectedColor(Color.Orange)
  13.             .onChange((itemName: CheckboxGroupResult) => {
  14.               console.info("checkbox group content" + JSON.stringify(itemName))
  15.             })
  16.             .mark({
  17.               strokeColor:Color.Black,
  18.               size: 40,
  19.               strokeWidth: 5
  20.             })
  21.             .unselectedColor(Color.Red)
  22.             .width(30)
  23.             .height(30)
  24.           Text('Select All').fontSize(20)
  25.         }.margin({right:15})
  26.         Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
  27.           Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
  28.             .selectedColor(0x39a2db)
  29.             .shape(CheckBoxShape.ROUNDED_SQUARE)
  30.             .onChange((value: boolean) => {
  31.               console.info('Checkbox1 change is'+ value)
  32.             })
  33.             .mark({
  34.               strokeColor:Color.Black,
  35.               size: 50,
  36.               strokeWidth: 5
  37.             })
  38.             .unselectedColor(Color.Red)
  39.             .width(30)
  40.             .height(30)
  41.           Text('Checkbox1').fontSize(20)
  42.         }
  43.         Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
  44.           Checkbox({ name: 'checkbox2', group: 'checkboxGroup' })
  45.             .selectedColor(0x39a2db)
  46.             .shape(CheckBoxShape.ROUNDED_SQUARE)
  47.             .onChange((value: boolean) => {
  48.               console.info('Checkbox2 change is' + value)
  49.             })
  50.             .width(30)
  51.             .height(30)
  52.           Text('Checkbox2').fontSize(20)
  53.         }
  54.         Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
  55.           Checkbox({ name: 'checkbox3', group: 'checkboxGroup' })
  56.             .selectedColor(0x39a2db)
  57.             .shape(CheckBoxShape.ROUNDED_SQUARE)
  58.             .onChange((value: boolean) => {
  59.               console.info('Checkbox3 change is' + value)
  60.             })
  61.             .width(30)
  62.             .height(30)
  63.           Text('Checkbox3').fontSize(20)
  64.         }
  65.       }
  66.       .width('100%')
  67.     }
  68.     .height('100%')
  69.   }
  70. }

Checkbox
CalendarPicker
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词