使用场景
- 勾选框可以让用户在两种相反的状态、行为或取值之间选择;
- 适用于在列表中选择单个或多个选项，开启或关闭某个选项
代码演示
如何引入
import { Checkbox, CheckboxGroup } from '@kousum/semi-ui-vue';基本用法
Checkbox 单个使用，可以通过defaultChecked、checked属性控制是否勾选。
当传入checked时，为受控使用。
带辅助文本的 checkbox。通过extra传入辅助文本。辅助文本会更长一些，甚至还可能换行。
禁用
通过设置 disabled 属性，禁用 Checkbox
JSX 方式声明 Checkbox 组
通过在 CheckboxGroup 内部放置 Checkbox 元素，可以声明 Checkbox 组
使用 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 | | type | 设置 checkbox 的样式类型，可选值为: default、card、pureCard
v2.18.0 后提供 | string | default | | 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 | | preventScroll | 指示浏览器是否应滚动文档以显示新聚焦的元素，作用于组件内的 focus 方法 | boolean | | | | 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表示当前的选中状态
键盘和焦点
- Checkbox 可被获取焦点，键盘用户可以使用 Tab 及 Shift + Tab 切换焦点。
- 当前获取的焦点为 Checkbox 时，可以通过 Space 切换选中和未选状态。
- Checkbox 的点击区域大于框本身，包含了框后的文案；带辅助文本的 checkbox，辅助文本也包含在点击区域内。
- 禁用的 Checkbox 不可获取焦点。
文案规范
<div style={{ border: '1px solid var(--semi-color-border)', padding: 10, marginBottom: 24 }}>
<p style={{ fontWeight: 600, fontSize: 16 }}>Checkbox Content Demo</p>
<CheckboxGroup
options={[
{ label: 'Call', value: 'abc' },
{ label: 'IM', value: 'c' },
{ label: 'Ticket', value: 'd' },
{ label: 'Offline', value: 'e' },
{ label: 'Buzz', value: 'f' },
]}
direction="horizontal"
aria-label="CheckboxGroup 示例"
style={{ marginTop: 10 }}
/>
</div>- 首字母大写
- 不使用标点符号
| ✅ 推荐用法 | ❌ 不推荐用法 |
|---|---|
| Call | call |
| Call | Call; |