组件
    输入类

    开关

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

    代码演示

    如何引入

    <script setup lang="ts">
    import { Switch } from '@fibrous/semi-ui-vue';
</script>

    基本

    你可以通过 @change 监听状态变化，通过 defaultChecked 或 modelValue（v-model）指定选中状态。
    通过 aria-label 描述该 Switch 开关的具体作用


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

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

<template>
    <div>
        <Switch aria-label="a switch for demo" @change="log" />
        <br />
        <Switch aria-label="a switch for semi demo" defaultChecked @change="log" />
    </div>
</template>

    尺寸

    你可以通过 size 指定尺寸

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

<template>
    <div>
        <Space :style="{ marginBottom: '10px', display: 'block' }">
            <Switch aria-label="a switch for demo" size="small" />
            <Switch aria-label="a switch for demo" defaultChecked size="small" />
            <Switch aria-label="a switch for demo" loading size="small" />
            <Switch aria-label="a switch for demo" defaultChecked loading size="small" />
        </Space>
        <Space :style="{ marginBottom: '10px', display: 'block' }">
            <Switch aria-label="a switch for demo" />
            <Switch aria-label="a switch for demo" defaultChecked />
            <Switch aria-label="a switch for demo" loading />
            <Switch aria-label="a switch for demo" defaultChecked loading />
        </Space>
        <Space>
            <Switch aria-label="a switch for demo" size="large" />
            <Switch aria-label="a switch for demo" defaultChecked size="large" />
            <Switch aria-label="a switch for demo" loading size="large" />
            <Switch aria-label="a switch for demo" defaultChecked loading size="large" />
        </Space>
    </div>
</template>

    不可用


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

<template>
    <div>
        <Switch aria-label="a switch for demo" disabled />
        <br />
        <Switch aria-label="a switch for demo" disabled modelValue />
    </div>
</template>

    带文本

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

    关
    〇


    开
    ｜


    关
    〇


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

<template>
    <div>
        <Switch aria-label="带开关文字的开关">
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="带符号文字的开关" :style="{ marginLeft: '5px' }">
            <template #checkedText>｜</template>
            <template #uncheckedText>〇</template>
        </Switch>
        <br />
        <br />
        <Switch aria-label="带开关文字的开关，已开启" defaultChecked>
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="带符号文字的开关，已开启" defaultChecked :style="{ marginLeft: '5px' }">
            <template #checkedText>｜</template>
            <template #uncheckedText>〇</template>
        </Switch>
        <br />
        <br />
        <Switch aria-label="大号带开关文字的开关" size="large">
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="大号带符号文字的开关" size="large" :style="{ marginLeft: '5px' }">
            <template #checkedText>｜</template>
            <template #uncheckedText>〇</template>
        </Switch>
        <br />
        <br />
        <Switch aria-label="大号带开关文字的开关，已开启" defaultChecked size="large">
            <template #checkedText>开</template>
            <template #uncheckedText>关</template>
        </Switch>
        <Switch aria-label="大号带符号文字的开关，已开启" defaultChecked size="large" :style="{ marginLeft: '5px' }">
            <template #checkedText>｜</template>
            <template #uncheckedText>〇</template>
        </Switch>
    </div>
</template>

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

    已关闭
    代码
    <script setup lang="ts">
    import { ref } from 'vue';
    import { Switch, Typography } from '@fibrous/semi-ui-vue';

    const { Title } = Typography;
    const open = ref<boolean>();
</script>

<template>
    <div :style="{ display: 'flex', alignItems: 'center' }">
        <Title :heading="6" :style="{ margin: '8px' }">{{ open ? '已开启' : '已关闭' }}</Title>
        <Switch v-model="open" aria-label="a switch for demo" />
    </div>
</template>

    受控组件

    组件是否选中完全取决于传入的 modelValue，配合 v-model 使用。只传 :modelValue 而不回写时，点击仅触发通知，显示由传入的值决定。

    代码
    <script setup lang="ts">
    import { ref } from 'vue';
    import { Switch } from '@fibrous/semi-ui-vue';

    const checked = ref(true);
</script>

<template>
    <Switch v-model="checked" aria-label="a switch for demo" />
</template>

    加载中

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


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

<template>
    <div>
        <Switch aria-label="Loading switch" loading />
        <br />
        <Switch aria-label="Loading switch, on" defaultChecked loading />
    </div>
</template>

    API 参考

    Props

    属性说明类型默认值
    modelValue是否选中，配合 v-model 使用；传入后由该值决定显示，只传不回写时点击仅触发通知。booleanundefined
    defaultChecked非受控时的初始选中状态。booleansemiGlobalDefault("Switch", "defaultChecked")
    disabled是否禁用。booleansemiDefault("Switch", "disabled", false)
    loading是否处于加载中；加载中 input 仍可聚焦并带 aria-disabled，切换被忽略且不发出事件。booleansemiDefault("Switch", "loading", false)
    size开关尺寸，可选 large、default 或 small。SizesemiDefault("Switch", "size", "default")

    Events

    事件说明回调参数
    update:modelValue用户切换状态时触发，供 v-model 回写。[checked: boolean]
    change用户切换状态时触发，参数为新的选中状态与原生事件。[checked: boolean, event: Event]

    Slots

    插槽说明作用域参数
    checkedText选中时展示的内容，size 为 small 时不显示。any
    uncheckedText未选中时展示的内容，size 为 small 时不显示。any

    Exposes

    名称说明类型
    无

    class、style 落在根元素上。id、name、tabindex、autofocus、aria-* 与 focus、blur 监听经 attrs 落在内部的原生 input 上，其余原生属性与事件监听（如 @mouseenter）落在根元素上。

    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小尺寸开关圆角