复选框 - Semi Design Next

使用场景

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

代码演示

如何引入

import { Checkbox, CheckboxGroup, Col, Row } from '@fibrous/semi-ui-solid';

基本用法

Checkbox单个使用，可以通过defaultChecked、checked属性控制是否勾选。
当传入checked时，为受控使用。

Semi Design

代码

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <Checkbox onChange={(e) => console.log(e)} aria-label="Checkbox 示例">
            Semi Design
        </Checkbox>
    );
}

Semi Design

代码

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <Checkbox defaultChecked onChange={(e) => console.log(e)} aria-label="Checkbox 示例">
            Semi Design
        </Checkbox>
    );
}

带辅助文本的checkbox。通过extra传入辅助文本。辅助文本会更长一些，甚至还可能换行。

Semi Design

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

Semi Design

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

代码

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <>
            <Checkbox aria-label="Checkbox 示例" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统">
                Semi Design
            </Checkbox>
            <br />
            <Checkbox style={{ width: '280px' }} aria-label="Checkbox 示例" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统">
                Semi Design
            </Checkbox>
        </>
    );
}

禁用

通过设置 disabled 属性，禁用 Checkbox

Unchecked Disabled

Checked Disabled

代码

import { Checkbox } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <div>
            <Checkbox defaultChecked={false} disabled aria-label="Checkbox 示例">
                Unchecked Disabled
            </Checkbox>
            <br />
            <Checkbox defaultChecked disabled aria-label="Checkbox 示例">
                Checked Disabled
            </Checkbox>
        </div>
    );
}

JSX方式声明Checkbox组

通过在CheckboxGroup内部放置 Checkbox元素，可以声明Checkbox组
使用Checkbox组，你可以更便捷地通过CheckboxGroup的defaultValue、value属性去控制一组Checkbox的选中与否，此时Checkbox不需要再声明defaultChecked、checked属性

代码

import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup style={{ width: '100%' }} defaultValue={['A', 'B']} aria-label="CheckboxGroup 示例">
            <Checkbox value="A">A</Checkbox>
            <Checkbox value="B">B</Checkbox>
            <Checkbox value="C">C</Checkbox>
            <Checkbox value="D">D</Checkbox>
            <Checkbox value="E">E</Checkbox>
        </CheckboxGroup>
    );
}

数组方式声明 Checkbox 组

也可以将数组通过 options 属性直接传入 CheckboxGroup，直接生成 Checkbox 组

代码

import { CheckboxGroup, type CheckboxValue } from '@fibrous/semi-ui-solid';

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 },
];

function onChange(checkedValues: CheckboxValue[]) {
    console.log('checked = ', checkedValues);
}

export default function CheckboxDemo() {
    return (
        <div>
            <CheckboxGroup options={plainOptions} defaultValue={['Semi D2C']} onChange={onChange} aria-label="CheckboxGroup 示例" />
            <br />
            <br />
            <CheckboxGroup options={optionsWithExtra} defaultValue={[]} onChange={onChange} aria-label="带 extra 示例" />
            <br />
            <br />
            <CheckboxGroup options={optionsWithDisabled} disabled defaultValue={['Photography']} onChange={onChange} aria-label="Checkbox 示例" />
        </div>
    );
}

水平排列

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

抖音

今日头条

代码

import { CheckboxGroup } from '@fibrous/semi-ui-solid';

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

export default function CheckboxDemo() {
    return <CheckboxGroup options={options} direction="horizontal" aria-label="CheckboxGroup 示例" />;
}

受控

联动 checkbox。

Checked Enabled

代码

import { createSignal } from 'solid-js';
import { Button, Checkbox, type CheckboxEvent } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    const [checked, setChecked] = createSignal(true);
    const [disabled, setDisabled] = createSignal(false);

    const onChange = (e: CheckboxEvent) => {
        console.log('checked = ', e.target.checked);
        setChecked(e.target.checked);
    };

    const label = () => `${checked() ? 'Checked' : 'Unchecked'} ${disabled() ? 'Disabled' : 'Enabled'}`;
    return (
        <div>
            <div style={{ 'margin-bottom': '20px' }}>
                <Checkbox checked={checked()} disabled={disabled()} onChange={onChange} aria-label="Checkbox 示例">
                    {label()}
                </Checkbox>
            </div>
            <p>
                <Button type="primary" size="small" onClick={() => setChecked(!checked())}>
                    {!checked() ? 'Check' : 'Uncheck'}
                </Button>
                <Button style={{ 'margin-left': '10px' }} type="primary" size="small" onClick={() => setDisabled(!disabled())}>
                    {!disabled() ? 'Disable' : 'Enable'}
                </Button>
            </p>
        </div>
    );
}

全选

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

Check all

Photography

Movies

Running

代码

import { createSignal } from 'solid-js';
import { Checkbox, CheckboxGroup, type CheckboxEvent, type CheckboxValue } from '@fibrous/semi-ui-solid';

const plainOptions = ['Photography', 'Movies', 'Running'];

export default function CheckboxDemo() {
    const [checkedList, setCheckedList] = createSignal<CheckboxValue[]>(['Photography', 'Running']);
    const [indeterminate, setIndeterminate] = createSignal(true);
    const [checkAll, setCheckAll] = createSignal(false);
    const onChange = (list: CheckboxValue[]) => {
        setCheckedList(list);
        setIndeterminate(!!list.length && list.length < plainOptions.length);
        setCheckAll(list.length === plainOptions.length);
    };
    const onCheckAllChange = (e: CheckboxEvent) => {
        console.log(e);
        setCheckedList(e.target.checked ? plainOptions : []);
        setIndeterminate(false);
        setCheckAll(e.target.checked);
    };

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

卡片样式

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

单选框标题

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

单选框标题

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

单选框标题

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

单选框标题

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

代码

import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup type="card" defaultValue={['1', '3']} direction="vertical" aria-label="CheckboxGroup 示例">
            <Checkbox value="1" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="2" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="3" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="4" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
        </CheckboxGroup>
    );
}

无 checkbox 的纯卡片样式

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

单选框标题

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

单选框标题

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

单选框标题

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

单选框标题

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

代码

import { Checkbox, CheckboxGroup } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup type="pureCard" defaultValue={['1', '3']} direction="vertical" aria-label="CheckboxGroup 示例">
            <Checkbox value="1" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="2" disabled extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="3" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
            <Checkbox value="4" extra="Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统" style={{ width: '280px' }}>
                单选框标题
            </Checkbox>
        </CheckboxGroup>
    );
}

配合grid布局

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

代码

import { Checkbox, CheckboxGroup, Col, Row } from '@fibrous/semi-ui-solid';

export default function CheckboxDemo() {
    return (
        <CheckboxGroup style={{ width: '100%' }} aria-label="CheckboxGroup 示例">
            <Row>
                <Col span={8}>
                    <Checkbox value="A">A</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="B">B</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="C">C</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="D">D</Checkbox>
                </Col>
                <Col span={8}>
                    <Checkbox value="E">E</Checkbox>
                </Col>
            </Row>
        </CheckboxGroup>
    );
}

API参考

Checkbox

Props

属性	说明	类型	默认值
addonId	addon 节点的 id，aria-labelledby 指向这个 id；未设置时随机生成。	`string`	-
checked	是否选中，传入时为受控使用；在 CheckboxGroup 中使用时无效。	`boolean`	-
defaultChecked	初始是否选中，非受控使用；在 CheckboxGroup 中使用时无效。	`boolean`	`false`
disabled	是否禁用。	`boolean`	-
extra	辅助文本，可传入任意 JSX，aria-describedby 指向它。	`JSX.Element`	-
extraId	extra 节点的 id，aria-describedby 指向这个 id；未设置时随机生成。	`string`	-
indeterminate	半选状态，只影响外观与原生 input 的 indeterminate，不改变选中值。	`boolean`	`false`
name	原生 input 的 name；在 CheckboxGroup 中以组的 name 为准。	`string`	-
onBlur	原生 input 失去焦点时触发。	`Type`	-
onChange	选中状态变化时触发，参数的 `target` 为 `{ checked, value, name, disabled }`。	`Type`	-
onFocus	原生 input 获得焦点时触发。	`Type`	-
prefixCls	CSS 类名前缀。	`string`	-
preventScroll	聚焦时是否阻止浏览器滚动到该元素，作用于 focus 方法。	`boolean`	-
type	样式类型，可选 default、card、pureCard；在 CheckboxGroup 中以组的 type 为准。	`CheckboxType`	`"default"`
value	该 Checkbox 在 CheckboxGroup 中代表的值；不设置时它不属于任何分组。	`CheckboxValue`	-

class、style、ref 落在根元素 <span> 上。id、name、tabindex、autofocus、aria-* 与 onFocus、onBlur 落在内部的原生 input 上，其余原生属性与事件（如 onMouseEnter、onClick）落在根元素上。name 在 CheckboxGroup 中以组的 name 为准。

Checkbox Group

Props

属性	说明	类型	默认值
defaultValue	非受控时组内默认选中的值，与 Checkbox 的 value 匹配。	`CheckboxValue[]`	`[]`
direction	组内布局方向，可选 horizontal 或 vertical。	`CheckboxDirection`	`"vertical"`
disabled	是否禁用整组。	`boolean`	`false`
name	组内所有原生 input 的 name；未设置时每组生成唯一值。	`string`	-
onChange	选中的值变化时触发，参数为新的选中值数组。	`Type`	-
options	以配置形式声明选项，元素为字符串或 `{ label, value, disabled, extra, class, style, onChange }`；label 与 extra 可传入 JSX。	`Type`	-
prefixCls	CSS 类名前缀。	`string`	-
type	组内所有 Checkbox 的样式类型，可选 default、card、pureCard。	`CheckboxType`	`"default"`
value	选中的值，传入时为受控使用。	`CheckboxValue[]`	-

class、style、ref 与原生属性和事件落在根元素 <div> 上；onBlur 在焦点离开整个分组时触发，在组内 Checkbox 之间移动焦点不触发。aria-invalid、aria-errormessage 传给组内每个 Checkbox 的原生 input，aria-required、tabindex 以及 Tooltip 注入的 aria-expanded、aria-haspopup、aria-controls 不输出。

方法

Checkbox

ref 取得的是根元素 <span>，其上的 focus()、blur() 作用于内部的原生 input。focus() 会带上 preventScroll。

名称	描述
blur()	移除焦点
focus()	获取焦点

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	call
Call	Call;

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

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