输入类

复选框

复选框允许用户选中多个选项

使用场景

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

代码演示

如何引入

<script setup lang="ts">
    import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-vue';
</script>

基本用法

Checkbox单个使用,可以通过defaultChecked、modelValue(v-model)控制是否勾选。
当传入modelValue时,为受控使用。

Semi Design
代码
<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>
Semi Design
代码
<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插槽传入辅助文本。辅助文本会更长一些,甚至还可能换行。

Semi Design
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统

Semi Design
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
代码
<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

Unchecked Disabled

Checked Disabled
代码
<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

A
B
C
D
E
代码
<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 组

Semi UI
Semi DSM
Semi D2C


Semi DSM
从 Semi Design,到 Any Design 快速定制你的设计系统,并应用在设计稿和代码中
Semi D2C
高效的 Design To Code 设计稿转代码


Photography
Movies
Running
代码
<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。

Checked Enabled

代码
<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 属性。

Check all
Photography
Movies
Running
代码
<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',实现带有背景的卡片样式。

单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
代码
<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 的纯卡片样式。

单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
代码
<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 组件一起使用,可以实现灵活的布局。

A
B
C
D
E
代码
<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 中使用时无效。booleanundefined
defaultChecked初始是否选中,非受控使用;在 CheckboxGroup 中使用时无效。booleansemiDefault("Checkbox", "defaultChecked", false)
value该 Checkbox 在 CheckboxGroup 中代表的值;不设置时它不属于任何分组。CheckboxValueundefined
disabled是否禁用。booleansemiGlobalDefault("Checkbox", "disabled")
indeterminate半选状态,只影响外观与原生 input 的 indeterminate,不改变选中值。booleansemiDefault("Checkbox", "indeterminate", false)
type样式类型,可选 default、card、pureCard;在 CheckboxGroup 中以组的 type 为准。CheckboxTypesemiDefault("Checkbox", "type", "default")
addonIdaddon 节点的 id,aria-labelledby 指向这个 id;未设置时随机生成。stringundefined
extraIdextra 节点的 id,aria-describedby 指向这个 id;未设置时随机生成。stringundefined
prefixClsCSS 类名前缀。stringsemiGlobalDefault("Checkbox", "prefixCls")
preventScroll聚焦时是否阻止浏览器滚动到该元素,作用于 focus 方法。booleansemiGlobalDefault("Checkbox", "preventScroll")

Events

事件说明回调参数
update:modelValue选中状态变化时触发,用于 v-model。[checked: boolean]
change选中状态变化时触发,参数的 target 为 { checked, value, name, disabled }。[event: CheckboxEvent]

Slots

插槽说明作用域参数
defaultCheckbox 的文本内容,同时是原生 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是否禁用整组。booleansemiDefault("CheckboxGroup", "disabled", false)
name组内所有原生 input 的 name;未设置时每组生成唯一值。stringsemiGlobalDefault("CheckboxGroup", "name")
options以配置形式声明选项,元素为字符串或 { label, value, disabled, extra, class, style }。(string | CheckboxOptionItem)[]semiGlobalDefault("CheckboxGroup", "options")
direction组内布局方向,可选 horizontal 或 vertical。CheckboxDirectionsemiDefault("CheckboxGroup", "direction", "vertical")
type组内所有 Checkbox 的样式类型,可选 default、card、pureCard。CheckboxTypesemiDefault("CheckboxGroup", "type", "default")
prefixClsCSS 类名前缀。stringsemiGlobalDefault("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-label prop,用一句话描述 Checkbox 的作用,这会让屏幕阅读器读出这个标签的内容
  • 原生 input 的 aria-labelledby 指向 addon 节点,用于解释当前 Checkbox 的作用;传入的 aria-labelledby 也落在 input 上,排在 addon id 之前
  • aria-describedby 指向 extra 节点,用于补充解释当前 Checkbox 的作用
  • 选中与禁用状态由原生 input 的 checked、disabled 表达,不输出 aria-checked、aria-disabled

键盘和焦点

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

文案规范

Checkbox Content Demo

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

设计变量

下表是组件内部的 Sass 变量,不能覆写。定制样式请覆写 --semi-* CSS 变量(见 Design Token 页),或写不分层的 CSS 规则。
Sass 变量值用法
$transition_duration-checkbox-bgvar(--semi-transition_duration-none)复选框-背景色-动画持续时间
$transition_function-checkbox-bgvar(--semi-transition_function-easeIn)复选框-背景色-过渡曲线
$transition_delay-checkbox-bgvar(--semi-transition_delay-none)复选框-背景色-延迟时间
$transition_duration-checkbox-bordervar(--semi-transition_duration-none)复选框-边框-动画持续时间
$transition_function-checkbox-bordervar(--semi-transition_function-easeIn)复选框-边框-过渡曲线
$transition_delay-checkbox-bordervar(--semi-transition_delay-none)复选框-边框-延迟时间
$transform_scale-checkboxvar(--semi-transform_scale-none)复选框-放大
$spacing-checkbox_label-paddingLeft$spacing-tight文字与选框间距
$color-checkbox_label-text-defaultvar(--semi-color-text-0)文字颜色
$color-checkbox_default-bg-hovervar(--semi-color-fill-0)选框背景颜色 - 悬浮
$color-checkbox_default-bg-defaulttransparent复选框内部勾选框背景色 - 默认态
$color-checkbox_default-border-hovervar(--semi-color-focus-border)复选框内部勾选框描边颜色 - 悬停态
$color-checkbox_default-border-defaultvar(--semi-color-text-3)复选框内部勾选框描边颜色 - 默认态
$color-checkbox_default-bg-activevar(--semi-color-fill-1)选框未选中态背景颜色 - 按下
$font-checkbox_label-lineHeight20px文字行高
$color-checkbox_label-text-disabledvar(--semi-color-disabled-text)禁用文字颜色
$color-checkbox_checked-bg-defaultvar(--semi-color-primary)复选框选中态内部勾选框背景色 - 默认态
$color-checkbox_checked-bg-hovervar(--semi-color-primary-hover)选框选中态背景颜色 - 悬浮
$color-checkbox_checked-bg-activevar(--semi-color-primary-active)选框选中态背景颜色 - 按下
$color-checkbox_checked-icon-defaultvar(--semi-color-white)选框选中态对勾颜色 - 默认
$color-checkbox_checked-icon-hovervar(--semi-color-white)选框选中态对勾颜色 - 悬浮
$color-checkbox_checked-icon-activevar(--semi-color-white)选框选中态对勾颜色 - 按下
$color-checkbox_checked-border-defaultvar(--semi-color-primary)选框选中态描边颜色 - 默认
$color-checkbox_checked-border-hovervar(--semi-color-primary-hover)选框选中态描边颜色 - 悬浮
$color-checkbox_checked-border-activevar(--semi-color-primary-active)选框选中态描边颜色 - 按下
$color-checkbox_cardType_checked-bgvar(--semi-color-primary-light-default)卡片类型复选框选中时的背景颜色 - 默认
$color-checkbox_cardType_checked_disabled-bgvar(--semi-color-primary-light-default)卡片类型复选框选中且禁用时的背景颜色 - 默认
$color-checkbox_cardType-bg-hovervar(--semi-color-fill-0)卡片类型复选框选中时的背景颜色 - 悬浮
$color-checkbox_cardType-bg-activevar(--semi-color-fill-1)卡片类型复选框选中时的背景颜色 - 按下
$color-checkbox_cardType_checked_border-defaultvar(--semi-color-primary)卡片类型复选框选中时的边框颜色 - 默认
$color-checkbox_cardType_checked_border-hovervar(--semi-color-primary-hover)卡片类型复选框选中时的边框颜色 - 悬浮
$color-checkbox_cardType_checked_border-activevar(--semi-color-primary-active)卡片类型复选框选中时的边框颜色 - 按下
$color-checkbox_cardType_checked_disabled_border-defaultvar(--semi-color-primary-disabled)卡片类型复选框选中且禁用时的边框颜色 - 默认
$color-checkbox_cardType_addon-text-defaultvar(--semi-color-text-0)卡片类型复选框标题文本颜色 - 默认
$color-checkbox_cardType_extra-text-defaultvar(--semi-color-text-2)卡片复选框副标题文本颜色 - 默认
$color-checkbox_cardType_inner-bg-hovervar(--semi-color-white)卡片复选框内部勾选框背景色 - 悬浮
$color-checkbox_cardType_inner-bg-activevar(--semi-color-white)卡片复选框内部勾选框背景色 - 按下
$color-checkbox_cardType_inner-bg-defaultvar(--semi-color-white)卡片复选框内部勾选框背景色 -默认
$color-checkbox_disabled-bg-defaultvar(--semi-color-disabled-fill)选框禁用态背景颜色 - 默认
$color-checkbox_disabled-border-defaultvar(--semi-color-border)选框禁用态描边颜色 - 默认
$color-checkbox_checked-bg-disabledvar(--semi-color-primary-disabled)选框选中 + 禁用态背景颜色
$color-checkbox_checked-icon-disabledvar(--semi-color-white)选框禁用态对勾颜色
$color-checkbox_primary-outline-focus$color-focus-ring复选框轮廓-聚焦颜色
$color-checkbox_cardType-border-defaulttransparent卡片复选框默认边框颜色
$size-checkbox_inner-shadow$border-thickness-control选框内描边宽度
$width-checkbox_inner$width-icon-medium选框对勾 icon 宽度
$height-checkbox_inner20px选框对勾 icon 高度
$width-checkbox_cardType_checked-border1px卡片类型复选框的边框宽度
$width-checkbox_cardType_checked_disabled-border1px卡片类型复选框选中且禁用的边框宽度
$width-checkbox-outline$width-focus-ring复选框轮廓宽度
$radius-checkbox_cardType3px卡片类型复选框的圆角大小
$radius-checkbox_innervar(--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-defaultvar(--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-lineHeight20px卡片类型复选框的标题的文字行高
$font-checkbox_cardType_extra-size$font-size-regular卡片类型复选框的副标题的文字大小
$font-checkbox_cardType_extra-fontWeightnormal卡片类型复选框的副标题的 fontWeight
$font-checkbox_cardType_extra-lineHeight20px卡片类型复选框的副标题的文字行高