组件
    输入类

    开关

    开关是用于切换两种互斥状态的交互形式

    代码演示

    如何引入

    import { Switch } from '@fibrous/semi-ui-react';

    基本

    你可以通过 onChange 监听状态变化，通过 defaultChecked 或受控的 checked 制定选中状态。
    通过 aria-label 描述该 Switch 开关的具体作用


    代码
    import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch onChange={(v) => console.log(v)} aria-label="a switch for demo" />
            <br />
            <Switch defaultChecked onChange={(v) => console.log(v)} aria-label="a switch for semi demo" />
        </div>
    );
}

    尺寸

    你可以通过 size 指定尺寸

    代码
    import { Switch, Space } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Space style={{ marginBottom: 10, display: 'block' }}>
                <Switch size="small" aria-label="a switch for demo" />
                <Switch defaultChecked size="small" aria-label="a switch for demo" />
                <Switch size="small" loading aria-label="a switch for demo" />
                <Switch size="small" loading defaultChecked aria-label="a switch for demo" />
            </Space>
            <Space style={{ marginBottom: 10, display: 'block' }}>
                <Switch aria-label="a switch for demo" />
                <Switch defaultChecked aria-label="a switch for demo" />
                <Switch loading aria-label="a switch for demo" />
                <Switch loading defaultChecked aria-label="a switch for demo" />
            </Space>
            <Space>
                <Switch size="large" aria-label="a switch for demo" />
                <Switch defaultChecked size="large" aria-label="a switch for demo" />
                <Switch size="large" loading aria-label="a switch for demo" />
                <Switch size="large" loading defaultChecked aria-label="a switch for demo" />
            </Space>
        </div>
    );
}

    不可用


    代码
    import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch disabled aria-label="a switch for demo" />
            <br />
            <Switch disabled checked aria-label="a switch for demo" />
        </div>
    );
}

    带文本

    可以通过 checkedText 与 uncheckedText 设置开关时的文本
    注意：此项功能在最小的开关(即 size='small'时)无效

    关
    〇


    开
    ｜


    关
    〇


    开
    ｜
    代码
    import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch aria-label="带开关文字的开关" checkedText="开" uncheckedText="关" />
            <Switch aria-label="带符号文字的开关" checkedText="｜" uncheckedText="〇" style={{ marginLeft: 5 }} />
            <br />
            <br />
            <Switch aria-label="带开关文字的开关，已开启" defaultChecked checkedText="开" uncheckedText="关" />
            <Switch aria-label="带符号文字的开关，已开启" defaultChecked checkedText="｜" uncheckedText="〇" style={{ marginLeft: 5 }} />
            <br />
            <br />
            <Switch aria-label="大号带开关文字的开关" checkedText="开" uncheckedText="关" size="large" />
            <Switch aria-label="大号带符号文字的开关" checkedText="｜" uncheckedText="〇" size="large" style={{ marginLeft: 5 }} />
            <br />
            <br />
            <Switch aria-label="大号带开关文字的开关，已开启" defaultChecked checkedText="开" uncheckedText="关" size="large" />
            <Switch aria-label="大号带符号文字的开关，已开启" defaultChecked checkedText="｜" uncheckedText="〇" size="large" style={{ marginLeft: 5 }} />
        </div>
    );
}

    相比于通过 checkedText 与 uncheckedText 设置内嵌的文本，我们更推荐将文本说明放置在 Switch 外部

    已关闭
    代码
    import { useState } from 'react';
import { Switch, Typography } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    const [open, setOpen] = useState<boolean>();
    const { Title } = Typography;
    return (
        <div style={{ display: 'flex', alignItems: 'center' }}>
            <Title heading={6} style={{ margin: 8 }}>
                {open ? '已开启' : '已关闭'}
            </Title>
            <Switch checked={open} onChange={setOpen} aria-label="a switch for demo" />
        </div>
    );
}

    受控组件

    组件是否选中完全取决于传入的 checked 值，配合 onChange 回调函数使用

    代码
    import { useState } from 'react';
import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    const [checked, setChecked] = useState(true);

    const onChange = (checked: boolean) => {
        setChecked(checked);
    };

    return <Switch checked={checked} aria-label="a switch for demo" onChange={onChange} />;
}

    加载中

    可以通过设置 loading="true" 开启加载中状态。


    代码
    import { Switch } from '@fibrous/semi-ui-react';

export default function SwitchDemo() {
    return (
        <div>
            <Switch loading aria-label="Loading switch" />
            <br />
            <Switch loading defaultChecked aria-label="Loading switch, on" />
        </div>
    );
}

    API 参考

    Props

    属性说明类型默认值
    checked选中状态。不为 undefined 时为受控：显示由该值决定，点击只触发 onChange，需在回调中更新该值。变回 undefined 后取消选中并转为非受控。boolean-
    checkedText选中时展示的内容，size 为 small 时不显示。React.ReactNode-
    className根元素的类名。string""
    defaultChecked非受控时的初始选中状态，只在首次渲染时读取。boolean-
    disabled是否禁用。booleanfalse
    id原生 input 的 id。string-
    loading是否处于加载中；加载中 input 仍可聚焦并带 aria-disabled，切换被忽略且不触发 onChange。booleanfalse
    name原生 input 的 name，用于表单提交。string-
    onChange切换状态时的回调，参数为新的选中状态与原生 change 事件；加载中不触发。Type(checked: boolean, e: React.ChangeEvent<HTMLInputElement>) => void-
    onMouseEnter鼠标移入根元素时的回调。Type(e: React.MouseEvent) => any-
    onMouseLeave鼠标移出根元素时的回调。Type(e: React.MouseEvent) => any-
    ref根元素（div）的引用。TypeReact.Ref<HTMLDivElement>-
    size开关尺寸，可选 large、default 或 small。Size"default"
    style根元素的样式。React.CSSProperties-
    tabIndex原生 input 的 tabIndex。number-
    uncheckedText未选中时展示的内容，size 为 small 时不显示。React.ReactNode-

    className、style、ref、onFocus、onBlur 与其他原生属性（如 data-*）落在根元素上，onFocus、onBlur 接收到的是内部 input 冒泡上来的焦点事件；autoFocus 与 aria-* 落在内部的原生 input 上。

    Accessibility

    ARIA

    • Switch 内部的 input 具有 switch role，开关状态由原生 input 的 checked 表达
    • 作为表单控件应该带有 Label
    • 使用 Form.Switch 时 Label 会自动被带上；如果你单独使用 Switch，建议使用 aria-label 描述当前标签作用

    键盘和焦点

    • 键盘用户可以使用 Tab 及 Shift + Tab 切换焦点
    • 聚焦时可以通过 Space 键切换开启或关闭状态

    文案规范

    • 开关描述
      • 首字母大写，不需要标点符号
      • 间接明了地说明该设置的开启或关闭状态
      • 如果需要，解释给用户开启和关闭状态所代表的情况

    设计变量

    下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。
    Sass 变量值用法
    $transition_duration-switch-bg200ms开关-背景色-动画持续时间
    $transition_function-switch-bgvar(--semi-transition_function-easeIn)开关-背景色-过渡曲线
    $transition_delay-switch-bgvar(--semi-transition_delay-none)开关-背景色-延迟时间
    $spacing-switch_unchecked-translateX2px未选中态开关滑块位移距离
    $spacing-switch_spin_unchecked-translateX2px未选中态加载图标位移距离
    $spacing-switch_checked-translateX18px选中态开关滑块位移距离
    $spacing-switch_spin_checked-translateX16px选中态加载图标位移距离
    $spacing-switch_expand_large-translateX10px
    $spacing-switch_unchecked_large-translateX3px大尺寸未选中态开关滑块位移距离
    $spacing-switch_spin_unchecked_large-translateX2px大尺寸未选中态加载图标位移距离
    $spacing-switch_checked_large-translateX26px大尺寸选中态开关滑块位移距离
    $spacing-switch_spin_checked_large-translateX22px大尺寸选中态加载图标位移距离
    $spacing-switch_expand_small-translateX2px
    $spacing-switch_unchecked_small-translateX1px小尺寸未选中态开关滑块位移距离
    $spacing-switch_spin_unchecked_small-translateX2px小尺寸未选中态加载图标位移距离
    $spacing-switch_checked_small-translateX11px小尺寸选中态开关滑块位移距离
    $spacing-switch_spin_checked_small-translateX10px小尺寸选中态加载图标位移距离
    $motion-switch-transitionDuration200ms开关动画时长
    $color-switch_default-bg-defaultvar(--semi-color-fill-0)关闭态(未选中)开关背景色 - 默认
    $color-switch_default-bg-hovervar(--semi-color-fill-1)关闭态开关背景色 - 悬浮
    $color-switch_default-bg-activevar(--semi-color-fill-2)关闭态开关背景色 - 按下
    $color-switch_default-border-defaulttransparent关闭态开关描边颜色
    $color-switch_checked-bg-defaultvar(--semi-color-success)开启态开关背景色 - 默认
    $color-switch_checked-bg-hovervar(--semi-color-success-hover)开启态开关背景色 - 悬浮
    $color-switch_checked-bg-activevar(--semi-color-success-active)开启态开关背景色 - 按下
    $color-switch_disabled-bg-defaulttransparent禁用态开关背景色
    $color-switch_disabled-bg-hovertransparent禁用态开关背景色 - 悬浮
    $color-switch_disabled-bg-activetransparent禁用态开关背景色 - 按下
    $color-switch_disabled-border-defaultvar(--semi-color-border)禁用态开关描边颜色
    $color-switch_disabled-bg-hovertransparent禁用态开关背景色 - 悬浮
    $color-switch_checked_disabled-bg-defaultvar(--semi-color-success-disabled)禁用开启态开关背景颜色
    $color-switch_checked_disabled-border-defaulttransparent禁用开启态开关描边颜色
    $color-switch_knob-bg-defaultvar(--semi-white)开关滑块背景颜色 - 关闭态
    $color-switch_knob-bg-checkedvar(--semi-white)开关滑块背景颜色 - 开启态
    $color-switch_knob-border-defaultvar(--semi-color-border)开关滑块描边颜色
    $color-switch_checked-text-defaultvar(--semi-color-white)开启态开关文案颜色
    $color-switch_unchecked-text-defaultvar(--semi-color-text-2)关闭态开关文案颜色
    $color-switch_loading_spin-defaultvar(--semi-color-white)加载态开关loading图标颜色
    $color-switch_spin_checked-bg-defaultvar(--semi-color-success-hover)已开启开关加载态loading背景颜色
    $color-switch_spin_unchecked-bg-defaultvar(--semi-color-fill-1)已关闭开关加载态loading背景颜色
    $color-switch_primary-outline-focus$color-focus-ring开关轮廓 - 聚焦
    $width-switch40px开关宽度
    $height-switch24px开关高度
    $width-switch_knob_expand6px开关滑块按压时延展宽度
    $width-switch_knob_default18px开关滑块宽度
    $width-switch_knob_active$width-switch_knob_default + $width-switch_knob_expand开关滑块按下态宽度
    $height-switch_large32px大尺寸开关高度
    $width-switch_large54px大尺寸开关宽度
    $width-switch_knob_large24px大尺寸开关滑块宽度
    $width-switch_knob_large_active$width-switch_knob_large + $spacing-switch_expand_large-translateX大尺寸开关滑块按下态宽度
    $height-switch_small16px小尺寸开关高度
    $width-switch_small26px小尺寸开关宽度
    $width-switch_knob_large_small12px小尺寸开关滑块宽度
    $width-switch_knob_small_active$width-switch_knob_large_small + $spacing-switch_expand_small-translateX小尺寸开关滑块按下态宽度
    $width-switch_knob_disabled-border1px禁用态开关滑块边框宽度
    $width-switch_checked_unchecked_text26px开关文案宽度
    $width-switch_spin-small10px小尺寸开关加载 spin 宽度
    $width-switch_spin-default18px默认尺寸开关加载 spin 宽度
    $width-switch_spin-large28px大尺寸开关加载 spin 宽度
    $width-switch-outline$width-focus-ring开关轮廓宽度
    $spacing-switch_knob-padding2px开关滑块顶部边距
    $spacing-switch_knob_large-padding3px大尺寸开关滑块顶部边距
    $spacing-switch_knob_small-padding1px小尺寸开关滑块顶部边距
    $spacing-switch_knob-left0px开关滑块左侧偏移距离
    $radius-switch$height-switch * 0.5开关圆角
    $radius-switch_large$height-switch_large * 0.5大尺寸开关圆角
    $radius-switch_small$height-switch_small * 0.5小尺寸开关圆角