1# Checkbox 2 3提供多选框组件，通常用于某选项的打开或关闭。 4 5> **说明：** 6> 7> API version 11开始，Checkbox默认样式由圆角方形变为圆形。 8> 9> 该组件从API version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 10 11## 子组件 12 13无 14 15## 接口 16 17Checkbox(options?: CheckboxOptions) 18 19多选框组件。 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 | [CheckboxOptions](#checkboxoptions对象说明) | 否 | 配置多选框的参数。 | 32 33## CheckboxOptions对象说明 34 35多选框的信息。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39| 名称 | 类型 | 必填 | 说明 | 40| --------| --------| ------ | -------- | 41| name | string | 否 | 用于指定多选框名称。 <br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 42| group | string | 否 | 用于指定多选框所属群组的名称（即所属CheckboxGroup的名称）。<br/>**说明：** <br/>未配合使用[CheckboxGroup](ts-basic-components-checkboxgroup.md)组件时，此值无用。 <br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| indicatorBuilder<sup>12+</sup> | [CustomBuilder](ts-types.md#custombuilder8) | 否 | 配置多选框的选中样式为自定义组件。自定义组件与Checkbox组件为中心点对齐显示。indicatorBuilder设置为undefined/null时，默认为indicatorBuilder未设置状态。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 44 45## 属性 46 47除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 48 49### select 50 51select(value: boolean) 52 53设置多选框是否选中。 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### select<sup>18+</sup> 71 72select(isSelected: Optional\<boolean>) 73 74设置多选框是否选中。与[select](#select)相比，isSelected参数新增了对undefined类型的支持。 75 76该属性支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。该属性支持[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。 77 78**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 79 80**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 81 82**系统能力：** SystemCapability.ArkUI.ArkUI.Full 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 88| isSelected | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | 是 | 多选框是否选中。<br/>当isSelected的值为undefined时取默认值false。<br/>值为true时，多选框被选中。值为false时，多选框不被选中。 | 89 90### selectedColor 91 92selectedColor(value: ResourceColor) 93 94设置多选框选中状态颜色。 95 96**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 97 98**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 99 100**系统能力：** SystemCapability.ArkUI.ArkUI.Full 101 102**参数：** 103 104| 参数名 | 类型 | 必填 | 说明 | 105| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 106| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 多选框选中状态颜色。<br/>默认值：$r('sys.color.ohos_id_color_text_primary_activated')。<br/>异常值按照默认值处理。 | 107 108### selectedColor<sup>18+</sup> 109 110selectedColor(resColor: Optional\<ResourceColor>) 111 112设置多选框选中状态颜色。与[selectedColor](#selectedcolor)相比，resColor参数新增了对undefined类型的支持。 113 114**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 115 116**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 117 118**系统能力：** SystemCapability.ArkUI.ArkUI.Full 119 120**参数：** 121 122| 参数名 | 类型 | 必填 | 说明 | 123| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 124| 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/>异常值按照默认值处理。 | 125 126### unselectedColor<sup>10+</sup> 127 128unselectedColor(value: ResourceColor) 129 130设置多选框非选中状态边框颜色。 131 132**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 133 134**系统能力：** SystemCapability.ArkUI.ArkUI.Full 135 136**参数：** 137 138| 参数名 | 类型 | 必填 | 说明 | 139| ------ | ------------------------------------------ | ---- | -------------------------- | 140| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 多选框非选中状态边框颜色。<br/>默认值：$r('sys.color.ohos_id_color_switch_outline_off')。 | 141 142### unselectedColor<sup>18+</sup> 143 144unselectedColor(resColor: Optional\<ResourceColor>) 145 146设置多选框非选中状态边框颜色。与[unselectedColor](#unselectedcolor10)<sup>10+</sup>相比，resColor参数新增了对undefined类型的支持。 147 148**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 156| 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')。 | 157 158### mark<sup>10+</sup> 159 160mark(value: MarkStyle) 161 162设置多选框内部图标样式。 163 164**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 165 166**系统能力：** SystemCapability.ArkUI.ArkUI.Full 167 168**参数：** 169 170| 参数名 | 类型 | 必填 | 说明 | 171| ------ | -------------------------------------------- | ---- | ------------------------------------------------------------ | 172| value | [MarkStyle](ts-types.md#markstyle10对象说明) | 是 | 多选框内部图标样式。 从API version 12开始，设置了indicatorBuilder时，按照indicatorBuilder中的内容显示。<br/>默认值：{<br/>strokeColor : `$r('sys.color.ohos_id_color_foreground_contrary')`,<br/>strokeWidth: `$r('sys.float.ohos_id_checkbox_stroke_width')`,<br/>size: '20vp'<br/>} | 173 174### mark<sup>18+</sup> 175 176mark(style: Optional\<MarkStyle>) 177 178设置多选框内部图标样式。与[mark](#mark10)<sup>10+</sup>相比，style参数新增了对undefined类型的支持。 179 180**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 181 182**系统能力：** SystemCapability.ArkUI.ArkUI.Full 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 188| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[MarkStyle](ts-types.md#markstyle10对象说明)> | 是 | 多选框内部图标样式。 设置了indicatorBuilder时，按照indicatorBuilder中的内容显示。<br/>当style的值为undefined时，默认值：{<br/>strokeColor : `$r('sys.color.ohos_id_color_foreground_contrary')`,<br/>strokeWidth: `$r('sys.float.ohos_id_checkbox_stroke_width')`,<br/>size: '20vp'<br/>} | 189 190### shape<sup>11+</sup> 191 192shape(value: CheckBoxShape) 193 194设置CheckBox组件形状, 包括圆形和圆角方形。 195 196**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 197 198**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 199 200**系统能力：** SystemCapability.ArkUI.ArkUI.Full 201 202**参数：** 203 204| 参数名 | 类型 | 必填 | 说明 | 205| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 206| value | [CheckBoxShape](ts-appendix-enums.md#checkboxshape11) | 是 | CheckBox组件形状, 包括圆形和圆角方形。<br/>默认值：CheckBoxShape.CIRCLE | 207 208### shape<sup>18+</sup> 209 210shape(shape: Optional\<CheckBoxShape>) 211 212设置CheckBox组件形状, 包括圆形和圆角方形。与[shape](#shape11)<sup>11+</sup>相比，shape参数新增了对undefined类型的支持。 213 214**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 215 216**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 217 218**系统能力：** SystemCapability.ArkUI.ArkUI.Full 219 220**参数：** 221 222| 参数名 | 类型 | 必填 | 说明 | 223| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 224| shape | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CheckBoxShape](ts-appendix-enums.md#checkboxshape11)> | 是 | CheckBox组件形状, 包括圆形和圆角方形。<br/>当shape的值为undefined时，默认值：CheckBoxShape.CIRCLE | 225 226### contentModifier<sup>12+</sup> 227 228contentModifier(modifier: ContentModifier\<CheckBoxConfiguration>) 229 230定制CheckBox内容区的方法。 231 232**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 233 234**系统能力：** SystemCapability.ArkUI.ArkUI.Full 235 236**参数：** 237 238| 参数名 | 类型 | 必填 | 说明 | 239| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 240| modifier | [ContentModifier\<CheckBoxConfiguration>](#checkboxconfiguration12对象说明) | 是 | 在CheckBox组件上，定制内容区的方法。<br/>modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。 | 241 242### contentModifier<sup>18+</sup> 243 244contentModifier(modifier: Optional<ContentModifier\<CheckBoxConfiguration>>) 245 246定制CheckBox内容区的方法。与[contentModifier](#contentmodifier12)<sup>12+</sup>相比，modifier参数新增了对undefined类型的支持。 247 248**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 249 250**系统能力：** SystemCapability.ArkUI.ArkUI.Full 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 256| modifier | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[ContentModifier\<CheckBoxConfiguration>](#checkboxconfiguration12对象说明)> | 是 | 在CheckBox组件上，定制内容区的方法。<br/>modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。<br/>当modifier的值为undefined时，不使用内容修改器。 | 257 258## 事件 259 260支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 261 262### onChange 263 264onChange(callback: OnCheckboxChangeCallback) 265 266当选中状态发生变化时，触发该回调。 267 268**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 269 270**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 271 272**系统能力：** SystemCapability.ArkUI.ArkUI.Full 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| -------- | ------------------------------------------------------- | ---- | ---------------- | 278| callback | [OnCheckboxChangeCallback](#oncheckboxchangecallback18) | 是 | 返回选中的状态。 | 279 280### onChange<sup>18+</sup> 281 282onChange(callback: Optional\<OnCheckboxChangeCallback>) 283 284当选中状态发生变化时，触发该回调。与[onChange](#onchange)相比，callback参数新增了对undefined类型的支持。 285 286**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 287 288**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 289 290**系统能力：** SystemCapability.ArkUI.ArkUI.Full 291 292**参数：** 293 294| 参数名 | 类型 | 必填 | 说明 | 295| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 296| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[OnCheckboxChangeCallback](#oncheckboxchangecallback18)> | 是 | 返回选中的状态。<br/>当callback的值为undefined时，不使用回调函数。 | 297 298## OnCheckboxChangeCallback<sup>18+</sup> 299 300type OnCheckboxChangeCallback = (value: boolean) => void 301 302选中的状态。 303 304**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 305 306**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 307 308**系统能力：** SystemCapability.ArkUI.ArkUI.Full 309 310**参数：** 311 312| 参数名 | 类型 | 必填 | 说明 | 313| ------ | ------- | ---- | ------------------------------------------------- | 314| value | boolean | 是 | 返回true时，表示已选中。返回false时，表示未选中。 | 315 316## CheckBoxConfiguration<sup>12+</sup>对象说明 317 318开发者需要自定义class实现ContentModifier接口。 319 320**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 321 322**系统能力：** SystemCapability.ArkUI.ArkUI.Full 323 324| 名称 | 类型 | 只读 | 可选 | 说明 | 325| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 326| name | string | 否 | 否 |当前多选框名称。 | 327| selected | boolean| 否 | 否 | 指示多选框是否被选中。</br>如果select属性没有设置默认值是false。</br>如果设置select属性，此值与设置select属性的值相同。 | 328| triggerChange |Callback\<boolean>| 否 | 否 |触发多选框选中状态变化。<br/>为true时，表示从未选中变为选中。为false时，表示从选中变为未选中。 | 329 330## 示例 331 332### 示例1（设置多选框形状） 333 334该示例通过配置CheckBoxShape实现圆形和圆角方形多选框样式。 335 336```ts 337// xxx.ets 338@Entry 339@Component 340struct CheckboxExample { 341 build() { 342 Flex({ justifyContent: FlexAlign.SpaceEvenly }) { 343 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 344 .select(true) 345 .selectedColor(0xed6f21) 346 .shape(CheckBoxShape.CIRCLE) 347 .onChange((value: boolean) => { 348 console.info('Checkbox1 change is' + value); 349 }) 350 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 351 .select(false) 352 .selectedColor(0x39a2db) 353 .shape(CheckBoxShape.ROUNDED_SQUARE) 354 .onChange((value: boolean) => { 355 console.info('Checkbox2 change is' + value); 356 }) 357 } 358 } 359} 360``` 361 362 363 364 365### 示例2（设置多选框颜色） 366 367该示例通过配置mark实现自定义多选框的颜色。 368 369```ts 370// xxx.ets 371@Entry 372@Component 373struct Index { 374 375 build() { 376 Row() { 377 Column() { 378 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 379 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 380 .selectedColor(0x39a2db) 381 .shape(CheckBoxShape.ROUNDED_SQUARE) 382 .onChange((value: boolean) => { 383 console.info('Checkbox1 change is'+ value); 384 }) 385 .mark({ 386 strokeColor:Color.Black, 387 size: 50, 388 strokeWidth: 5 389 }) 390 .unselectedColor(Color.Red) 391 .width(30) 392 .height(30) 393 Text('Checkbox1').fontSize(20) 394 } 395 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 396 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 397 .selectedColor(0x39a2db) 398 .shape(CheckBoxShape.ROUNDED_SQUARE) 399 .onChange((value: boolean) => { 400 console.info('Checkbox2 change is' + value); 401 }) 402 .width(30) 403 .height(30) 404 Text('Checkbox2').fontSize(20) 405 } 406 } 407 .width('100%') 408 } 409 .height('100%') 410 } 411} 412``` 413 414 415 416 417### 示例3（自定义多选框样式） 418该示例实现了自定义复选框样式的功能，自定义样式实现了一个五边形复选框，如果选中，内部会出现红色三角图案，标题会显示选中字样，如果取消选中，红色三角图案消失，标题会显示非选中字样。 419 420```ts 421// xxx.ets 422class MyCheckboxStyle implements ContentModifier<CheckBoxConfiguration> { 423 selectedColor: Color = Color.White; 424 425 constructor(selectedColor: Color) { 426 this.selectedColor = selectedColor; 427 } 428 429 applyContent(): WrappedBuilder<[CheckBoxConfiguration]> { 430 return wrapBuilder(buildCheckbox); 431 } 432} 433 434@Builder 435function buildCheckbox(config: CheckBoxConfiguration) { 436 Column({ space: 10 }) { 437 Text(config.name + (config.selected ? "（ 选中 ）" : "（ 非选中 ）")).margin({ right: 70, top: 50 }) 438 Text(config.enabled ? "enabled true" : "enabled false").margin({ right: 110 }) 439 Shape() { 440 Path() 441 .width(100) 442 .height(100) 443 .commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z') 444 .fillOpacity(0) 445 .strokeWidth(3) 446 .onClick(() => { 447 if (config.selected) { 448 config.triggerChange(false); 449 } else { 450 config.triggerChange(true); 451 } 452 }) 453 .opacity(config.enabled ? 1 : 0.1) 454 Path() 455 .width(10) 456 .height(10) 457 .commands('M50 0 L100 100 L0 100 Z') 458 .visibility(config.selected ? Visibility.Visible : Visibility.Hidden) 459 .fill(config.selected ? (config.contentModifier as MyCheckboxStyle).selectedColor : Color.Black) 460 .stroke((config.contentModifier as MyCheckboxStyle).selectedColor) 461 .margin({ left: 10, top: 10 }) 462 .opacity(config.enabled ? 1 : 0.1) 463 } 464 .width(300) 465 .height(200) 466 .viewPort({ 467 x: 0, 468 y: 0, 469 width: 310, 470 height: 310 471 }) 472 .strokeLineJoin(LineJoinStyle.Miter) 473 .strokeMiterLimit(5) 474 .margin({ left: 50 }) 475 } 476} 477 478@Entry 479@Component 480struct Index { 481 @State checkboxEnabled: boolean = true; 482 483 build() { 484 Column({ space: 100 }) { 485 Checkbox({ name: '复选框状态', group: 'checkboxGroup' }) 486 .contentModifier(new MyCheckboxStyle(Color.Red)) 487 .onChange((value: boolean) => { 488 console.info('Checkbox change is' + value); 489 }).enabled(this.checkboxEnabled) 490 491 Row() { 492 Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => { 493 if (value) { 494 this.checkboxEnabled = true; 495 } else { 496 this.checkboxEnabled = false; 497 } 498 }) 499 }.position({ x: 50, y: 130 }) 500 }.margin({ top: 30 }) 501 } 502} 503``` 504 505 506 507 508### 示例4（设置文本多选框样式） 509该示例通过配置indicatorBuilder实现选中样式为Text。 510```ts 511// xxx.ets 512@Entry 513@Component 514struct CheckboxExample { 515 @Builder 516 indicatorBuilder(value: number) { 517 Column(){ 518 Text(value > 99 ? '99+': value.toString()) 519 .textAlign(TextAlign.Center) 520 .fontSize(value > 99 ? '16vp': '20vp') 521 .fontWeight(FontWeight.Medium) 522 .fontColor('#ffffffff') 523 } 524 } 525 build() { 526 Row() { 527 Column() { 528 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center}) { 529 Checkbox({ name: 'checkbox1', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(9)}}) 530 .shape(CheckBoxShape.CIRCLE) 531 .onChange((value: boolean) => { 532 console.info('Checkbox1 change is'+ value); 533 }) 534 .mark({ 535 strokeColor:Color.Black, 536 size: 50, 537 strokeWidth: 5 538 }) 539 .width(30) 540 .height(30) 541 Text('Checkbox1').fontSize(20) 542 }.padding(15) 543 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 544 Checkbox({ name: 'checkbox2', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(100)}}) 545 .shape(CheckBoxShape.ROUNDED_SQUARE) 546 .onChange((value: boolean) => { 547 console.info('Checkbox2 change is' + value); 548 }) 549 .width(30) 550 .height(30) 551 Text('Checkbox2').fontSize(20) 552 } 553 } 554 .width('100%') 555 } 556 .height('100%') 557 } 558} 559``` 560 561 562
