1# CheckboxGroup 2 3多选框群组，用于控制多选框全选或者不全选状态。 4 5> **说明：** 6> 7> 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 子组件 10 11无 12 13## 接口 14 15CheckboxGroup(options?: CheckboxGroupOptions) 16 17创建多选框群组，可以控制群组内的Checkbox全选或者不全选，group值相同的Checkbox和CheckboxGroup为同一群组。 18 19在结合带缓存组件使用时(如List)，未被创建的Checkbox选中状态需要应用手动控制。 20 21**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 22 23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 24 25**系统能力：** SystemCapability.ArkUI.ArkUI.Full 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------- | ----------------------------------------------------- | ---- | -------------------- | 31| options | [CheckboxGroupOptions](#checkboxgroupoptions对象说明) | 否 | 配置多选框群组参数。 | 32 33## CheckboxGroupOptions对象说明 34 35**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 36 37**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 38 39**系统能力：** SystemCapability.ArkUI.ArkUI.Full 40 41| 名称 | 类型 | 必填 | 说明 | 42| -------- | -------- | -------- | -------- | 43| group | string | 否 | 群组名称。<br/>**说明：** <br/>多个相同群组名称的CheckboxGroup，仅第一个CheckboxGroup生效。 | 44 45## 属性 46 47除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 48 49### selectAll 50 51selectAll(value: boolean) 52 53设置是否全选。若同组的[Checkbox](ts-basic-components-checkbox.md)显式设置了select属性，则Checkbox的优先级高。 54 55从API version 10开始，该属性支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。 56从API version 18开始，该属性支持[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。 57 58**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 59 60**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 61 62**系统能力：** SystemCapability.ArkUI.ArkUI.Full 63 64**参数：** 65 66| 参数名 | 类型 | 必填 | 说明 | 67| ------ | ------- | ---- | ------------------------------------------------------------ | 68| value | boolean | 是 | 是否全选。<br/>默认值：false<br/>值为true时，多选框群组都被选中。值为false时，多选框群组都不被选中。 | 69 70### selectAll<sup>18+</sup> 71 72selectAll(isAllSelected: Optional\<boolean>) 73 74设置是否全选。若同组的[Checkbox](ts-basic-components-checkbox.md)显式设置了select属性，则Checkbox的优先级高。与[selectAll](#selectall)相比，isAllSelected参数新增了对undefined类型的支持。 75 76该属性支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。 77该属性支持[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。 78 79**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 80 81**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 82 83**系统能力：** SystemCapability.ArkUI.ArkUI.Full 84 85**参数：** 86 87| 参数名 | 类型 | 必填 | 说明 | 88| ------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 89| isAllSelected | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 是否全选。<br/>当isAllSelected的值为undefined时取默认值false。<br/>值为true时，多选框群组都被选中。值为false时，多选框群组都不被选中。 | 90 91### selectedColor 92 93selectedColor(value: ResourceColor) 94 95设置被选中或部分选中状态的颜色。 96 97**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 98 99**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 100 101**系统能力：** SystemCapability.ArkUI.ArkUI.Full 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 107| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 被选中或部分选中状态的颜色。<br/>默认值：$r('sys.color.ohos_id_color_text_primary_activated')<br/>异常值按照默认值处理。 | 108 109### selectedColor<sup>18+</sup> 110 111selectedColor(resColor: Optional\<ResourceColor>) 112 113设置被选中或部分选中状态的颜色。与[selectedColor](#selectedcolor)相比，resColor参数新增了对undefined类型的支持。 114 115**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 116 117**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 118 119**系统能力：** SystemCapability.ArkUI.ArkUI.Full 120 121**参数：** 122 123| 参数名 | 类型 | 必填 | 说明 | 124| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 125| resColor | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 被选中或部分选中状态的颜色。<br/>当resColor的值为undefined时，默认值：$r('sys.color.ohos_id_color_text_primary_activated')<br/>异常值按照默认值处理。 | 126 127### unselectedColor<sup>10+</sup> 128 129unselectedColor(value: ResourceColor) 130 131设置非选中状态边框颜色。 132 133**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137**参数：** 138 139| 参数名 | 类型 | 必填 | 说明 | 140| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 141| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 非选中状态边框颜色。<br/>默认值：$r('sys.color.ohos_id_color_switch_outline_off')。 | 142 143### unselectedColor<sup>18+</sup> 144 145unselectedColor(resColor: Optional\<ResourceColor>) 146 147设置非选中状态边框颜色。与[unselectedColor](#unselectedcolor10)<sup>10+</sup>相比，resColor参数新增了对undefined类型的支持。 148 149**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 150 151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 152 153**参数：** 154 155| 参数名 | 类型 | 必填 | 说明 | 156| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 157| resColor | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[ResourceColor](ts-types.md#resourcecolor)> | 是 | 非选中状态边框颜色。<br/>当resColor的值为undefined时，默认值：$r('sys.color.ohos_id_color_switch_outline_off')。 | 158 159### mark<sup>10+</sup> 160 161mark(value: MarkStyle) 162 163设置多选框内部图标样式。 164 165**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 166 167**系统能力：** SystemCapability.ArkUI.ArkUI.Full 168 169**参数：** 170 171| 参数名 | 类型 | 必填 | 说明 | 172| ------ | -------------------------------------------- | ---- | -------------------- | 173| value | [MarkStyle](ts-types.md#markstyle10对象说明) | 是 | 多选框内部图标样式。 | 174 175### mark<sup>18+</sup> 176 177mark(style: Optional\<MarkStyle>) 178 179设置多选框内部图标样式。与[mark](#mark10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 180 181**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 189| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[MarkStyle](ts-types.md#markstyle10对象说明)> | 是 | 多选框内部图标样式。<br/>当style的值为undefined时，维持上次取值。 | 190 191### checkboxShape<sup>12+</sup> 192 193checkboxShape(value: CheckBoxShape) 194 195设置CheckboxGroup组件形状， 包括圆形和圆角方形。 196 197**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 198 199**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 200 201**系统能力：** SystemCapability.ArkUI.ArkUI.Full 202 203**参数：** 204 205| 参数名 | 类型 | 必填 | 说明 | 206| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 207| value | [CheckBoxShape](ts-appendix-enums.md#checkboxshape11) | 是 | 设置CheckboxGroup组件形状， 包括圆形和圆角方形。<br/>默认值：CheckBoxShape.CIRCLE <br />**说明**：<br/>CheckboxGroup组件形状按照设置显示。<br/>CheckboxGroup内所有没有单独设置shape类型的Checkbox形状和CheckboxGroup的保持一致。<br/>CheckboxGroup内有单独设置shape类型的Checkbox形状则优先于CheckboxGroup，按照设置形状显示。 | 208 209### checkboxShape<sup>18+</sup> 210 211checkboxShape(shape: Optional\<CheckBoxShape>) 212 213设置CheckboxGroup组件形状， 包括圆形和圆角方形。与[checkboxShape](#checkboxshape12)<sup>12+</sup>相比，shape参数新增了对undefined类型的支持。 214 215**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 216 217**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 218 219**系统能力：** SystemCapability.ArkUI.ArkUI.Full 220 221**参数：** 222 223| 参数名 | 类型 | 必填 | 说明 | 224| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 225| shape | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CheckBoxShape](ts-appendix-enums.md#checkboxshape11)> | 是 | 设置CheckboxGroup组件形状， 包括圆形和圆角方形。<br/>当shape的值为undefined时，默认值为CheckBoxShape.CIRCLE。 <br />**说明**：<br/>CheckboxGroup组件形状按照设置显示。<br/>CheckboxGroup内所有没有单独设置shape类型的Checkbox形状和CheckboxGroup的保持一致。<br/>CheckboxGroup内有单独设置shape类型的Checkbox形状则优先于CheckboxGroup，按照设置形状显示。 | 226 227## 事件 228 229除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 230 231### onChange 232 233onChange(callback: OnCheckboxGroupChangeCallback) 234 235CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。 236 237**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 238 239**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 240 241**系统能力：** SystemCapability.ArkUI.ArkUI.Full 242 243**参数：** 244 245| 参数名 | 类型 | 必填 | 说明 | 246| -------- | ------------------------------------------------------------ | ---- | ------------------ | 247| callback | [OnCheckboxGroupChangeCallback](#oncheckboxgroupchangecallback18) | 是 | 多选框群组的信息。 | 248 249### onChange<sup>18+</sup> 250 251onChange(callback: Optional\<OnCheckboxGroupChangeCallback>) 252 253CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。与[onChange](#onchange)相比，callback参数新增了对undefined类型的支持。 254 255**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 256 257**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 258 259**系统能力：** SystemCapability.ArkUI.ArkUI.Full 260 261**参数：** 262 263| 参数名 | 类型 | 必填 | 说明 | 264| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 265| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[OnCheckboxGroupChangeCallback](#oncheckboxgroupchangecallback18)> | 是 | 多选框群组的信息。<br/>当callback的值为undefined时，不使用回调函数。 | 266 267## OnCheckboxGroupChangeCallback<sup>18+</sup> 268 269type OnCheckboxGroupChangeCallback = (value: CheckboxGroupResult) => void 270 271多选框群组的信息。 272 273**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 274 275**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 276 277**系统能力：** SystemCapability.ArkUI.ArkUI.Full 278 279**参数：** 280 281| 参数名 | 类型 | 必填 | 说明 | 282| ------ | --------------------------------------------------- | ---- | ------------------ | 283| value | [CheckboxGroupResult](#checkboxgroupresult对象说明) | 是 | 多选框群组的信息。 | 284 285## CheckboxGroupResult对象说明 286 287**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 288 289**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 290 291**系统能力：** SystemCapability.ArkUI.ArkUI.Full 292 293| 名称 | 类型 | 只读 | 可选 | 说明 | 294| ------ | ------ | ------- | ------- | ------- | 295| name | Array<string> | 否 | 否 | 群组内所有被选中的多选框名称。 | 296| status | [SelectStatus](#selectstatus枚举说明) | 否 | 否 | 选中状态。 | 297 298## SelectStatus枚举说明 299 300**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 301 302**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 303 304**系统能力：** SystemCapability.ArkUI.ArkUI.Full 305 306| 名称 | 说明 | 307| ----- | -------------------- | 308| All | 群组多选择框全部选择。 | 309| Part | 群组多选择框部分选择。 | 310| None | 群组多选择框全部没有选择。 | 311 312## 示例 313 314### 示例1（设置多选框群组） 315 316该示例用于控制多选框全选或者不全选状态。 317 318```ts 319// xxx.ets 320@Entry 321@Component 322struct CheckboxExample { 323 build() { 324 Scroll() { 325 Column() { 326 // 全选按钮 327 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 328 CheckboxGroup({ group: 'checkboxGroup' }) 329 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 330 .selectedColor('#007DFF') 331 .onChange((itemName: CheckboxGroupResult) => { 332 console.info("checkbox group content" + JSON.stringify(itemName)); 333 }) 334 Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 335 } 336 337 // 选项1 338 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 339 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 340 .selectedColor('#007DFF') 341 .shape(CheckBoxShape.ROUNDED_SQUARE) 342 .onChange((value: boolean) => { 343 console.info('Checkbox1 change is' + value); 344 }) 345 Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 346 }.margin({ left: 36 }) 347 348 // 选项2 349 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 350 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 351 .selectedColor('#007DFF') 352 .shape(CheckBoxShape.ROUNDED_SQUARE) 353 .onChange((value: boolean) => { 354 console.info('Checkbox2 change is' + value); 355 }) 356 Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 357 }.margin({ left: 36 }) 358 359 // 选项3 360 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 361 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 362 .selectedColor('#007DFF') 363 .shape(CheckBoxShape.ROUNDED_SQUARE) 364 .onChange((value: boolean) => { 365 console.info('Checkbox3 change is' + value); 366 }) 367 Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 368 }.margin({ left: 36 }) 369 } 370 } 371 } 372} 373``` 374 375 376### 示例2（自定义勾选样式） 377 378该示例通过配置mark实现自定义多选框群组的勾选样式。 379 380```ts 381// xxx.ets 382@Entry 383@Component 384struct Index { 385 386 build() { 387 Row() { 388 Column() { 389 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 390 CheckboxGroup({ group: 'checkboxGroup' }) 391 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 392 .selectedColor(Color.Orange) 393 .onChange((itemName: CheckboxGroupResult) => { 394 console.info("checkbox group content" + JSON.stringify(itemName)); 395 }) 396 .mark({ 397 strokeColor:Color.Black, 398 size: 40, 399 strokeWidth: 5 400 }) 401 .unselectedColor(Color.Red) 402 .width(30) 403 .height(30) 404 Text('Select All').fontSize(20) 405 }.margin({right:15}) 406 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 407 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 408 .selectedColor(0x39a2db) 409 .shape(CheckBoxShape.ROUNDED_SQUARE) 410 .onChange((value: boolean) => { 411 console.info('Checkbox1 change is'+ value); 412 }) 413 .mark({ 414 strokeColor:Color.Black, 415 size: 50, 416 strokeWidth: 5 417 }) 418 .unselectedColor(Color.Red) 419 .width(30) 420 .height(30) 421 Text('Checkbox1').fontSize(20) 422 } 423 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 424 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 425 .selectedColor(0x39a2db) 426 .shape(CheckBoxShape.ROUNDED_SQUARE) 427 .onChange((value: boolean) => { 428 console.info('Checkbox2 change is' + value); 429 }) 430 .width(30) 431 .height(30) 432 Text('Checkbox2').fontSize(20) 433 } 434 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 435 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 436 .selectedColor(0x39a2db) 437 .shape(CheckBoxShape.ROUNDED_SQUARE) 438 .onChange((value: boolean) => { 439 console.info('Checkbox3 change is' + value); 440 }) 441 .width(30) 442 .height(30) 443 Text('Checkbox3').fontSize(20) 444 } 445 } 446 .width('100%') 447 } 448 .height('100%') 449 } 450} 451``` 452 453 454 455
