Switch 开关
role="switch" 的开关按钮。
基础用法
基础用法
禁用与加载
disabled / loading
loading 显示加载动画并阻止切换，用于异步提交场景。
标签
label 属性在开关旁渲染文本标签，点击标签即可切换（原生 label 关联），同时为 role="switch" 提供可访问名称；label-position="start" 把标签放到开关左侧，默认 end（右侧）。也可以用默认插槽放入自定义内容（优先于 label 属性文本）。
标签
热区说明：开关宿主宽度收缩为控件实际宽度（width: fit-content），默认形态下视觉宽度与点击热区一致；当宿主被显式拉宽（竖向 oas-space 的 align-stretch、宿主 width: 100%）时，整行空白区点击同样切换——对齐 iOS 设置项的整行点击语义（内部按钮与 label 标签区域仍走各自通道，不会重复触发）。需要旁侧文本热区时用 label 提供可点标签。无 label 时宿主也可自设 aria-label（自动镜像到内部按钮作可访问名称）。
块级拉伸整行可点
disabled / loading 状态下整行热区同样拦截，行为与拨杆一致。
开关文案
checked-text / unchecked-text 在开关上显示对应文案：medium/large/xl 尺寸显示在轨道内滑块对侧，size="xs" / size="small" 时文案放到开关外侧。
开关文案
尺寸
size 支持 xs / small / medium（默认）/ large / xl 五档；非法值回落 medium 并提示告警。
五种尺寸
自定义颜色
color 覆盖开启态主色（默认走 --oas-color-primary）。
自定义颜色
滑块图标
checked-icon / unchecked-icon 在滑块上渲染图标（oas-icons 图标名），开启/关闭切换图标随之切换，适合星标收藏、昼夜模式等场景：
滑块图标
值映射
true-value / false-value 自定义开关的取值（字符串），oas-change 的 detail.value 返回当前映射值（未设置时为布尔 true / false）；读 el.value 也可直接获得当前映射值，适合表单提交 'YES' / 'NO' 这类场景。
true-value / false-value
切换前拦截
el.beforeChange = (next) => boolean | Promise<boolean>（JS property 通道，attribute 传不了函数）：返回 false 或 Promise reject 则不切换；异步确认（如关闭两步验证前请求后端）在途期间组件进入加载态（spinner + 禁点），防止重复触发。
before-change 异步确认
校验态
status="success" | "warning" | "error" 校验态着色（error 自动联动 aria-invalid，宿主自设 aria-invalid 等效 error 视觉）：
status 校验态
描述（description）
description 在标签下方渲染一行弱化副文本，说明开关的业务含义（与 oas-checkbox / oas-radio 的 description 契约一致）；slot[name="description"] 富内容优先于属性文本：
描述副文本
卡片形态（variant=card）
variant="card" 把开关升级为选择卡：描边容器包住拨杆 + 标签 + 描述，整卡可点（点击卡片任意位置切换）、选中时描边着主色并带浅色底（与 oas-checkbox / oas-radio 的选择卡同视觉语言）；disabled / status 校验态同样作用于卡片描边。适合设置页的逐项开关列表：
卡片形态
宽度自定义
--oas-switch-width / --oas-switch-height / --oas-switch-thumb-size CSS 变量覆盖尺寸档的轨道宽 / 高 / 滑块大小（跨尺寸档生效）：
CSS 变量尺寸
事件
oas-change（detail: { checked, value }）、oas-focus / oas-blur（焦点进入 / 离开组件）。
切换事件
受控用法：宿主持有状态时绑定 checked 属性并在 oas-change 里回写（Vue 下 :checked="x" + @oas-change="x = $event.detail.checked" 一行完成双向）。
required 必填
required 必填（原生校验链）
required 驱动原生校验链（form-associated）：未填时 checkValidity() 为 false（valueMissing），原生表单提交被阻止；填写后自动恢复 :valid。
API
oas-switch
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
aria-label | 可访问名（宿主覆盖通道，显式设置优先于 label 推导） | — | — |
checked | 是否开启 | boolean | — |
checked-icon | 选中态滑块图标（oas-icon 图标名） | string | — |
checked-text | 开启时显示的文案；medium/large/xl 在轨道内，xs/small 在轨道外侧 | — | — |
color | 开启态自定义主色，覆盖 --oas-color-primary（CSS 颜色值） | — | — |
description | 描述副文本（label 下方的次级说明；slot[name=description] 富内容优先于属性文本），与 checkbox/radio 的 description 契约一致 | string | — |
disabled | 禁用 | boolean | — |
false-value | 未选中时的映射值 | string | — |
label | 标签文本（label 通道，点击标签切换；slot 同名插槽可传富内容） | string | — |
label-position | 标签位置：end（默认，右侧）/ start（左侧） | string | — |
loading | 加载态，阻止切换 | boolean | — |
required | 必填标记（驱动原生校验链 valueMissing：关 = 未填） | boolean | — |
size | 尺寸：xs / small / medium（默认）/ large / xl；非法值回落 medium 并告警 | string | medium |
status | 校验态：error / warning / success；error 联动 aria-invalid | string | — |
true-value | 选中时的映射值（读 value getter 取映射值） | string | — |
unchecked-icon | 未选中态滑块图标 | string | — |
unchecked-text | 关闭时显示的文案；medium/large/xl 在轨道内，xs/small 在轨道外侧 | — | — |
variant | 形态：default（默认拨杆）/ card（卡片：描边容器包住拨杆 + 标签 + 描述，整卡可点、选中描边着色，对齐 checkbox/radio 选择卡）；非法值静默回落 default | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-blur | 失焦时派发 |
oas-change | 切换，detail: { checked, value }（value 为映射值） |
oas-focus | 聚焦时派发 |
插槽
| 名称 | 说明 |
|---|---|
| 默认 | 开关内容（文案 / 富内容） |
description | 描述副文本富内容（优先于 description 属性文本） |
CSS 变量
| CSS 变量 | 说明 | 默认值 |
|---|---|---|
--oas-glass-refraction | 液态玻璃边缘折射滤镜（data-glass 生效，默认 none）；局部停用覆盖为空值（--oas-glass-refraction: ;）——不得用 none（与 button 态的 brightness() 混排会使整条 filter 声明非法） | none |
--oas-switch-height | — | 22px |
--oas-switch-on-color | 开启态轨道内文字色（color 自定义轨道底色时组件按底色亮度注入深/浅文字；缺省回落 var(--oas-color-bg)） | var(--oas-color-bg) |
--oas-switch-thumb-size | — | 18px |
--oas-switch-width | — | 40px |