定价

Switch 使用手册

v1.2.0 · @snowui-design-system/components

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在开启与关闭之间切换，适合需要即时生效的设置和功能开关。

使用选择

用于立即生效的二态设置。表单多选使用 Checkbox，互斥参数组使用 Radio 或 Segmented。

  • bind:checked 同步开关状态；value 只表示内部输入值，不决定开关状态。

  • 当前 name / form 不转发给内部 input；需要原生表单提交时由表单层显式同步字段。提供可读标签。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Switch } from '@snowui-design-system/components';	let subscribed = $state(false);</script> <Switch bind:checked={subscribed}>Email me product updates</Switch>

API

关键字 类型 默认值 描述
checked boolean false 开关状态，支持 bind:checked。点击标签或聚焦后按 Space 切换；绑定变量、可见轨道与原生输入状态同步。禁用时用户操作不改变状态。
value any — 传给内部原生 checkbox 的值，不决定开关状态，也不建立选择组。当前 name / form 等其余属性传给外层标签，不转发至内部 input，因此仅设置 value 不会产生具名表单提交项。
size ResourceSize | number — 可见轨道高度，数字按根字号为 16px 时的名义 px 解析，外侧留白另计。支持 12 / 16 / 20 / 24 / 28 / 32 / 40 / 48 / 80 及其它有限正数；未传时依次读取父级尺寸 Context 的 iconSize、size，最后回退到 16。非法数字回退到默认尺寸 Token。显式值优先，随根字号缩放。
disabled boolean false 禁用原生输入及用户切换，保留当前开关值和标签，退出 Tab 顺序。外部仍可更新 checked。
singleLine boolean true 默认标签与控件保持单行，附件不压缩；窄宽时原始标签可省略显示并保留完整可访问名称，不复制 children。复杂多行内容可显式设为 false，由该内容拥有布局。需要全文提示时组合 Text lines={1}。
gap number — 继承 Frame 的间距 Token 序号；省略时使用原组件间距，显式值覆盖组件间距。有效间距至少 4 CSS px，包含零值、根字号及 gap-scale 缩放；较大首选值保留。
children Snippet — 无参数标签内容，显示在轨道后；省略时不显示标签。标签文字同时为内部开关提供可访问名称，可通过内容 Snippet 组合文本。
enableResponsive boolean false 传给根 Frame，启用其容器内容适配监听；不改变 Switch 的标准尺寸值域。通用行为见 Frame 能力开关。
enableContext boolean false 传给根 Frame，控制向子组件提供状态、加载与动效等 Context；不控制 Switch 读取父级尺寸 Context。通用行为见 Frame 能力开关。

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

布局模型

主布局模型：内联外壳布局。定义见 ../../../specs/maintainers/LayoutProtocol.md §12.4（源码参考：specs/maintainers/LayoutProtocol.md）。

Switch 属于“控件视觉体 + label”的内联外壳子类：

  • 根节点保持 inline-flex，内容整体 Hug。

  • .snowui-switch-track 是固定 Hug 的控件视觉体。

  • .snowui-switch-label 是可选标签，空间充足时 Hug，受限时允许收缩并单行省略；原始内容及完整原生名称保留。

  • track 与 label 的距离由 --snowui-switch-gap 管理，可通过 gap 或 --snowui-switch-gap-override 设置首选值；有效间距至少 4 CSS px。

  • size 表示可见轨道高度；四边透明留白各为 size / 14，控件占位高为 size × 8 / 7、宽为 size × (1.8 + 1 / 7)。例如 size={28} 轨道为 50.4×28px，四边各留 2px，占位为 54.4×32px。

  • 留白与 track / thumb 随 size、根字号和尺寸 Token 等比缩放，留白仍可点击；label 位于留白壳外。

使用示例

<script>  import { Switch } from '@snowui-design-system/components';  let checked = $state(false);</script>  <Switch bind:checked>开关</Switch>  <Switch bind:checked size={20}>大号开关</Switch>  <Switch checked disabled>禁用开关</Switch>

状态

  • unchecked: 未选中状态，灰色轨道

  • checked: 选中状态，主题色轨道

  • disabled: 禁用状态，降低透明度

无障碍性

  • 使用原生 <input type="checkbox"> 确保键盘导航

  • 支持 Tab 键聚焦

  • 支持 Space 键切换

  • 禁用状态下 tabindex=-1

Switch 样式覆盖

先阅读 完整 LICENSE；同任务、同版本、同范围去重。

优先用组件公开 Props 匹配合适样式，尽可能保留原有视觉。确需改写时按 样式选择与改写顺序 使用自己的 class（含项目已有 Tailwind）或实例 style。以下名称来自源码实际消费的公开 override；先核对目标作用域，不修改私有 DOM。采用 SnowUI Token 时选择正确类别，外部应用不被要求安装一方 utilities。

变量 用途与默认参考
--snowui-switch-color-override color（默认值见组件源码）
--snowui-switch-gap-override gap（默认 var(--gap-1) = 4px）
--snowui-switch-height-override 高度（默认值见组件源码）
--snowui-switch-label-font-size-override label font-size（默认值见组件源码）
--snowui-switch-label-line-height-override label line-height（默认值见组件源码）
--snowui-switch-motion-duration-override 动效时长（默认值见组件源码）
--snowui-switch-motion-easing-override 动效曲线（默认值见组件源码）
--snowui-switch-overlay-color-override 覆盖层颜色（默认值见组件源码）
--snowui-switch-overlay-opacity-override 覆盖层不透明度（默认值见组件源码）
--snowui-switch-primary-override 主色（默认值见组件源码）
--snowui-switch-radius-override border-radius（默认值见组件源码）
--snowui-switch-size-override 整体尺寸（尺寸 px，默认值见组件源码）
--snowui-switch-thumb-gap-override thumb 间距（默认值见组件源码）
--snowui-switch-thumb-size-override thumb 尺寸（尺寸 px，默认值见组件源码）
--snowui-switch-width-override 宽度（默认值见组件源码）

设计指南 · Token · 组合边界

Switch 类型与状态

必填属性：无具名必填属性。

可双向绑定：bind:checked。

继承声明：Omit<FrameProps, "size">。继承能力以基类公开文档为准；Omit 中的字段已排除，不能按基类原样使用。

共享 Frame API · 返回 API

以下为公开属性实际引用的类型声明，来自源码；Svelte Snippet 表示内容片段，ComponentProps 表示对应组件的 Props。

ResourceSize

来源：components/src/context.ts

export type ResourceSize = 12 | 16 | 20 | 24 | 28 | 32 | 40 | 48 | 80;