表单 · 6 / 21
Switch st-switch
开关：轨道、拇指弹性位移与对勾动画共同表达开合。checked / disabled / color 三个语义属性，适合设置项与即时生效的偏好开关。
基础状态
无属性为关闭，checked 为开启；disabled 阻断交互并降低透明度。它与 checkbox 的区别是语义：开关表示立即生效的设置，不需要再点保存。
LIVE
st-switch示例代码
<st-switch>关闭</st-switch>
<st-switch checked>开启</st-switch>
<st-switch disabled checked>禁用开启</st-switch>color 语义色
color 只改变开启态的轨道色，拇指自动使用对应的 on-角色色以保证对比度。未选中态始终是 outline / surface 系，不随 color 变化。
LIVE
color示例代码
<st-switch color="primary" checked>primary</st-switch>
<st-switch color="error" checked>error</st-switch>
<st-switch color="success" checked>success</st-switch>受控绑定与 change 回显
用 attr:checked 把 data 接到开关，点击后组件先同步属性再派发 change；在回调里读 hasAttribute("checked") 就能写回准确状态，不需要自己取反。
LIVE
attr:checked / on:change示例代码
<st-switch attr:checked="autoSync" on:change="onAuto">自动同步</st-switch>
<script>
export default async () => ({
data: { autoSync: false, changeCount: 0 },
proto: {
onAuto(e) {
this.autoSync = e.target.hasAttribute("checked");
this.changeCount += 1;
},
},
});
</script>设置列表中的用法
设置面板里通常把标题与说明放在左侧，开关放右侧，并且开关本身不写标签。每一项独立绑定 data，点击后立即生效；行与行之间用描边分隔，不需要 card 嵌套。
LIVE
设置项列表
Wi-Fi
连接办公网络
蓝牙
连接附近的键盘与耳机
自动更新
仅在 Wi-Fi 下下载
省电模式
降低后台活动频率
示例代码（设置项）
<div style="display: flex; align-items: center; justify-content: space-between;">
<div>
<div>Wi-Fi</div>
<div>连接办公网络</div>
</div>
<st-switch attr:checked="wifi" on:change="wifi = !wifi"></st-switch>
</div>文字、图标与尺寸
默认插槽放在轨道右侧，可以放纯文字或 emoji 图标；没有内容时标签区自动隐藏。尺寸全部用 em，改宿主 font-size 会同时缩放轨道、拇指、间距和圆角。
LIVE
slot / font-size
12px + 图标
14px（默认）
20px + 图标
✈️ 飞行模式
无标签
示例代码
<st-switch style="font-size: 12px;" checked><iconify-icon icon="mdi:bell-outline"></iconify-icon> 提醒</st-switch>
<st-switch style="font-size: 20px;" checked>✈️ 飞行模式</st-switch>
<st-switch checked></st-switch>属性
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
checked | boolean | 无 | 开启态；点击自动同步 |
disabled | boolean | 无 | 0.38 透明度，阻断交互 |
color | M3 角色名 / 自定义变量名 | 无 | 开启态轨道色，拇指自动用 on-角色色 |
插槽 / 事件 / 注意
- 插槽：默认插槽是标签文字或 emoji；为空时文字区自动隐藏。
- 事件：
change（bubbles + composed），触发时 checked 属性已同步。 - 布尔属性用
attr:checked="expr"；不要用:checked。 color只影响开启态，未选中态恒为 outline / surface。- 不要用外部 CSS 强改拇指尺寸或边框宽度：实心底靠 border-width 扩展实现。