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**系统能力：** SystemCapability.ArkUI.ArkUI.Full 36 37| 名称 | 类型 | 必填 | 说明 | 38| --------| --------| ------ | -------- | 39| name | string | 否 | 用于指定多选框名称。 <br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 40| group | string | 否 | 用于指定多选框所属群组的名称（即所属CheckboxGroup的名称）。<br/>**说明：** <br/>未配合使用[CheckboxGroup](ts-basic-components-checkboxgroup.md)组件时，此值无用。 <br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 41| indicatorBuilder<sup>12+</sup> | [CustomBuilder](ts-types.md#custombuilder8) | 否 | 配置多选框的选中样式为自定义组件。自定义组件与Checkbox组件为中心点对齐显示。indicatorBuilder设置为undefined/null时，默认为indicatorBuilder未设置状态。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 42 43## 属性 44 45除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性： 46 47### select 48 49select(value: boolean) 50 51设置多选框是否选中。 52 53从API version 10开始，该属性支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 54 55**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 56 57**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.ArkUI.ArkUI.Full 60 61**参数：** 62 63| 参数名 | 类型 | 必填 | 说明 | 64| ------ | ------- | ---- | ---------------------------------- | 65| value | boolean | 是 | 多选框是否选中。<br/>默认值：false | 66 67### selectedColor 68 69selectedColor(value: ResourceColor) 70 71设置多选框选中状态颜色。 72 73**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 74 75**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.ArkUI.ArkUI.Full 78 79**参数：** 80 81| 参数名 | 类型 | 必填 | 说明 | 82| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 83| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 多选框选中状态颜色。<br/>默认值：$r('sys.color.ohos_id_color_text_primary_activated')。<br/>异常值按照默认值处理。 | 84 85### unselectedColor<sup>10+</sup> 86 87unselectedColor(value: ResourceColor) 88 89设置多选框非选中状态边框颜色。 90 91**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 92 93**系统能力：** SystemCapability.ArkUI.ArkUI.Full 94 95**参数：** 96 97| 参数名 | 类型 | 必填 | 说明 | 98| ------ | ------------------------------------------ | ---- | -------------------------- | 99| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 多选框非选中状态边框颜色。<br/>默认值：$r('sys.color.ohos_id_color_switch_outline_off')。 | 100 101### mark<sup>10+</sup> 102 103mark(value: MarkStyle) 104 105设置多选框内部图标样式。 106 107**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 108 109**系统能力：** SystemCapability.ArkUI.ArkUI.Full 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| ------ | -------------------------------------------- | ---- | ------------------------------------------------------------ | 115| 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/>} | 116 117### shape<sup>11+</sup> 118 119shape(value: CheckBoxShape) 120 121设置CheckBox组件形状, 包括圆形和圆角方形。 122 123**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。 124 125**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 126 127**系统能力：** SystemCapability.ArkUI.ArkUI.Full 128 129**参数：** 130 131| 参数名 | 类型 | 必填 | 说明 | 132| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 133| value |[CheckBoxShape](ts-appendix-enums.md#checkboxshape11) | 是 | CheckBox组件形状, 包括圆形和圆角方形。<br/>默认值：CheckBoxShape.CIRCLE | 134 135### contentModifier<sup>12+</sup> 136 137contentModifier(modifier: ContentModifier\<CheckBoxConfiguration>) 138 139定制CheckBox内容区的方法。 140 141**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 142 143**系统能力：** SystemCapability.ArkUI.ArkUI.Full 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 149| modifier | [ContentModifier\<CheckBoxConfiguration>](#checkboxconfiguration12对象说明) | 是 | 在CheckBox组件上，定制内容区的方法。<br/>modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 | 150 151## 事件 152 153支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 154 155### onChange 156 157onChange(callback: (value: boolean) => void) 158 159当选中状态发生变化时，触发该回调。 160 161**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 162 163**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 164 165**系统能力：** SystemCapability.ArkUI.ArkUI.Full 166 167**参数：** 168 169| 参数名 | 类型 | 必填 | 说明 | 170| ------ | ------- | ---- | ------------------------------------------------- | 171| value | boolean | 是 | 返回true时，表示已选中。返回false时，表示未选中。 | 172 173## CheckBoxConfiguration<sup>12+</sup>对象说明 174 175开发者需要自定义class实现ContentModifier接口。 176 177**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 178 179**系统能力：** SystemCapability.ArkUI.ArkUI.Full 180 181| 名称 | 类型 | 只读 | 可选 | 说明 | 182| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 183| name | string | 否 | 否 |当前多选框名称。 | 184| selected | boolean| 否 | 否 | 指示多选框是否被选中。</br>如果select属性没有设置默认值是false。</br>如果设置select属性，此值与设置select属性的值相同。 | 185| triggerChange |Callback\<boolean>| 否 | 否 |触发多选框选中状态变化。 | 186 187## 示例 188 189### 示例1（设置多选框形状） 190 191该示例通过配置CheckBoxShape实现圆形和圆角方形多选框样式。 192 193```ts 194// xxx.ets 195@Entry 196@Component 197struct CheckboxExample { 198 build() { 199 Flex({ justifyContent: FlexAlign.SpaceAround }) { 200 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 201 .select(true) 202 .selectedColor(0xed6f21) 203 .shape(CheckBoxShape.CIRCLE) 204 .onChange((value: boolean) => { 205 console.info('Checkbox1 change is' + value) 206 }) 207 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 208 .select(false) 209 .selectedColor(0x39a2db) 210 .shape(CheckBoxShape.ROUNDED_SQUARE) 211 .onChange((value: boolean) => { 212 console.info('Checkbox2 change is' + value) 213 }) 214 } 215 } 216} 217``` 218 219 220 221 222### 示例2（设置多选框颜色） 223 224该示例通过配置mark实现自定义多选框的颜色。 225 226```ts 227// xxx.ets 228@Entry 229@Component 230struct Index { 231 232 build() { 233 Row() { 234 Column() { 235 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 236 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 237 .selectedColor(0x39a2db) 238 .shape(CheckBoxShape.ROUNDED_SQUARE) 239 .onChange((value: boolean) => { 240 console.info('Checkbox1 change is'+ value) 241 }) 242 .mark({ 243 strokeColor:Color.Black, 244 size: 50, 245 strokeWidth: 5 246 }) 247 .unselectedColor(Color.Red) 248 .width(30) 249 .height(30) 250 Text('Checkbox1').fontSize(20) 251 } 252 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 253 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 254 .selectedColor(0x39a2db) 255 .shape(CheckBoxShape.ROUNDED_SQUARE) 256 .onChange((value: boolean) => { 257 console.info('Checkbox2 change is' + value) 258 }) 259 .width(30) 260 .height(30) 261 Text('Checkbox2').fontSize(20) 262 } 263 } 264 .width('100%') 265 } 266 .height('100%') 267 } 268} 269``` 270 271 272 273 274### 示例3（自定义多选框样式） 275该示例实现了自定义复选框样式的功能，自定义样式实现了一个五边形复选框，如果选中，内部会出现红色三角图案，标题会显示选中字样，如果取消选中，红色三角图案消失，标题会显示非选中字样。 276 277```ts 278// xxx.ets 279class MyCheckboxStyle implements ContentModifier<CheckBoxConfiguration> { 280 selectedColor: Color = Color.White 281 constructor(selectedColor: Color) { 282 this.selectedColor = selectedColor; 283 } 284 applyContent() : WrappedBuilder<[CheckBoxConfiguration]> 285 { 286 return wrapBuilder(buildCheckbox) 287 } 288} 289 290@Builder function buildCheckbox(config: CheckBoxConfiguration) { 291 Column({space:10}) { 292 Text(config.name + (config.selected ? "（ 选中 ）" : "（ 非选中 ）")).margin({right : 70, top : 50}) 293 Text(config.enabled ? "enabled true" : "enabled false").margin({right : 110}) 294 Shape() { 295 Path().width(100).height(100).commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z').fillOpacity(0).strokeWidth(3).onClick(()=>{ 296 if (config.selected) { 297 config.triggerChange(false) 298 } else { 299 config.triggerChange(true) 300 } 301 }).opacity(config.enabled ? 1 : 0.1) 302 Path().width(10).height(10).commands('M50 0 L100 100 L0 100 Z') 303 .visibility(config.selected ? Visibility.Visible : Visibility.Hidden) 304 .fill(config.selected ? (config.contentModifier as MyCheckboxStyle).selectedColor : Color.Black) 305 .stroke((config.contentModifier as MyCheckboxStyle).selectedColor) 306 .margin({left:10,top:10}) 307 .opacity(config.enabled ? 1 : 0.1) 308 } 309 .width(300) 310 .height(200) 311 .viewPort({ x: 0, y: 0, width: 310, height: 310 }) 312 .strokeLineJoin(LineJoinStyle.Miter) 313 .strokeMiterLimit(5) 314 .margin({left:50}) 315 } 316} 317 318@Entry 319@Component 320struct Index { 321 @State checkboxEnabled: boolean = true; 322 build() { 323 Column({ space: 100 }) { 324 Checkbox({ name: '复选框状态', group: 'checkboxGroup' }) 325 .contentModifier(new MyCheckboxStyle(Color.Red)) 326 .onChange((value: boolean) => { 327 console.info('Checkbox change is' + value) 328 }).enabled(this.checkboxEnabled) 329 330 Row() { 331 Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => { 332 if (value) { 333 this.checkboxEnabled = true 334 } else { 335 this.checkboxEnabled = false 336 } 337 }) 338 }.position({ x: 50, y: 130 }) 339 }.margin({top : 30}) 340 } 341} 342``` 343 344 345 346 347### 示例4（设置文本多选框样式） 348该示例通过配置indicatorBuilder实现选中样式为Text。 349```ts 350// xxx.ets 351@Entry 352@Component 353struct CheckboxExample { 354 @Builder 355 indicatorBuilder(value: number) { 356 Column(){ 357 Text(value > 99 ? '99+': value.toString()) 358 .textAlign(TextAlign.Center) 359 .fontSize(value > 99 ? '16vp': '20vp') 360 .fontWeight(FontWeight.Medium) 361 .fontColor('#ffffffff') 362 } 363 } 364 build() { 365 Row() { 366 Column() { 367 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center}) { 368 Checkbox({ name: 'checkbox1', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(9)}}) 369 .shape(CheckBoxShape.CIRCLE) 370 .onChange((value: boolean) => { 371 console.info('Checkbox1 change is'+ value) 372 }) 373 .mark({ 374 strokeColor:Color.Black, 375 size: 50, 376 strokeWidth: 5 377 }) 378 .width(30) 379 .height(30) 380 Text('Checkbox1').fontSize(20) 381 }.padding(15) 382 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 383 Checkbox({ name: 'checkbox2', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(100)}}) 384 .shape(CheckBoxShape.ROUNDED_SQUARE) 385 .onChange((value: boolean) => { 386 console.info('Checkbox2 change is' + value) 387 }) 388 .width(30) 389 .height(30) 390 Text('Checkbox2').fontSize(20) 391 } 392 } 393 .width('100%') 394 } 395 .height('100%') 396 } 397} 398``` 399 400 401
