使用场景
- 勾选框可以让用户在两种相反的状态、行为或取值之间选择;
- 适用于在列表中选择单个或多个选项,开启或关闭某个选项
代码演示
如何引入
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
</script>
基本用法
Checkbox单个使用,可以通过defaultChecked、modelValue(v-model)控制是否勾选。
当传入modelValue时,为受控使用。
代码
<script setup lang="ts">
import { Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-vue';
const onChange = (e: CheckboxEvent) => console.log(e);
</script>
<template>
<Checkbox aria-label="Checkbox 示例" @change="onChange">Semi Design</Checkbox>
</template>代码
<script setup lang="ts">
import { Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-vue';
const onChange = (e: CheckboxEvent) => console.log(e);
</script>
<template>
<Checkbox aria-label="Checkbox 示例" defaultChecked @change="onChange">Semi Design</Checkbox>
</template>带辅助文本的checkbox。通过#extra插槽传入辅助文本。辅助文本会更长一些,甚至还可能换行。
代码
<script setup lang="ts">
import { Checkbox } from '@fibrous/semi-ui-vue';
const extra = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
</script>
<template>
<Checkbox aria-label="Checkbox 示例">
Semi Design
<template #extra>{{ extra }}</template>
</Checkbox>
<br />
<Checkbox aria-label="Checkbox 示例" :style="{ width: '280px' }">
Semi Design
<template #extra>{{ extra }}</template>
</Checkbox>
</template>禁用
通过设置 disabled 属性,禁用 Checkbox
代码
<script setup lang="ts">
import { Checkbox } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Checkbox aria-label="Checkbox 示例" :defaultChecked="false" disabled>Unchecked Disabled</Checkbox>
<br />
<Checkbox aria-label="Checkbox 示例" defaultChecked disabled>Checked Disabled</Checkbox>
</div>
</template>JSX方式声明Checkbox组
通过在CheckboxGroup内部放置 Checkbox元素,可以声明Checkbox组
使用Checkbox组,你可以更便捷地通过CheckboxGroup的defaultValue、modelValue(v-model)去控制一组Checkbox的选中与否,此时Checkbox不需要再声明defaultChecked、modelValue
代码
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
const values = ['A', 'B', 'C', 'D', 'E'];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['A', 'B']" :style="{ width: '100%' }">
<Checkbox v-for="value in values" :key="value" :value="value">{{ value }}</Checkbox>
</CheckboxGroup>
</template>数组方式声明 Checkbox 组
也可以将数组通过 options 属性直接传入 CheckboxGroup,直接生成 Checkbox 组
代码
<script setup lang="ts">
import { CheckboxGroup, type CheckboxValue } from '@fibrous/semi-ui-vue';
const onChange = (checkedValues: CheckboxValue[]) => console.log('checked = ', checkedValues);
const plainOptions = ['Semi UI', 'Semi DSM', 'Semi D2C'];
const optionsWithExtra = [
{
extra: '从 Semi Design,到 Any Design 快速定制你的设计系统,并应用在设计稿和代码中',
label: 'Semi DSM',
value: 'dsm',
},
{ extra: '高效的 Design To Code 设计稿转代码', label: 'Semi D2C', value: 'd2c' },
];
const optionsWithDisabled = [
{ label: 'Photography', value: 'Photography' },
{ label: 'Movies', value: 'Movies' },
{ label: 'Running', value: 'Running', disabled: false },
];
</script>
<template>
<div>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['Semi D2C']" :options="plainOptions" @change="onChange" />
<br />
<br />
<CheckboxGroup aria-label="带 extra 示例" :defaultValue="[]" :options="optionsWithExtra" @change="onChange" />
<br />
<br />
<CheckboxGroup aria-label="Checkbox 示例" :defaultValue="['Photography']" disabled :options="optionsWithDisabled" @change="onChange" />
</div>
</template>水平排列
通过设置 direction 为 horizontal 或者 vertical 可以调整 CheckboxGroup 内的布局
代码
<script setup lang="ts">
import { CheckboxGroup } from '@fibrous/semi-ui-vue';
const options = [
{ label: '抖音', value: 'abc' },
{ label: '今日头条', value: 'toutiao' },
];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" direction="horizontal" :options="options" />
</template>受控
联动 checkbox。
代码
<script setup lang="ts">
import { computed, ref } from 'vue';
import { Button, Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-vue';
const checked = ref(true);
const disabled = ref(false);
const label = computed(() => `${checked.value ? 'Checked' : 'Unchecked'} ${disabled.value ? 'Disabled' : 'Enabled'}`);
const onChange = (e: CheckboxEvent) => console.log('checked = ', e.target.checked);
</script>
<template>
<div>
<div :style="{ marginBottom: '20px' }">
<Checkbox v-model="checked" aria-label="Checkbox 示例" :disabled="disabled" @change="onChange">
{{ label }}
</Checkbox>
</div>
<p>
<Button size="small" type="primary" @click="checked = !checked">{{ !checked ? 'Check' : 'Uncheck' }}</Button>
<Button size="small" :style="{ marginLeft: '10px' }" type="primary" @click="disabled = !disabled">
{{ !disabled ? 'Disable' : 'Enable' }}
</Button>
</p>
</div>
</template>全选
在实现全选效果时,你可能会用到 indeterminate 属性。
代码
<script setup lang="ts">
import { computed, ref } from 'vue';
import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrous/semi-ui-vue';
const plainOptions = ['Photography', 'Movies', 'Running'];
const checkedList = ref<CheckboxValue[]>(['Photography', 'Running']);
const checkAll = computed(() => checkedList.value.length === plainOptions.length);
const indeterminate = computed(() => checkedList.value.length > 0 && !checkAll.value);
const onCheckAllChange = (e: CheckboxEvent) => {
console.log(e);
checkedList.value = e.target.checked ? plainOptions : [];
};
</script>
<template>
<div>
<div :style="{ paddingBottom: '8px', borderBottom: '1px solid var(--semi-color-border)' }">
<Checkbox aria-label="Checkbox 示例" :indeterminate="indeterminate" :modelValue="checkAll" @change="onCheckAllChange"> Check all </Checkbox>
</div>
<CheckboxGroup v-model="checkedList" aria-label="CheckboxGroup 示例" :options="plainOptions" :style="{ marginTop: '6px' }" />
</div>
</template>卡片样式
可以给 CheckboxGroup 设置 type='card',实现带有背景的卡片样式。
代码
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
const extra = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
const items = [
{ value: '1', disabled: true },
{ value: '2', disabled: true },
{ value: '3', disabled: false },
{ value: '4', disabled: false },
];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['1', '3']" direction="vertical" type="card">
<Checkbox v-for="item in items" :key="item.value" :disabled="item.disabled" :style="{ width: '280px' }" :value="item.value">
单选框标题
<template #extra>{{ extra }}</template>
</Checkbox>
</CheckboxGroup>
</template>无 checkbox 的纯卡片样式
可以给 CheckboxGroup 设置 type='pureCard',实现带有背景且无 checkbox 的纯卡片样式。
代码
<script setup lang="ts">
import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
const extra = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
const items = [
{ value: '1', disabled: true },
{ value: '2', disabled: true },
{ value: '3', disabled: false },
{ value: '4', disabled: false },
];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :defaultValue="['1', '3']" direction="vertical" type="pureCard">
<Checkbox v-for="item in items" :key="item.value" :disabled="item.disabled" :style="{ width: '280px' }" :value="item.value">
单选框标题
<template #extra>{{ extra }}</template>
</Checkbox>
</CheckboxGroup>
</template>配合grid布局
CheckboxGroup 内嵌 Checkbox 并与 Grid 组件一起使用,可以实现灵活的布局。
代码
<script setup lang="ts">
import { Checkbox, CheckboxGroup, Col, Row } from '@fibrous/semi-ui-vue';
const values = ['A', 'B', 'C', 'D', 'E'];
</script>
<template>
<CheckboxGroup aria-label="CheckboxGroup 示例" :style="{ width: '100%' }">
<Row>
<Col v-for="value in values" :key="value" :span="8">
<Checkbox :value="value">{{ value }}</Checkbox>
</Col>
</Row>
</CheckboxGroup>
</template>API参考
Checkbox
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| modelValue | 是否选中,配合 v-model 受控使用;在 CheckboxGroup 中使用时无效。 | boolean | undefined |
| defaultChecked | 初始是否选中,非受控使用;在 CheckboxGroup 中使用时无效。 | boolean | semiDefault("Checkbox", "defaultChecked", false) |
| value | 该 Checkbox 在 CheckboxGroup 中代表的值;不设置时它不属于任何分组。 | CheckboxValue | undefined |
| disabled | 是否禁用。 | boolean | semiGlobalDefault("Checkbox", "disabled") |
| indeterminate | 半选状态,只影响外观与原生 input 的 indeterminate,不改变选中值。 | boolean | semiDefault("Checkbox", "indeterminate", false) |
| type | 样式类型,可选 default、card、pureCard;在 CheckboxGroup 中以组的 type 为准。 | CheckboxType | semiDefault("Checkbox", "type", "default") |
| addonId | addon 节点的 id,aria-labelledby 指向这个 id;未设置时随机生成。 | string | undefined |
| extraId | extra 节点的 id,aria-describedby 指向这个 id;未设置时随机生成。 | string | undefined |
| prefixCls | CSS 类名前缀。 | string | semiGlobalDefault("Checkbox", "prefixCls") |
| preventScroll | 聚焦时是否阻止浏览器滚动到该元素,作用于 focus 方法。 | boolean | semiGlobalDefault("Checkbox", "preventScroll") |
Events
| 事件 | 说明 | 回调参数 |
|---|---|---|
| update:modelValue | 选中状态变化时触发,用于 v-model。 | [checked: boolean] |
| change | 选中状态变化时触发,参数的 target 为 { checked, value, name, disabled }。 | [event: CheckboxEvent] |
Slots
| 插槽 | 说明 | 作用域参数 |
|---|---|---|
| default | Checkbox 的文本内容,同时是原生 input 的可访问名称。 | any |
| extra | 辅助文本,aria-describedby 指向它。 | any |
Exposes
| 名称 | 说明 | 类型 |
|---|---|---|
| focus | 使原生 input 获得焦点。 | Type() => void |
| blur | 使原生 input 失去焦点。 | Type() => void |
class、style 落在根元素上。id、name、tabindex、autofocus、aria-* 与 focus、blur 监听经 attrs 落在内部的原生 input 上,其余原生属性与事件监听(如 @mouseenter)落在根元素上。name 在 CheckboxGroup 中以组的 name 为准。
Checkbox Group
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| modelValue | 选中的值,配合 v-model 受控使用。 | CheckboxValue[] | undefined |
| defaultValue | 非受控时组内默认选中的值,与 Checkbox 的 value 匹配。 | CheckboxValue[] | semiDefault("CheckboxGroup", "defaultValue", []) |
| disabled | 是否禁用整组。 | boolean | semiDefault("CheckboxGroup", "disabled", false) |
| name | 组内所有原生 input 的 name;未设置时每组生成唯一值。 | string | semiGlobalDefault("CheckboxGroup", "name") |
| options | 以配置形式声明选项,元素为字符串或 { label, value, disabled, extra, class, style }。 | (string | CheckboxOptionItem)[] | semiGlobalDefault("CheckboxGroup", "options") |
| direction | 组内布局方向,可选 horizontal 或 vertical。 | CheckboxDirection | semiDefault("CheckboxGroup", "direction", "vertical") |
| type | 组内所有 Checkbox 的样式类型,可选 default、card、pureCard。 | CheckboxType | semiDefault("CheckboxGroup", "type", "default") |
| prefixCls | CSS 类名前缀。 | string | semiGlobalDefault("CheckboxGroup", "prefixCls") |
Events
| 事件 | 说明 | 回调参数 |
|---|---|---|
| update:modelValue | 选中的值变化时触发,用于 v-model。 | [value: CheckboxValue[]] |
| change | 选中的值变化时触发,参数为新的选中值数组。 | [value: CheckboxValue[]] |
| blur | 焦点离开整个分组时触发,在组内 Checkbox 之间移动焦点不触发。 | [event: FocusEvent] |
Slots
| 插槽 | 说明 | 作用域参数 |
|---|---|---|
| default | 组内的 Checkbox;设置 options 时忽略。 | any |
| label | 自定义 options 中每一项的文本,作用域参数为 option 与 index。 | CheckboxGroupOptionSlotProps |
| extra | 自定义 options 中每一项的辅助文本,作用域参数为 option 与 index。 | CheckboxGroupOptionSlotProps |
Exposes
| 名称 | 说明 | 类型 |
|---|---|---|
| 无 |
options 项的字段为 label、value、disabled、extra(string | number)、class、style,没有 onChange;需要自定义内容时使用 #label、#extra 作用域插槽。class、style 与原生属性经 attrs 落在根元素上;aria-invalid、aria-errormessage 传给组内每个 Checkbox 的原生 input,aria-required、tabindex 以及 Tooltip 注入的 aria-expanded、aria-haspopup、aria-controls 不输出。
方法
Checkbox
通过模板 ref 取得组件实例后调用,说明见上方 Exposes。
Accessibility
ARIA
- Checkbox 的 role 为
checkbox,CheckboxGroup 的 role 为group,它的子元素没有额外的 role aria-label:单独使用 Checkbox 时,如果 Children 没有文本,建议传入aria-labelprop,用一句话描述 Checkbox 的作用,这会让屏幕阅读器读出这个标签的内容- 原生 input 的
aria-labelledby指向addon节点,用于解释当前 Checkbox 的作用;传入的aria-labelledby也落在 input 上,排在addonid 之前 aria-describedby指向extra节点,用于补充解释当前 Checkbox 的作用- 选中与禁用状态由原生 input 的
checked、disabled表达,不输出aria-checked、aria-disabled
键盘和焦点
- Checkbox 可被获取焦点,键盘用户可以使用 Tab 及 Shift + Tab 切换焦点。
- 当前获取的焦点为 Checkbox 时,可以通过 Space 切换选中和未选状态。
- Checkbox 的点击区域大于框本身,包含了框后的文案;带辅助文本的 checkbox,辅助文本也包含在点击区域内。
- 禁用的 Checkbox 不可获取焦点。
文案规范
Checkbox Content Demo
- 首字母大写
- 不使用标点符号
| ✅ 推荐用法 | ❌ 不推荐用法 |
|---|---|
| Call | call |
| Call | Call; |
设计变量
| Sass 变量 | 值 | 用法 |
|---|---|---|
| $transition_duration-checkbox-bg | var(--semi-transition_duration-none) | 复选框-背景色-动画持续时间 |
| $transition_function-checkbox-bg | var(--semi-transition_function-easeIn) | 复选框-背景色-过渡曲线 |
| $transition_delay-checkbox-bg | var(--semi-transition_delay-none) | 复选框-背景色-延迟时间 |
| $transition_duration-checkbox-border | var(--semi-transition_duration-none) | 复选框-边框-动画持续时间 |
| $transition_function-checkbox-border | var(--semi-transition_function-easeIn) | 复选框-边框-过渡曲线 |
| $transition_delay-checkbox-border | var(--semi-transition_delay-none) | 复选框-边框-延迟时间 |
| $transform_scale-checkbox | var(--semi-transform_scale-none) | 复选框-放大 |
| $spacing-checkbox_label-paddingLeft | $spacing-tight | 文字与选框间距 |
| $color-checkbox_label-text-default | var(--semi-color-text-0) | 文字颜色 |
| $color-checkbox_default-bg-hover | var(--semi-color-fill-0) | 选框背景颜色 - 悬浮 |
| $color-checkbox_default-bg-default | transparent | 复选框内部勾选框背景色 - 默认态 |
| $color-checkbox_default-border-hover | var(--semi-color-focus-border) | 复选框内部勾选框描边颜色 - 悬停态 |
| $color-checkbox_default-border-default | var(--semi-color-text-3) | 复选框内部勾选框描边颜色 - 默认态 |
| $color-checkbox_default-bg-active | var(--semi-color-fill-1) | 选框未选中态背景颜色 - 按下 |
| $font-checkbox_label-lineHeight | 20px | 文字行高 |
| $color-checkbox_label-text-disabled | var(--semi-color-disabled-text) | 禁用文字颜色 |
| $color-checkbox_checked-bg-default | var(--semi-color-primary) | 复选框选中态内部勾选框背景色 - 默认态 |
| $color-checkbox_checked-bg-hover | var(--semi-color-primary-hover) | 选框选中态背景颜色 - 悬浮 |
| $color-checkbox_checked-bg-active | var(--semi-color-primary-active) | 选框选中态背景颜色 - 按下 |
| $color-checkbox_checked-icon-default | var(--semi-color-white) | 选框选中态对勾颜色 - 默认 |
| $color-checkbox_checked-icon-hover | var(--semi-color-white) | 选框选中态对勾颜色 - 悬浮 |
| $color-checkbox_checked-icon-active | var(--semi-color-white) | 选框选中态对勾颜色 - 按下 |
| $color-checkbox_checked-border-default | var(--semi-color-primary) | 选框选中态描边颜色 - 默认 |
| $color-checkbox_checked-border-hover | var(--semi-color-primary-hover) | 选框选中态描边颜色 - 悬浮 |
| $color-checkbox_checked-border-active | var(--semi-color-primary-active) | 选框选中态描边颜色 - 按下 |
| $color-checkbox_cardType_checked-bg | var(--semi-color-primary-light-default) | 卡片类型复选框选中时的背景颜色 - 默认 |
| $color-checkbox_cardType_checked_disabled-bg | var(--semi-color-primary-light-default) | 卡片类型复选框选中且禁用时的背景颜色 - 默认 |
| $color-checkbox_cardType-bg-hover | var(--semi-color-fill-0) | 卡片类型复选框选中时的背景颜色 - 悬浮 |
| $color-checkbox_cardType-bg-active | var(--semi-color-fill-1) | 卡片类型复选框选中时的背景颜色 - 按下 |
| $color-checkbox_cardType_checked_border-default | var(--semi-color-primary) | 卡片类型复选框选中时的边框颜色 - 默认 |
| $color-checkbox_cardType_checked_border-hover | var(--semi-color-primary-hover) | 卡片类型复选框选中时的边框颜色 - 悬浮 |
| $color-checkbox_cardType_checked_border-active | var(--semi-color-primary-active) | 卡片类型复选框选中时的边框颜色 - 按下 |
| $color-checkbox_cardType_checked_disabled_border-default | var(--semi-color-primary-disabled) | 卡片类型复选框选中且禁用时的边框颜色 - 默认 |
| $color-checkbox_cardType_addon-text-default | var(--semi-color-text-0) | 卡片类型复选框标题文本颜色 - 默认 |
| $color-checkbox_cardType_extra-text-default | var(--semi-color-text-2) | 卡片复选框副标题文本颜色 - 默认 |
| $color-checkbox_cardType_inner-bg-hover | var(--semi-color-white) | 卡片复选框内部勾选框背景色 - 悬浮 |
| $color-checkbox_cardType_inner-bg-active | var(--semi-color-white) | 卡片复选框内部勾选框背景色 - 按下 |
| $color-checkbox_cardType_inner-bg-default | var(--semi-color-white) | 卡片复选框内部勾选框背景色 -默认 |
| $color-checkbox_disabled-bg-default | var(--semi-color-disabled-fill) | 选框禁用态背景颜色 - 默认 |
| $color-checkbox_disabled-border-default | var(--semi-color-border) | 选框禁用态描边颜色 - 默认 |
| $color-checkbox_checked-bg-disabled | var(--semi-color-primary-disabled) | 选框选中 + 禁用态背景颜色 |
| $color-checkbox_checked-icon-disabled | var(--semi-color-white) | 选框禁用态对勾颜色 |
| $color-checkbox_primary-outline-focus | $color-focus-ring | 复选框轮廓-聚焦颜色 |
| $color-checkbox_cardType-border-default | transparent | 卡片复选框默认边框颜色 |
| $size-checkbox_inner-shadow | $border-thickness-control | 选框内描边宽度 |
| $width-checkbox_inner | $width-icon-medium | 选框对勾 icon 宽度 |
| $height-checkbox_inner | 20px | 选框对勾 icon 高度 |
| $width-checkbox_cardType_checked-border | 1px | 卡片类型复选框的边框宽度 |
| $width-checkbox_cardType_checked_disabled-border | 1px | 卡片类型复选框选中且禁用的边框宽度 |
| $width-checkbox-outline | $width-focus-ring | 复选框轮廓宽度 |
| $radius-checkbox_cardType | 3px | 卡片类型复选框的圆角大小 |
| $radius-checkbox_inner | var(--semi-border-radius-extra-small) | 复选框内部勾选框圆角 |
| $spacing-checkbox_extra-marginTop | $spacing-extra-tight | 复选框副标题顶部内边距 |
| $spacing-checkbox_cardType-paddingX | $spacing-base | 卡片类型复选框的水平内间距 |
| $spacing-checkbox_cardType-paddingY | $spacing-base-tight | 卡片类型复选框的垂直内间距 |
| $spacing-checkbox_card_group_vertical-marginBottom | $spacing-base | 卡片样式复选框的下间距 |
| $color-checkbox_extra-text-default | var(--semi-color-text-2) | 复选框副标题文本颜色 |
| $spacing-checkbox_group_vertical-marginBottom | $spacing-base | |
| $spacing-checkbox_group_vertical_item-marginBottom | $spacing-base-tight | 垂直复选框组底部外边距 |
| $spacing-checkbox_group_horizontal-marginRight | $spacing-base | 水平复选框组右侧外边距 |
| $font-checkbox_cardType_addon-size | $font-size-regular | 卡片类型复选框标题文本大小 |
| $font-checkbox_cardType_addon-fontWeight | $font-weight-bold | 卡片类型复选框的标题的 fontWeight |
| $font-checkbox_cardType_addon-lineHeight | 20px | 卡片类型复选框的标题的文字行高 |
| $font-checkbox_cardType_extra-size | $font-size-regular | 卡片类型复选框的副标题的文字大小 |
| $font-checkbox_cardType_extra-fontWeight | normal | 卡片类型复选框的副标题的 fontWeight |
| $font-checkbox_cardType_extra-lineHeight | 20px | 卡片类型复选框的副标题的文字行高 |