使用场景
- 勾选框可以让用户在两种相反的状态、行为或取值之间选择;
- 适用于在列表中选择单个或多个选项,开启或关闭某个选项
代码演示
如何引入
基本用法
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-label
prop,用一句话描述 Checkbox 的作用,这会让屏幕阅读器读出这个标签的内容。如果你使用的是 Form.Checkbox,可以使用 Form 提供的 label 而无需传入aria-label
aria-labelledby
指向addon
节点,用于解释当前 Checkbox 的作用aria-describedby
指向extra
节点,用于补充解释当前 Checkbox 的作用aria-disabled
表示当前的禁用状态,与disabled
prop 的值保持一致aria-checked
表示当前的选中状态