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](#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: OnCheckboxChangeCallback) 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| callback | [OnCheckboxChangeCallback](#oncheckboxchangecallback13) | 是 | 返回选中的状态。 | 172 173## OnCheckboxChangeCallback<sup>13+</sup> 174 175type OnCheckboxChangeCallback = (value: boolean) => void 176 177选中的状态。 178 179**卡片能力：** 从API version 13开始，该接口支持在ArkTS卡片中使用。 180 181**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------ | ------- | ---- | ------------------------------------------------- | 189| value | boolean | 是 | 返回true时，表示已选中。返回false时，表示未选中。 | 190 191## CheckBoxShape<sup>11+</sup>枚举类型说明 192 193**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 194 195**系统能力：** SystemCapability.ArkUI.ArkUI.Full 196 197| 名称 | 值 | 说明 | 198| -------------- | ---- | -------- | 199| CIRCLE | 0 | 圆形 | 200| ROUNDED_SQUARE | 1 | 圆角方形 | 201 202## CheckBoxConfiguration<sup>12+</sup>对象说明 203 204开发者需要自定义class实现ContentModifier接口。 205 206**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 207 208**系统能力：** SystemCapability.ArkUI.ArkUI.Full 209 210| 名称 | 类型 | 只读 | 可选 | 说明 | 211| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 212| name | string | 否 | 否 |当前多选框名称。 | 213| selected | boolean| 否 | 否 | 指示多选框是否被选中。</br>如果select属性没有设置默认值是false。</br>如果设置select属性，此值与设置select属性的值相同。 | 214| triggerChange |Callback\<boolean>| 否 | 否 |触发多选框选中状态变化。 | 215 216## 示例 217 218### 示例1 219 220```ts 221// xxx.ets 222@Entry 223@Component 224struct CheckboxExample { 225 build() { 226 Flex({ justifyContent: FlexAlign.SpaceAround }) { 227 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 228 .select(true) 229 .selectedColor(0xed6f21) 230 .shape(CheckBoxShape.CIRCLE) 231 .onChange((value: boolean) => { 232 console.info('Checkbox1 change is' + value) 233 }) 234 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 235 .select(false) 236 .selectedColor(0x39a2db) 237 .shape(CheckBoxShape.ROUNDED_SQUARE) 238 .onChange((value: boolean) => { 239 console.info('Checkbox2 change is' + value) 240 }) 241 } 242 } 243} 244``` 245 246 247 248 249### 示例2 250 251```ts 252// xxx.ets 253@Entry 254@Component 255struct Index { 256 257 build() { 258 Row() { 259 Column() { 260 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 261 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 262 .selectedColor(0x39a2db) 263 .shape(CheckBoxShape.ROUNDED_SQUARE) 264 .onChange((value: boolean) => { 265 console.info('Checkbox1 change is'+ value) 266 }) 267 .mark({ 268 strokeColor:Color.Black, 269 size: 50, 270 strokeWidth: 5 271 }) 272 .unselectedColor(Color.Red) 273 .width(30) 274 .height(30) 275 Text('Checkbox1').fontSize(20) 276 } 277 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 278 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 279 .selectedColor(0x39a2db) 280 .shape(CheckBoxShape.ROUNDED_SQUARE) 281 .onChange((value: boolean) => { 282 console.info('Checkbox2 change is' + value) 283 }) 284 .width(30) 285 .height(30) 286 Text('Checkbox2').fontSize(20) 287 } 288 } 289 .width('100%') 290 } 291 .height('100%') 292 } 293} 294``` 295 296 297 298 299### 示例3 300该示例实现了自定义复选框样式的功能，自定义样式实现了一个五边形复选框，如果选中，内部会出现红色三角图案，标题会显示选中字样，如果取消选中，红色三角图案消失，标题会显示非选中字样。 301 302```ts 303// xxx.ets 304class MyCheckboxStyle implements ContentModifier<CheckBoxConfiguration> { 305 selectedColor: Color = Color.White 306 constructor(selectedColor: Color) { 307 this.selectedColor = selectedColor; 308 } 309 applyContent() : WrappedBuilder<[CheckBoxConfiguration]> 310 { 311 return wrapBuilder(buildCheckbox) 312 } 313} 314 315@Builder function buildCheckbox(config: CheckBoxConfiguration) { 316 Column({space:10}) { 317 Text(config.name + (config.selected ? "（ 选中 ）" : "（ 非选中 ）")).margin({right : 70, top : 50}) 318 Text(config.enabled ? "enabled true" : "enabled false").margin({right : 110}) 319 Shape() { 320 Path().width(100).height(100).commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z').fillOpacity(0).strokeWidth(3).onClick(()=>{ 321 if (config.selected) { 322 config.triggerChange(false) 323 } else { 324 config.triggerChange(true) 325 } 326 }).opacity(config.enabled ? 1 : 0.1) 327 Path().width(10).height(10).commands('M50 0 L100 100 L0 100 Z') 328 .visibility(config.selected ? Visibility.Visible : Visibility.Hidden) 329 .fill(config.selected ? (config.contentModifier as MyCheckboxStyle).selectedColor : Color.Black) 330 .stroke((config.contentModifier as MyCheckboxStyle).selectedColor) 331 .margin({left:10,top:10}) 332 .opacity(config.enabled ? 1 : 0.1) 333 } 334 .width(300) 335 .height(200) 336 .viewPort({ x: 0, y: 0, width: 310, height: 310 }) 337 .strokeLineJoin(LineJoinStyle.Miter) 338 .strokeMiterLimit(5) 339 .margin({left:50}) 340 } 341} 342 343@Entry 344@Component 345struct Index { 346 @State checkboxEnabled: boolean = true; 347 build() { 348 Column({ space: 100 }) { 349 Checkbox({ name: '复选框状态', group: 'checkboxGroup' }) 350 .contentModifier(new MyCheckboxStyle(Color.Red)) 351 .onChange((value: boolean) => { 352 console.info('Checkbox change is' + value) 353 }).enabled(this.checkboxEnabled) 354 355 Row() { 356 Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => { 357 if (value) { 358 this.checkboxEnabled = true 359 } else { 360 this.checkboxEnabled = false 361 } 362 }) 363 }.position({ x: 50, y: 130 }) 364 }.margin({top : 30}) 365 } 366} 367``` 368 369 370 371 372### 示例4 373该示例设置选中样式为Text。 374```ts 375// xxx.ets 376@Entry 377@Component 378struct CheckboxExample { 379 @Builder 380 indicatorBuilder(value: number) { 381 Column(){ 382 Text(value > 99 ? '99+': value.toString()) 383 .textAlign(TextAlign.Center) 384 .fontSize(value > 99 ? '16vp': '20vp') 385 .fontWeight(FontWeight.Medium) 386 .fontColor('#ffffffff') 387 } 388 } 389 build() { 390 Row() { 391 Column() { 392 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center}) { 393 Checkbox({ name: 'checkbox1', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(9)}}) 394 .shape(CheckBoxShape.CIRCLE) 395 .onChange((value: boolean) => { 396 console.info('Checkbox1 change is'+ value) 397 }) 398 .mark({ 399 strokeColor:Color.Black, 400 size: 50, 401 strokeWidth: 5 402 }) 403 .width(30) 404 .height(30) 405 Text('Checkbox1').fontSize(20) 406 }.padding(15) 407 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 408 Checkbox({ name: 'checkbox2', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(100)}}) 409 .shape(CheckBoxShape.ROUNDED_SQUARE) 410 .onChange((value: boolean) => { 411 console.info('Checkbox2 change is' + value) 412 }) 413 .width(30) 414 .height(30) 415 Text('Checkbox2').fontSize(20) 416 } 417 } 418 .width('100%') 419 } 420 .height('100%') 421 } 422} 423``` 424 425 426
