输入类

复选框

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

使用场景

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

代码演示

如何引入

<script lang="ts">
    import { Checkbox, CheckboxGroup, Col, Row } from '@fibrae/semi-ui-svelte';
</script>

基本用法

Checkbox单个使用,只传 checked 时作为初始选中状态,之后由用户点击切换;需要读写选中状态时用 bind:checked,见「受控」。

Semi Design
代码
<script lang="ts">
    import { Checkbox, type CheckboxEvent } from '@fibrae/semi-ui-svelte';

    const onChange = (e: CheckboxEvent) => console.log(e);
</script>

<Checkbox aria-label="Checkbox 示例" {onChange}>Semi Design</Checkbox>
Semi Design
代码
<script lang="ts">
    import { Checkbox, type CheckboxEvent } from '@fibrae/semi-ui-svelte';

    const onChange = (e: CheckboxEvent) => console.log(e);
</script>

<Checkbox aria-label="Checkbox 示例" checked {onChange}>Semi Design</Checkbox>

带辅助文本的checkbox。extra 接受 snippet:在 Checkbox 标签内用 {#snippet extra()}...{/snippet} 定义,其余内容是文本内容。辅助文本会更长一些,甚至还可能换行。

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

Semi Design
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
代码
<script lang="ts">
    import { Checkbox } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
</script>

<Checkbox aria-label="Checkbox 示例">
    Semi Design
    {#snippet extra()}{extraText}{/snippet}
</Checkbox>
<br />
<Checkbox aria-label="Checkbox 示例" style="width: 280px">
    Semi Design
    {#snippet extra()}{extraText}{/snippet}
</Checkbox>

禁用

通过设置 disabled 属性,禁用 Checkbox

Unchecked Disabled

Checked Disabled
代码
<script lang="ts">
    import { Checkbox } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Checkbox aria-label="Checkbox 示例" checked={false} disabled>Unchecked Disabled</Checkbox>
    <br />
    <Checkbox aria-label="Checkbox 示例" checked disabled>Checked Disabled</Checkbox>
</div>

JSX方式声明Checkbox组

通过在CheckboxGroup内部放置 Checkbox元素,可以声明Checkbox组
使用Checkbox组,你可以更便捷地通过CheckboxGroup的 value 去控制一组Checkbox的选中与否:只传 value 作为初值,需要读写时用 bind:value,此时Checkbox不需要再声明 checked

A
B
C
D
E
代码
<script lang="ts">
    import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const values = ['A', 'B', 'C', 'D', 'E'];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" style="width: 100%" value={['A', 'B']}>
    {#each values as value (value)}
        <Checkbox {value}>{value}</Checkbox>
    {/each}
</CheckboxGroup>

数组方式声明 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 lang="ts">
    import { CheckboxGroup, type CheckboxValue } from '@fibrae/semi-ui-svelte';

    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>

<div>
    <CheckboxGroup aria-label="CheckboxGroup 示例" {onChange} options={plainOptions} value={['Semi D2C']} />
    <br />
    <br />
    <CheckboxGroup aria-label="带 extra 示例" {onChange} options={optionsWithExtra} value={[]} />
    <br />
    <br />
    <CheckboxGroup aria-label="Checkbox 示例" disabled {onChange} options={optionsWithDisabled} value={['Photography']} />
</div>

水平排列

通过设置 direction 为 horizontal 或者 vertical 可以调整 CheckboxGroup 内的布局

抖音
今日头条
代码
<script lang="ts">
    import { CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const options = [
        { label: '抖音', value: 'abc' },
        { label: '今日头条', value: 'toutiao' },
    ];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" direction="horizontal" {options} />

受控

联动 checkbox。

Checked Enabled

代码
<script lang="ts">
    import { Button, Checkbox, type CheckboxEvent } from '@fibrae/semi-ui-svelte';

    let checked = $state(true);
    let disabled = $state(false);
    const label = $derived(`${checked ? 'Checked' : 'Unchecked'} ${disabled ? 'Disabled' : 'Enabled'}`);

    const onChange = (e: CheckboxEvent) => console.log('checked = ', e.target.checked);
</script>

<div>
    <div style="margin-bottom: 20px">
        <Checkbox aria-label="Checkbox 示例" bind:checked {disabled} {onChange}>
            {label}
        </Checkbox>
    </div>
    <p>
        <Button size="small" type="primary" onclick={() => (checked = !checked)}>{!checked ? 'Check' : 'Uncheck'}</Button>
        <Button size="small" style="margin-left: 10px" type="primary" onclick={() => (disabled = !disabled)}>
            {!disabled ? 'Disable' : 'Enable'}
        </Button>
    </p>
</div>

全选

在实现全选效果时,你可能会用到 indeterminate 属性。

Check all
Photography
Movies
Running
代码
<script lang="ts">
    import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrae/semi-ui-svelte';

    const plainOptions = ['Photography', 'Movies', 'Running'];
    let checkedList = $state<CheckboxValue[]>(['Photography', 'Running']);
    const checkAll = $derived(checkedList.length === plainOptions.length);
    const indeterminate = $derived(checkedList.length > 0 && !checkAll);

    const onCheckAllChange = (e: CheckboxEvent) => {
        console.log(e);
        checkedList = e.target.checked ? plainOptions : [];
    };
</script>

<div>
    <div style="padding-bottom: 8px; border-bottom: 1px solid var(--semi-color-border)">
        <Checkbox aria-label="Checkbox 示例" checked={checkAll} {indeterminate} onChange={onCheckAllChange}>Check all</Checkbox>
    </div>
    <CheckboxGroup aria-label="CheckboxGroup 示例" bind:value={checkedList} options={plainOptions} style="margin-top: 6px" />
</div>

卡片样式

可以给 CheckboxGroup 设置 type='card',实现带有背景的卡片样式。

单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
代码
<script lang="ts">
    import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
    const items = [
        { value: '1', disabled: true },
        { value: '2', disabled: true },
        { value: '3', disabled: false },
        { value: '4', disabled: false },
    ];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" direction="vertical" type="card" value={['1', '3']}>
    {#each items as item (item.value)}
        <Checkbox disabled={item.disabled} style="width: 280px" value={item.value}>
            单选框标题
            {#snippet extra()}{extraText}{/snippet}
        </Checkbox>
    {/each}
</CheckboxGroup>

无 checkbox 的纯卡片样式

可以给 CheckboxGroup 设置 type='pureCard',实现带有背景且无 checkbox 的纯卡片样式。

单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
单选框标题
Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统
代码
<script lang="ts">
    import { Checkbox, CheckboxGroup } from '@fibrae/semi-ui-svelte';

    const extraText = 'Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统';
    const items = [
        { value: '1', disabled: true },
        { value: '2', disabled: true },
        { value: '3', disabled: false },
        { value: '4', disabled: false },
    ];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" direction="vertical" type="pureCard" value={['1', '3']}>
    {#each items as item (item.value)}
        <Checkbox disabled={item.disabled} style="width: 280px" value={item.value}>
            单选框标题
            {#snippet extra()}{extraText}{/snippet}
        </Checkbox>
    {/each}
</CheckboxGroup>

配合grid布局

CheckboxGroup 内嵌 Checkbox 并与 Grid 组件一起使用,可以实现灵活的布局。

A
B
C
D
E
代码
<script lang="ts">
    import { Checkbox, CheckboxGroup, Col, Row } from '@fibrae/semi-ui-svelte';

    const values = ['A', 'B', 'C', 'D', 'E'];
</script>

<CheckboxGroup aria-label="CheckboxGroup 示例" style="width: 100%">
    <Row>
        {#each values as value (value)}
            <Col span={8}>
                <Checkbox {value}>{value}</Checkbox>
            </Col>
        {/each}
    </Row>
</CheckboxGroup>

API参考

Checkbox

Props

属性说明类型默认值
addonIdaddon 节点的 id,aria-labelledby 指向这个 id;未设置时随机生成。string-
checked是否选中,可用 bind:checked 双向绑定;在 CheckboxGroup 中使用时无效。bind:checked={get, set} 时完全受控;只传 checked 时作为初值,点击在组件内覆盖,父级再传新值时以父级为准。boolean-
childrenCheckbox 的文本内容 snippet,同时是原生 input 的可访问名称;写在标签内的其余内容就是它。Snippet-
disabled是否禁用。booleanfalse
extra辅助文本的 snippet,aria-describedby 指向它。Snippet-
extraIdextra 节点的 id,aria-describedby 指向这个 id;未设置时随机生成。string-
indeterminate半选状态,只影响外观与原生 input 的 indeterminate,不改变选中值。booleanfalse
name原生 input 的 name;在 CheckboxGroup 中以组的 name 为准。string | null-
onChange选中状态变化时的回调,参数的 target 为 { checked, value, name, disabled }。Type(event: CheckboxEvent) => void-
onclick点击根元素时的回调,在切换之前调用。TypeMouseEventHandler<T> | null-
prefixClsCSS 类名前缀。string-
preventScroll聚焦时是否阻止浏览器滚动到该元素,作用于 focus 方法。boolean-
type样式类型,可选 default、card、pureCard;在 CheckboxGroup 中以组的 type 为准。CheckboxType"default"
value该 Checkbox 在 CheckboxGroup 中代表的值;不设置时它不属于任何分组。CheckboxValue-

Methods

方法说明类型
blur使原生 input 失去焦点。Type() => void
focus使原生 input 获得焦点。Type() => void

class、style(字符串)落在根元素 <span> 上。id、name、tabindex、autofocus、aria-* 与 onfocus、onblur 落在内部的原生 input 上,其余原生属性与事件(如 onmouseenter)落在根元素上;onclick 在切换之前调用。name 在 CheckboxGroup 中以组的 name 为准。

Checkbox Group

Props

属性说明类型默认值
children组内的 Checkbox;设置 options 时忽略。Snippet-
direction组内布局方向,可选 horizontal 或 vertical。CheckboxDirection"vertical"
disabled是否禁用整组。booleanfalse
extra自定义 options 中每一项辅助文本的 snippet,参数为 { option, index }。TypeSnippet<[CheckboxGroupOptionSnippetProps]>-
label自定义 options 中每一项文本的 snippet,参数为 { option, index }。TypeSnippet<[CheckboxGroupOptionSnippetProps]>-
name组内所有原生 input 的 name;未设置时每组生成唯一值。string-
onBlur焦点离开整个分组时的回调,在组内 Checkbox 之间移动焦点不触发。Type(event: FocusEvent) => void-
onChange选中的值变化时的回调,参数为新的选中值数组。Type(value: CheckboxValue[]) => void-
onfocusout根元素的 focusout 事件回调,先于 onBlur 调用。TypeFocusEventHandler<T> | null-
options以配置形式声明选项,元素为字符串或 { label, value, disabled, extra, class, style },其中 style 为字符串。TypeArray<string | CheckboxOptionItem>-
prefixClsCSS 类名前缀。string-
type组内所有 Checkbox 的样式类型,可选 default、card、pureCard。CheckboxType"default"
value选中的值,可用 bind:value 双向绑定,与 Checkbox 的 value 匹配。bind:value={get, set} 时完全受控;只传 value 时作为初值。CheckboxValue[]-

options 项的字段为 label、value、disabled、extra(string | number)、class、style(字符串),没有 onChange;需要自定义内容时使用 label、extra snippet,参数为 { option, index }。class、style(字符串)与原生属性和事件落在根元素 <div> 上;onBlur 在焦点离开整个分组时触发,在组内 Checkbox 之间移动焦点不触发。aria-invalid、aria-errormessage 传给组内每个 Checkbox 的原生 input,aria-required、tabindex 以及 Tooltip 注入的 aria-expanded、aria-haspopup、aria-controls 不输出。

方法

Checkbox

通过 bind:this 取得 Checkbox 实例后调用,说明见上方 Methods。

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卡片类型复选框的副标题的文字行高