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-universal-attributes-size.md)外，还支持以下属性： 48 49### selectAll 50 51selectAll(value: boolean) 52 53设置是否全选。若同组的[Checkbox](ts-basic-components-checkbox.md)显式设置了select属性，则Checkbox的优先级高。 54 55从API version 10开始，该属性支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 56 57**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 58 59**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 60 61**系统能力：** SystemCapability.ArkUI.ArkUI.Full 62 63**参数：** 64 65| 参数名 | 类型 | 必填 | 说明 | 66| ------ | ------- | ---- | ---------------------------- | 67| value | boolean | 是 | 是否全选。<br/>默认值：false | 68 69### selectedColor 70 71selectedColor(value: ResourceColor) 72 73设置被选中或部分选中状态的颜色。 74 75**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 76 77**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 78 79**系统能力：** SystemCapability.ArkUI.ArkUI.Full 80 81**参数：** 82 83| 参数名 | 类型 | 必填 | 说明 | 84| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 85| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 被选中或部分选中状态的颜色。<br/>默认值：$r('sys.color.ohos_id_color_text_primary_activated')<br/>异常值按照默认值处理。 | 86 87### unselectedColor<sup>10+</sup> 88 89unselectedColor(value: ResourceColor) 90 91设置非选中状态边框颜色。 92 93**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 94 95**系统能力：** SystemCapability.ArkUI.ArkUI.Full 96 97**参数：** 98 99| 参数名 | 类型 | 必填 | 说明 | 100| ------ | ------------------------------------------ | ---- | -------------------- | 101| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 非选中状态边框颜色。<br/>默认值：$r('sys.color.ohos_id_color_switch_outline_off')。 | 102 103### mark<sup>10+</sup> 104 105mark(value: MarkStyle) 106 107设置多选框内部图标样式。 108 109**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 110 111**系统能力：** SystemCapability.ArkUI.ArkUI.Full 112 113**参数：** 114 115| 参数名 | 类型 | 必填 | 说明 | 116| ------ | --------------------------------- | ---- | -------------------- | 117| value | [MarkStyle](ts-types.md#markstyle10对象说明) | 是 | 多选框内部图标样式。 | 118 119### checkboxShape<sup>12</sup> 120 121checkboxShape(value: CheckBoxShape) 122 123设置CheckboxGroup组件形状， 包括圆形和圆角方形。 124 125**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。 126 127**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133| 参数名 | 类型 | 必填 | 说明 | 134| ------ | --------------------------------------------------- | ---- | ------------------ | 135| value | [CheckBoxShape](ts-basic-components-checkbox.md#checkboxshape11枚举类型说明) | 是 | 设置CheckboxGroup组件形状， 包括圆形和圆角方形。<br/>默认值:CheckBoxShape.CIRCLE。 <br />**说明**：<br/>CheckboxGroup组件形状按照设置显示。<br/>CheckboxGroup内所有没有单独设置shape类型的Checkbox形状和CheckboxGroup的保持一致。<br/>CheckboxGroup内有单独设置shape类型的Checkbox形状则优先于CheckboxGroup，按照设置形状显示。 136 137## 事件 138 139除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件： 140 141### onChange 142 143onChange(callback: OnCheckboxGroupChangeCallback) 144 145CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。 146 147**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 148 149**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 150 151**系统能力：** SystemCapability.ArkUI.ArkUI.Full 152 153**参数：** 154 155| 参数名 | 类型 | 必填 | 说明 | 156| -------- | ------------------------------------------------------------ | ---- | ------------------ | 157| callback | [OnCheckboxGroupChangeCallback](#oncheckboxgroupchangecallback13) | 是 | 多选框群组的信息。 | 158 159## OnCheckboxGroupChangeCallback<sup>13+</sup> 160 161type OnCheckboxGroupChangeCallback = (value: CheckboxGroupResult) => void 162 163多选框群组的信息。 164 165**卡片能力：** 从API version 13开始，该接口支持在ArkTS卡片中使用。 166 167**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 168 169**系统能力：** SystemCapability.ArkUI.ArkUI.Full 170 171**参数：** 172 173| 参数名 | 类型 | 必填 | 说明 | 174| ------ | --------------------------------------------------- | ---- | ------------------ | 175| value | [CheckboxGroupResult](#checkboxgroupresult对象说明) | 是 | 多选框群组的信息。 | 176 177## CheckboxGroupResult对象说明 178 179**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 180 181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.ArkUI.ArkUI.Full 184 185| 名称 | 类型 | 只读 | 可选 | 说明 | 186| ------ | ------ | ------- | ------- | ------- | 187| name | Array<string> | 否 | 否 | 群组内所有被选中的多选框名称。 | 188| status | [SelectStatus](#selectstatus枚举说明) | 否 | 否 | 选中状态。 | 189 190## SelectStatus枚举说明 191 192**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 193 194**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 195 196**系统能力：** SystemCapability.ArkUI.ArkUI.Full 197 198| 名称 | 说明 | 199| ----- | -------------------- | 200| All | 群组多选择框全部选择。 | 201| Part | 群组多选择框部分选择。 | 202| None | 群组多选择框全部没有选择。 | 203 204## 示例 205 206### 示例1 207 208```ts 209// xxx.ets 210@Entry 211@Component 212struct CheckboxExample { 213 build() { 214 Scroll() { 215 Column() { 216 // 全选按钮 217 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 218 CheckboxGroup({ group: 'checkboxGroup' }) 219 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 220 .selectedColor('#007DFF') 221 .onChange((itemName: CheckboxGroupResult) => { 222 console.info("checkbox group content" + JSON.stringify(itemName)) 223 }) 224 Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 225 } 226 227 // 选项1 228 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 229 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 230 .selectedColor('#007DFF') 231 .shape(CheckBoxShape.ROUNDED_SQUARE) 232 .onChange((value: boolean) => { 233 console.info('Checkbox1 change is' + value) 234 }) 235 Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 236 }.margin({ left: 36 }) 237 238 // 选项2 239 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 240 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 241 .selectedColor('#007DFF') 242 .shape(CheckBoxShape.ROUNDED_SQUARE) 243 .onChange((value: boolean) => { 244 console.info('Checkbox2 change is' + value) 245 }) 246 Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 247 }.margin({ left: 36 }) 248 249 // 选项3 250 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 251 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 252 .selectedColor('#007DFF') 253 .shape(CheckBoxShape.ROUNDED_SQUARE) 254 .onChange((value: boolean) => { 255 console.info('Checkbox3 change is' + value) 256 }) 257 Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 258 }.margin({ left: 36 }) 259 } 260 } 261 } 262} 263``` 264 265 266### 示例2 267 268```ts 269// xxx.ets 270@Entry 271@Component 272struct Index { 273 274 build() { 275 Row() { 276 Column() { 277 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 278 CheckboxGroup({ group: 'checkboxGroup' }) 279 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 280 .selectedColor(Color.Orange) 281 .onChange((itemName: CheckboxGroupResult) => { 282 console.info("checkbox group content" + JSON.stringify(itemName)) 283 }) 284 .mark({ 285 strokeColor:Color.Black, 286 size: 40, 287 strokeWidth: 5 288 }) 289 .unselectedColor(Color.Red) 290 .width(30) 291 .height(30) 292 Text('Select All').fontSize(20) 293 }.margin({right:15}) 294 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 295 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 296 .selectedColor(0x39a2db) 297 .shape(CheckBoxShape.ROUNDED_SQUARE) 298 .onChange((value: boolean) => { 299 console.info('Checkbox1 change is'+ value) 300 }) 301 .mark({ 302 strokeColor:Color.Black, 303 size: 50, 304 strokeWidth: 5 305 }) 306 .unselectedColor(Color.Red) 307 .width(30) 308 .height(30) 309 Text('Checkbox1').fontSize(20) 310 } 311 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 312 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 313 .selectedColor(0x39a2db) 314 .shape(CheckBoxShape.ROUNDED_SQUARE) 315 .onChange((value: boolean) => { 316 console.info('Checkbox2 change is' + value) 317 }) 318 .width(30) 319 .height(30) 320 Text('Checkbox2').fontSize(20) 321 } 322 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 323 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 324 .selectedColor(0x39a2db) 325 .shape(CheckBoxShape.ROUNDED_SQUARE) 326 .onChange((value: boolean) => { 327 console.info('Checkbox3 change is' + value) 328 }) 329 .width(30) 330 .height(30) 331 Text('Checkbox3').fontSize(20) 332 } 333 } 334 .width('100%') 335 } 336 .height('100%') 337 } 338} 339``` 340 341 342 343
