开关 Switch
开关选择器。
安装
npm install antd-mobile@5.43.0
antd-mobile 是移动网页组件库，不是 React Native 或小程序组件。React 19 项目需在入口用 unstableSetRender 注册 createRoot，否则 Toast、Dialog 等命令式 API 无法渲染；深色模式通过 <html data-prefers-color-scheme="dark"> 切换。
示例来自 Ant Design Mobile 官方仓库（MIT），固定在 npm 5.43.0 对应的提交；示例中的 DemoBlock 等展示辅助组件由 JGuang 重写，不属于 antd-mobile 的 API。
开关选择器。
何时使用
- 需要表示开关状态/两种状态之间的切换时。
- 和 checkbox 的区别是，切换 switch 会直接触发状态改变，而 checkbox 一般用于状态标记，需要和提交操作配合。
示例
Switch
属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| beforeChange（已弃用） | 变化前执行（已弃用，推荐使用 onChange 属性） | (val: boolean) => Promise<void> | - |
| checked | 指定当前是否打开 | boolean | false |
| checkedText | 选中时的内容 | ReactNode | - |
| defaultChecked | 初始是否打开 | boolean | false |
| disabled | 禁用状态 | boolean | false |
| loading | 加载状态 | boolean | false |
| onChange | 变化时的回调函数，当返回 Promise 时，会自动显示加载状态 | (val: boolean) => void | Promise<void> | - |
| uncheckedText | 非选中时的内容 | ReactNode | - |
CSS 变量
| 属性 | 说明 | 默认值 |
|---|---|---|
| --border-width | 边框宽度 | 2px |
| --checked-color | 填充颜色 | var(--adm-color-primary) |
| --height | 高度 | 31px |
| --width | 宽度 | 51px |
FAQ
如何处理异步 onChange 中的异常？
onChange 事件支持返回一个 Promise，当 Promise 开始时，Switch 会自动进入加载状态，而当 Promise 完成或失败时，Switch 会自动退出加载状态。一般情况下，这满足大多数项目的需求。
但是当 Promise 失败时，Switch 并不会吃掉报错，而是会把这个错误对象重新抛出来，这是预期行为，如果你想自己拦截掉一些错误，避免他们被抛出，可以使用 try/catch 包裹 onChange 中的处理逻辑，例如：
async function onChange(val: boolean) {
try {
await doSomething();
} catch (e) {
// handle or ignore error
}
}