组件
    切换框架
    ReactVueSolidSvelte
    切换语言
    简体中文English
    GitHub
    输入类

    开关

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

    代码演示

    如何引入

    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';
</script>

    基本

    你可以通过 onChange 监听状态变化。只传 checked 时作为初始选中状态，之后由用户点击切换；需要读写选中状态时用 bind:checked，见「受控组件」。
    通过 aria-label 描述该 Switch 开关的具体作用


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

    const log = (checked: boolean) => console.log(checked);
</script>

<div>
    <Switch aria-label="示例开关" onChange={log} />
    <br />
    <Switch aria-label="示例开关，初始开启" checked onChange={log} />
</div>

    尺寸

    你可以通过 size 指定尺寸

    代码
    <script lang="ts">
    import { Space, Switch } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Space style="display: block; margin-bottom: 10px">
        <Switch aria-label="小号开关" size="small" />
        <Switch aria-label="小号开关，已开启" checked size="small" />
        <Switch aria-label="小号开关，加载中" loading size="small" />
        <Switch aria-label="小号开关，已开启且加载中" checked loading size="small" />
    </Space>
    <Space style="display: block; margin-bottom: 10px">
        <Switch aria-label="默认开关" />
        <Switch aria-label="默认开关，已开启" checked />
        <Switch aria-label="默认开关，加载中" loading />
        <Switch aria-label="默认开关，已开启且加载中" checked loading />
    </Space>
    <Space>
        <Switch aria-label="大号开关" size="large" />
        <Switch aria-label="大号开关，已开启" checked size="large" />
        <Switch aria-label="大号开关，加载中" loading size="large" />
        <Switch aria-label="大号开关，已开启且加载中" checked loading size="large" />
    </Space>
</div>

    不可用


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

<div>
    <Switch aria-label="不可用的开关" disabled />
    <br />
    <Switch aria-label="不可用的开关，已开启" checked disabled />
</div>

    带文本

    checkedText 与 uncheckedText 接受 snippet：用 {#snippet} 定义后作为属性传入，或直接写在 Switch 标签内作为同名 snippet。
    注意：此项功能在最小的开关(即 size='small'时)无效

    关
    〇


    开
    ｜


    关
    〇


    开
    ｜
    代码
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';
</script>

{#snippet on()}开{/snippet}
{#snippet off()}关{/snippet}
{#snippet bar()}｜{/snippet}
{#snippet ring()}〇{/snippet}

<div>
    <Switch aria-label="带开关文字的开关" checkedText={on} uncheckedText={off} />
    <Switch aria-label="带符号文字的开关" checkedText={bar} style="margin-left: 5px" uncheckedText={ring} />
    <br />
    <br />
    <Switch aria-label="带开关文字的开关，已开启" checked checkedText={on} uncheckedText={off} />
    <Switch aria-label="带符号文字的开关，已开启" checked checkedText={bar} style="margin-left: 5px" uncheckedText={ring} />
    <br />
    <br />
    <Switch aria-label="大号带开关文字的开关" checkedText={on} size="large" uncheckedText={off} />
    <Switch aria-label="大号带符号文字的开关" checkedText={bar} size="large" style="margin-left: 5px" uncheckedText={ring} />
    <br />
    <br />
    <Switch aria-label="大号带开关文字的开关，已开启" checked checkedText={on} size="large" uncheckedText={off} />
    <Switch aria-label="大号带符号文字的开关，已开启" checked checkedText={bar} size="large" style="margin-left: 5px" uncheckedText={ring} />
</div>

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

    已关闭
    代码
    <script lang="ts">
    import { Switch } from '@fibrae/semi-ui-svelte';

    let open = $state<boolean>();
</script>

<div style="display: flex; align-items: center">
    <span style="margin: 8px; font-weight: 600">{open ? '已开启' : '已关闭'}</span>
    <Switch aria-label="示例开关" bind:checked={open} />
</div>

    受控组件

    用 bind:checked 把选中状态与 $state 变量双向同步。需要拒绝或改写用户的切换时用函数绑定 bind:checked={() => value, (next) => { ... }}，组件显示 getter 返回的值。只传 checked 不绑定时，它只作初值：点击在组件内切换，父级再传新值时以父级为准。

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

    let checked = $state(true);
</script>

<Switch aria-label="受控开关" bind:checked />

    加载中

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


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

<div>
    <Switch aria-label="加载中的开关" loading />
    <br />
    <Switch aria-label="加载中的开关，已开启" checked loading />
</div>

    API 参考

    Props

    属性说明类型默认值
    checked选中状态，可用 bind:checked 双向绑定。bind:checked={get, set} 时完全受控；只传 checked 时作为初值，点击在组件内覆盖，父级再传新值时以父级为准。boolean-
    checkedText选中时展示内容的 snippet，size 为 small 时不显示。Snippet-
    disabled是否禁用。booleanfalse
    loading是否处于加载中；加载中 input 仍可聚焦并带 aria-disabled，切换被忽略且不触发 onChange。booleanfalse
    onChange切换状态时的回调，参数为新的选中状态与原生 change 事件；加载中不触发。Type(checked: boolean, event: Event) => void-
    size开关尺寸，可选 large、default 或 small。Size"default"
    uncheckedText未选中时展示内容的 snippet，size 为 small 时不显示。Snippet-

    class、style 与其他原生属性和事件（如 onmouseenter）落在根元素上；id、name、tabindex、autofocus、aria-*，以及 onfocus、onblur 落在内部的原生 input 上。

    Accessibility

    ARIA

    • Switch 内部的 input 具有 switch role，开关状态由原生 input 的 checked 表达
    • 作为表单控件应该带有 Label
    • 建议使用 aria-label 描述当前标签作用，或用 aria-labelledby 关联页面上的可见标签

    键盘和焦点

    • 键盘用户可以使用 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小尺寸开关圆角