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-appendix-enums.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该示例用于控制多选框全选或者不全选状态。 191 192```ts 193// xxx.ets 194@Entry 195@Component 196struct CheckboxExample { 197 build() { 198 Scroll() { 199 Column() { 200 // 全选按钮 201 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 202 CheckboxGroup({ group: 'checkboxGroup' }) 203 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 204 .selectedColor('#007DFF') 205 .onChange((itemName: CheckboxGroupResult) => { 206 console.info("checkbox group content" + JSON.stringify(itemName)) 207 }) 208 Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 209 } 210 211 // 选项1 212 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 213 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 214 .selectedColor('#007DFF') 215 .shape(CheckBoxShape.ROUNDED_SQUARE) 216 .onChange((value: boolean) => { 217 console.info('Checkbox1 change is' + value) 218 }) 219 Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 220 }.margin({ left: 36 }) 221 222 // 选项2 223 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 224 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 225 .selectedColor('#007DFF') 226 .shape(CheckBoxShape.ROUNDED_SQUARE) 227 .onChange((value: boolean) => { 228 console.info('Checkbox2 change is' + value) 229 }) 230 Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 231 }.margin({ left: 36 }) 232 233 // 选项3 234 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 235 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 236 .selectedColor('#007DFF') 237 .shape(CheckBoxShape.ROUNDED_SQUARE) 238 .onChange((value: boolean) => { 239 console.info('Checkbox3 change is' + value) 240 }) 241 Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 242 }.margin({ left: 36 }) 243 } 244 } 245 } 246} 247``` 248 249 250### 示例2（自定义勾选样式） 251 252该示例通过配置mark实现自定义多选框群组的勾选样式。 253 254```ts 255// xxx.ets 256@Entry 257@Component 258struct Index { 259 260 build() { 261 Row() { 262 Column() { 263 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 264 CheckboxGroup({ group: 'checkboxGroup' }) 265 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 266 .selectedColor(Color.Orange) 267 .onChange((itemName: CheckboxGroupResult) => { 268 console.info("checkbox group content" + JSON.stringify(itemName)) 269 }) 270 .mark({ 271 strokeColor:Color.Black, 272 size: 40, 273 strokeWidth: 5 274 }) 275 .unselectedColor(Color.Red) 276 .width(30) 277 .height(30) 278 Text('Select All').fontSize(20) 279 }.margin({right:15}) 280 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 281 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 282 .selectedColor(0x39a2db) 283 .shape(CheckBoxShape.ROUNDED_SQUARE) 284 .onChange((value: boolean) => { 285 console.info('Checkbox1 change is'+ value) 286 }) 287 .mark({ 288 strokeColor:Color.Black, 289 size: 50, 290 strokeWidth: 5 291 }) 292 .unselectedColor(Color.Red) 293 .width(30) 294 .height(30) 295 Text('Checkbox1').fontSize(20) 296 } 297 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 298 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 299 .selectedColor(0x39a2db) 300 .shape(CheckBoxShape.ROUNDED_SQUARE) 301 .onChange((value: boolean) => { 302 console.info('Checkbox2 change is' + value) 303 }) 304 .width(30) 305 .height(30) 306 Text('Checkbox2').fontSize(20) 307 } 308 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 309 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 310 .selectedColor(0x39a2db) 311 .shape(CheckBoxShape.ROUNDED_SQUARE) 312 .onChange((value: boolean) => { 313 console.info('Checkbox3 change is' + value) 314 }) 315 .width(30) 316 .height(30) 317 Text('Checkbox3').fontSize(20) 318 } 319 } 320 .width('100%') 321 } 322 .height('100%') 323 } 324} 325``` 326 327 328 329
