Switch
即时切换二元状态。中文惯用名：开关。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.switch |
| 名称 | Switch |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 即时切换二元状态 |
| 描述 | 中文惯用名：开关。 |
预览
静态结构：Switch 为 inline-flex 包裹：开关轨道（data-slot="switch" + data-slot="switch-thumb" 滑块，切换时滑块平移）+ 旁侧 label 文本，label 经 htmlFor 关联控件 useId，点击文字即切换。Form 内声明非空 name 时外层为 data-slot="form-item" 容器（mb-4），label 与开关同行、不另起表单标签行，校验错误以 data-slot="form-error" 追加在下方。
DSL 结构
{
"type": "Switch",
"props": {
"name": "autoSave",
"label": "开启自动保存",
"value": true
}
}何时用
何时使用
- 即时启停某项能力或状态：自动保存、消息推送、灰度开关。
- 切换后立即生效、无需二次确认、不需提交按钮的布尔设置。
- 表单内的 boolean 字段：声明 name 即自动注册，值为 true / false。
何时不用
- 需要用户填写完表单再一起提交的布尔项（如「同意条款」）：使用 Checkbox——多选 Checkbox、单选 RadioGroup、即时启停 Switch。
- 互斥的多个选项中选一个：使用 RadioGroup。
- 破坏性或高影响操作的确认（删除、下线）：使用 Dialog / Popconfirm，不要用 Switch 一键切换。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（开 / 关） | 轨道 + 滑块，开启态滑块移至右侧并高亮 | 即时启停的设置项 |
| 无 label 纯开关 | 仅开关本体（label 缺省不渲染） | 与外部说明文案配合的紧凑场景 |
| Form 表单项 | form-item 容器：开关 + 标签同行，错误行在下方 | 表单内 boolean 字段（声明 name 自动注册） |
| disabled 禁用 | 半透明不可切换 | 权限不足或依赖项未就绪 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项（值为 boolean） |
label | string | — | 开关旁的标签文本（Form 内仍与开关同行，不另起表单标签行） |
rules | FieldRule[] | — | 校验规则 |
value | boolean | — | 受控值（独立渲染时生效，仅 true 视为开启）；Form 内作为字段初始值（优先于 Form initialValues） |
disabled | boolean | false | 禁用切换 |
onChange | (checked: boolean) => void | — | 开关变化事件，传出 boolean（Renderer 绑定 events.onChange；DSL 语义值） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为控件包裹） |
使用规范
- 只用 true / false 两态，且切换立即生效：Three-state（未设置）场景请用 RadioGroup 或 Select 显式表达。
- 高影响开关需给出后果说明与撤销路径（如「开启后所有成员可见」），必要时先经 Dialog 确认。
- 依赖未就绪时用 disabled 而非隐藏，并说明原因，避免用户反复寻找入口。
- 标签文案用肯定句式并描述开启后的状态（「开启自动保存」），不要用含义模糊的「模式」。
- Form 内声明非空 name 才注册字段；未声明 name 时为独立受控控件，值不进表单 values。
正例
- ✓ 设置页「自动保存」：onChange 立即写回接口，切换即生效，无需保存按钮。
- ✓ Form 内布尔项：name + value 初始值，提交时随表单 values 一并带出。
- ✓ 依赖未就绪：disabled + 旁注「需先选择数据源」，用户理解为何点不动。
反例
- ✕ 用 Switch 承载「同意用户协议」这类需随表单提交的布尔项（应使用 Checkbox）。
- ✕ 用 Switch 一键删除 / 下线资源，无确认也无撤销路径。
- ✕ 依赖项未就绪时直接隐藏开关，用户以为功能缺失。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。