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: (event: CheckboxGroupResult) => void ) 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| event | [CheckboxGroupResult](#checkboxgroupresult对象说明) | 是 | 多选框群组的信息。 | 158 159## CheckboxGroupResult对象说明 160 161**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 162 163**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 164 165**系统能力：** SystemCapability.ArkUI.ArkUI.Full 166 167| 名称 | 类型 | 只读 | 可选 | 说明 | 168| ------ | ------ | ------- | ------- | ------- | 169| name | Array<string> | 否 | 否 | 群组内所有被选中的多选框名称。 | 170| status | [SelectStatus](#selectstatus枚举说明) | 否 | 否 | 选中状态。 | 171 172## SelectStatus枚举说明 173 174**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 175 176**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 177 178**系统能力：** SystemCapability.ArkUI.ArkUI.Full 179 180| 名称 | 说明 | 181| ----- | -------------------- | 182| All | 群组多选择框全部选择。 | 183| Part | 群组多选择框部分选择。 | 184| None | 群组多选择框全部没有选择。 | 185 186## 示例 187 188### 示例1 189 190```ts 191// xxx.ets 192@Entry 193@Component 194struct CheckboxExample { 195 build() { 196 Scroll() { 197 Column() { 198 // 全选按钮 199 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 200 CheckboxGroup({ group: 'checkboxGroup' }) 201 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 202 .selectedColor('#007DFF') 203 .onChange((itemName: CheckboxGroupResult) => { 204 console.info("checkbox group content" + JSON.stringify(itemName)) 205 }) 206 Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 207 } 208 209 // 选项1 210 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 211 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 212 .selectedColor('#007DFF') 213 .shape(CheckBoxShape.ROUNDED_SQUARE) 214 .onChange((value: boolean) => { 215 console.info('Checkbox1 change is' + value) 216 }) 217 Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 218 }.margin({ left: 36 }) 219 220 // 选项2 221 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 222 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 223 .selectedColor('#007DFF') 224 .shape(CheckBoxShape.ROUNDED_SQUARE) 225 .onChange((value: boolean) => { 226 console.info('Checkbox2 change is' + value) 227 }) 228 Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 229 }.margin({ left: 36 }) 230 231 // 选项3 232 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 233 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 234 .selectedColor('#007DFF') 235 .shape(CheckBoxShape.ROUNDED_SQUARE) 236 .onChange((value: boolean) => { 237 console.info('Checkbox3 change is' + value) 238 }) 239 Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 240 }.margin({ left: 36 }) 241 } 242 } 243 } 244} 245``` 246 247 248### 示例2 249 250```ts 251// xxx.ets 252@Entry 253@Component 254struct Index { 255 256 build() { 257 Row() { 258 Column() { 259 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 260 CheckboxGroup({ group: 'checkboxGroup' }) 261 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 262 .selectedColor(Color.Orange) 263 .onChange((itemName: CheckboxGroupResult) => { 264 console.info("checkbox group content" + JSON.stringify(itemName)) 265 }) 266 .mark({ 267 strokeColor:Color.Black, 268 size: 40, 269 strokeWidth: 5 270 }) 271 .unselectedColor(Color.Red) 272 .width(30) 273 .height(30) 274 Text('Select All').fontSize(20) 275 }.margin({right:15}) 276 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 277 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 278 .selectedColor(0x39a2db) 279 .shape(CheckBoxShape.ROUNDED_SQUARE) 280 .onChange((value: boolean) => { 281 console.info('Checkbox1 change is'+ value) 282 }) 283 .mark({ 284 strokeColor:Color.Black, 285 size: 50, 286 strokeWidth: 5 287 }) 288 .unselectedColor(Color.Red) 289 .width(30) 290 .height(30) 291 Text('Checkbox1').fontSize(20) 292 } 293 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 294 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 295 .selectedColor(0x39a2db) 296 .shape(CheckBoxShape.ROUNDED_SQUARE) 297 .onChange((value: boolean) => { 298 console.info('Checkbox2 change is' + value) 299 }) 300 .width(30) 301 .height(30) 302 Text('Checkbox2').fontSize(20) 303 } 304 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 305 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 306 .selectedColor(0x39a2db) 307 .shape(CheckBoxShape.ROUNDED_SQUARE) 308 .onChange((value: boolean) => { 309 console.info('Checkbox3 change is' + value) 310 }) 311 .width(30) 312 .height(30) 313 Text('Checkbox3').fontSize(20) 314 } 315 } 316 .width('100%') 317 } 318 .height('100%') 319 } 320} 321``` 322 323 324 325
