使用场景
- 勾选框可以让用户在两种相反的状态、行为或取值之间选择;
- 适用于在列表中选择单个或多个选项,开启或关闭某个选项
代码演示
如何引入
<script lang="ts">
import { Checkbox, CheckboxGroup, Col, Row } from '@fibrae/semi-ui-svelte';
</script>
基本用法
Checkbox单个使用,只传 checked 时作为初始选中状态,之后由用户点击切换;需要读写选中状态时用 bind:checked,见「受控」。
代码
<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>代码
<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} 定义,其余内容是文本内容。辅助文本会更长一些,甚至还可能换行。
代码
<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
代码
<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
代码
<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 组
代码
<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。
代码
<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 属性。
代码
<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',实现带有背景的卡片样式。
代码
<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 的纯卡片样式。
代码
<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 组件一起使用,可以实现灵活的布局。
代码
<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
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| addonId | addon 节点的 id,aria-labelledby 指向这个 id;未设置时随机生成。 | string | - |
| checked | 是否选中,可用 bind:checked 双向绑定;在 CheckboxGroup 中使用时无效。bind:checked={get, set} 时完全受控;只传 checked 时作为初值,点击在组件内覆盖,父级再传新值时以父级为准。 | boolean | - |
| children | Checkbox 的文本内容 snippet,同时是原生 input 的可访问名称;写在标签内的其余内容就是它。 | Snippet | - |
| disabled | 是否禁用。 | boolean | false |
| extra | 辅助文本的 snippet,aria-describedby 指向它。 | Snippet | - |
| extraId | extra 节点的 id,aria-describedby 指向这个 id;未设置时随机生成。 | string | - |
| indeterminate | 半选状态,只影响外观与原生 input 的 indeterminate,不改变选中值。 | boolean | false |
| name | 原生 input 的 name;在 CheckboxGroup 中以组的 name 为准。 | string | null | - |
| onChange | 选中状态变化时的回调,参数的 target 为 { checked, value, name, disabled }。 | Type(event: CheckboxEvent) => void | - |
| onclick | 点击根元素时的回调,在切换之前调用。 | TypeMouseEventHandler<T> | null | - |
| prefixCls | CSS 类名前缀。 | 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 | 是否禁用整组。 | boolean | false |
| 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> | - |
| prefixCls | CSS 类名前缀。 | 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-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 | 卡片类型复选框的副标题的文字行高 |