使用场景
- 勾选框可以让用户在两种相反的状态、行为或取值之间选择;
- 适用于在列表中选择单个或多个选项，开启或关闭某个选项
代码演示
如何引入
基本用法
Checkbox单个使用，可以通过
当传入
defaultChecked、checked属性控制是否勾选。当传入
checked时，为受控使用。 带辅助文本的checkbox。通过
extra传入辅助文本。辅助文本会更长一些，甚至还可能换行。禁用
通过设置
disabled 属性，禁用 CheckboxJSX方式声明Checkbox组
通过在CheckboxGroup内部放置 Checkbox元素，可以声明Checkbox组
使用Checkbox组，你可以更便捷地通过CheckboxGroup的
使用Checkbox组，你可以更便捷地通过CheckboxGroup的
defaultValue、value属性去控制一组Checkbox的选中与否
此时Checkbox不需要再声明defaultChecked、checked属性数组方式声明 Checkbox 组
也可以将数组通过
options 属性直接传入 CheckboxGroup，直接生成 Checkbox 组水平排列
通过设置
direction 为 horizontal 或者 vertical 可以调整 CheckboxGroup 内的布局受控
联动 checkbox。
全选
在实现全选效果时，你可能会用到
indeterminate 属性。卡片样式
version: >=1.30.0
可以给 CheckboxGroup 设置
type='card'，实现带有背景的卡片样式。无 checkbox 的纯卡片样式
version: >=1.30.0
可以给 CheckboxGroup 设置
type='pureCard'，实现带有背景且无 checkbox 的纯卡片样式。配合grid布局
Checkbox.Group 内嵌 Checkbox 并与 Grid 组件一起使用，可以实现灵活的布局。
API参考
Checkbox
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| addonId | addon 节点 id，aria-labelledby 指向这个 id，若无设置会随机生成一个 id v2.11.0 后提供 | string | |
| aria-label | 定义 Checkbox 的作用 | string | - |
| checked | 指定当前Checkbox是否选中（在Group中使用时无效） | boolean | false |
| defaultChecked | 初始是否选中（在Group中使用时无效） | boolean | false |
| disabled | 失效状态 | boolean | false |
| extra | 副文本 v0.25.0后提供 | ReactNode | - |
| extraId | 副文本的 id，aria-describedby 指向这个 id，若无设置会随机生成一个 id v2.11.0 后提供 | ReactNode | - |
| value | 该checkbox在CheckboxGroup中代表的value | any | - |
| indeterminate | 设置 indeterminate 状态，只负责样式控制 | boolean | false |
| onChange | 变化时回调函数 | function(e:Event) | - |
Checkbox Group
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| defaultValue | 组内默认选中的选项，会与Checkbox的value值做匹配 | any[] | [] |
| direction | 组内checkbox布局，可选水平horizontal或vertical | string | vertical |
| disabled | 整组失效 | boolean | false |
| name | CheckboxGroup 下所有 input[type="checkbox"] 的 name 属性 | string | - |
| options | 指定可选项 | any[] | [] |
| type | 设置所有 checkbox 的样式类型，可选值为: default、card、pureCard v1.30.0 后提供 | string | default |
| value | 指定选中的选项 | any[] | [] |
| onChange | 变化时回调函数 | function(checkedValue) | - |
方法
Checkbox
| 名称 | 描述 |
|---|---|
| blur() | 移除焦点 |
| focus() | 获取焦点 |
Accessibility
ARIA
- Checkbox 的 role 为
checkbox，CheckboxGroup 的 role 为list，它的直接子元素为listitem aria-label：单独使用 Checkbox 时，如果 Children 没有文本，建议传入aria-labelprop，用一句话描述 Checkbox 的作用，这会让屏幕阅读器读出这个标签的内容。如果你使用的是 Form.Checkbox，可以使用 Form 提供的 label 而无需传入aria-labelaria-labelledby指向addon节点，用于解释当前 Checkbox 的作用aria-describedby指向extra节点，用于补充解释当前 Checkbox 的作用aria-disabled表示当前的禁用状态，与disabledprop 的值保持一致aria-checked表示当前的选中状态
