输入类 · Checkbox
复选框
复选框允许用户选中多个选项

使用场景

  • 勾选框可以让用户在两种相反的状态、行为或取值之间选择;
  • 适用于在列表中选择单个或多个选项,开启或关闭某个选项

代码演示

如何引入

基本用法

Checkbox单个使用,可以通过defaultCheckedchecked属性控制是否勾选。
当传入checked时,为受控使用。
带辅助文本的checkbox。通过extra传入辅助文本。辅助文本会更长一些,甚至还可能换行。

禁用

通过设置 disabled 属性,禁用 Checkbox

JSX方式声明Checkbox组

通过在CheckboxGroup内部放置 Checkbox元素,可以声明Checkbox组
使用Checkbox组,你可以更便捷地通过CheckboxGroup的defaultValuevalue属性去控制一组Checkbox的选中与否 此时Checkbox不需要再声明defaultCheckedchecked属性

数组方式声明 Checkbox 组

也可以将数组通过 options 属性直接传入 CheckboxGroup,直接生成 Checkbox 组

水平排列

通过设置 directionhorizontal 或者 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

参数说明类型默认值
addonIdaddon 节点 id,aria-labelledby 指向这个 id,若无设置会随机生成一个 id
v2.11.0 后提供
string
aria-label定义 Checkbox 的作用string-
checked指定当前Checkbox是否选中(在Group中使用时无效)booleanfalse
type设置checkbox 的样式类型,可选值为: defaultcardpureCard
v2.18.0 后提供
stringdefault
defaultChecked初始是否选中(在Group中使用时无效)booleanfalse
disabled失效状态booleanfalse
extra副文本
v0.25.0后提供
ReactNode-
extraId副文本的 id,aria-describedby 指向这个 id,若无设置会随机生成一个 id
v2.11.0 后提供
ReactNode-
value该checkbox在CheckboxGroup中代表的valueany-
indeterminate设置 indeterminate 状态,只负责样式控制booleanfalse
preventScroll指示浏览器是否应滚动文档以显示新聚焦的元素,作用于组件内的 focus 方法boolean
onChange变化时回调函数function(e:Event)-

Checkbox Group

参数说明类型默认值
defaultValue组内默认选中的选项,会与Checkbox的value值做匹配any[][]
direction组内checkbox布局,可选水平horizontalverticalstringvertical
disabled整组失效booleanfalse
nameCheckboxGroup 下所有 input[type="checkbox"]name 属性string-
options指定可选项any[][]
type设置所有 checkbox 的样式类型,可选值为: defaultcardpureCard
v1.30.0 后提供
stringdefault
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 表示当前的选中状态

键盘和焦点

  • Checkbox 可被获取焦点,键盘用户可以使用 Tab 及 Shift + Tab 切换焦点。
  • 当前获取的焦点为 Checkbox 时,可以通过 Space 切换选中和未选状态。
  • Checkbox 的点击区域大于框本身,包含了框后的文案;带辅助文本的 checkbox,辅助文本也包含在点击区域内。
  • 禁用的 Checkbox 不可获取焦点。

文案规范

Checkbox Content Demo
Call
IM
Ticket
Offline
Buzz
  • 首字母大写
  • 不使用标点符号
✅ 推荐用法❌ 不推荐用法
Callcall
CallCall;

设计变量