n-switch 开关
原生 switch 的主题化替身：轨道 + 圆形钮纯 CSS 自绘，选中色、形状、轨道内文可配，尺寸对齐原生 switch 固定规格（51×31）。完全受控：点击不翻转内部状态，只派发目标值，页面回写 modelValue 驱动视觉——这同时就是"异步确认"模式：开关触发请求时成功再回写、失败不动，不会先斩后奏。
- 受控用法：
:model-value+@change回写（也可使用 v-model）；update:modelValue与change同参同发，手动双向绑定监听其一即可- 与 n-cell 搭配（title +
#value放开关）是设置行的标准用法- 开关即触发请求的场景传
loading：圆钮内转加载圈并拦截点击，等待结果再定终态
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
API
属性
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
|---|---|---|---|---|
| model-value | 选中态（受控） | Boolean | false | - |
| disabled | 禁用：保留配色降透明度并拦截点击 | Boolean | false | - |
| loading | 加载中：圆钮内转加载圈并拦截点击 | Boolean | false | - |
| color | 选中态轨道颜色（实色值），留空取主题品牌色 | String | "" | 与 css 相同 |
| shape | 轨道形状 | String | round | round / square |
| active-text | 选中时轨道内文字（如"开"） | String | "" | - |
| inactive-text | 未选中时轨道内文字（如"关"） | String | "" | - |
| custom-class | 挂到根节点的额外 class（类需定义在组件样式表内） | String | "" | - |
| custom-style | 根节点行内样式，如 "margin-right:12px" | String | "" | 与 css 相同 |
事件
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:modelValue | 切换后的目标选中态；与 change 同参同发，手动双向绑定监听其一 | Boolean |
| change | 切换后的目标选中态；与 update:modelValue 同参同发，受控用法二选一监听回写 | Boolean |
插槽
| 名称 | 说明 | 参数 |
|---|---|---|
| icon | 自定义圆钮内内容（常用于选中 / 未选中切换的图标）；loading 态显示加载圈、插槽暂让 |
轨道内文字走 active-text / inactive-text（样式走令牌）；行文案由 n-cell 等行容器承担。
实现说明（机制对照）
| 能力 | 参考做法 | 本库做法 | 分工理由 |
|---|---|---|---|
| 值通道 | 一参考点击先翻内部副本再发事件（外部不回写时视觉已变）；另一参考需显式开 asyncChange 才把切换权交回外部（不开则"先操作 v-model 并失去控制效果"） | 完全受控：点击只派发目标值（update:modelValue 与 change 同参同发），回写 modelValue 才切换 | 异步确认是默认行为而非 opt-in，不存在"忘了开异步开关先斩后奏"的坑 |
| 未选中轨道色 | 一参考 inactiveColor 属性（恒定色值） | 主题次级表面色令牌（随深浅主题自动切换），不设属性 | 硬编码未选中色无法同时适配深浅两套主题，必有一侧不可读 |
| 选中轨道色 | activeColor / color 属性 | color 属性，留空取主题品牌色 | 一致收录；加载圈与轨道同色 |
| 尺寸 | 三参考分别为任意 px 宽高 / size 参数化 / scale 缩放系数 | 固定 51×31（对齐原生 switch 规格）；等比缩放场景走 customStyle 的 transform:scale | 语义控件规格统一保 40px 触控档；圆钮行程与轨道几何互为约定，任意拆尺寸破坏滑动手感 |
| 轨道形状 | shape round / square | 同左 | 一致收录 |
| 轨道内文 | 一参考 activeText / inactiveText 在开关两侧外挂文字（含文字间距与定宽省略属性） | 文字内嵌轨道，选中态翻转"文 / 钮"次序；字号与间距走令牌 | 内嵌形态更紧凑；两侧外挂文字属页面布局能力，定宽省略随外挂形态一并不收 |
| 圆钮内图标 | 两参考提供圆钮内插槽（随选中态换图标） | #icon 作用域插槽 { checked }，loading 时加载圈优先 | 一致收录 |
| 自定义文字插槽 | 一参考提供文字作用域插槽 | 不提供 | 文字内容与显隐已由 activeText / inactiveText 覆盖，样式走令牌，插槽重复 |
| loading | 一参考提供加载（另可定制加载图标类型 / 尺寸 / 名称） | loading 自绘加载圈并拦截点击 | 过程态反馈形态全库统一，尺寸随圆钮几何推导，不开放加载图标定制 |
| 自定义选中值 | 一参考 activeValue / inactiveValue（string / number / boolean） | 仅 Boolean，非 Boolean 两态在页面 change 回调映射 | 受控模型下一行映射即可，双值属性徒增心智 |
| 表单联动 | 一参考表单上下文禁用联动，另一参考 name + 原生表单 behaviors | 走库内 n-form 校验模型，不设 name | uni-app x 表单提交模型不同，行职责由 n-form-item 承担 |
| 触觉反馈 | 一参考切换时发宿主全局振动事件 | 不内置，业务侧在 change 回调调 uni.vibrateShort | 振动开关与强度属应用级体验决策（库内键盘族同款裁决） |
| 勾选盒形态 | 一参考内置 switch / checkbox 双形态 | 不收录 | 库内 n-checkbox 承担 |