跳到主要内容

Switch 开关 ​

uni-appH5微信小程序App

跨端布尔开关,使用 v-model 双向绑定。

何时使用 ​

立即生效的布尔状态切换,如通知开关、功能启用。

何时不使用 ​

表单勾选协议/多选用 Checkbox;互斥单选用 Radio。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
Switch 开关 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuebooleanfalse绑定值,配合 v-model 使用(等价 v-model:checked)
disabledbooleanfalse禁用,不响应点击
checkedbooleanfalse开关状态,对应 v-model:checked
loadingbooleanfalse加载中,圆点上显示旋转小圈并禁用点击
ariaLabelstring"开关"无障碍标签(H5 端生效,App/小程序端无害透传)
sizestring:'sm' | 'md'"md"尺寸:md = 44×24,sm = 34×20

Events ​

名称载荷说明
update:modelValueboolean-
changeboolean状态变化时触发,携带新值;disabled/loading 时不触发
update:checkedboolean点击切换时触发,用于 v-model:checked

示例 ​

基础用法 ​

vue
<Switch v-model="on" />

禁用状态 ​

vue
<view class="row">
  <Switch v-model="tf1" />
  <Switch v-model="tf2" />
  <Switch disabled />
</view>

设置项组合 ​

vue
<CellGroup inset>
  <Cell title="消息推送"><Switch v-model="tf3" /></Cell>
  <Cell title="夜间模式"><Switch v-model="tf4" /></Cell>
</CellGroup>

尺寸与加载 ​

vue
<view class="row">
  <Switch v-model:checked="tf1" size="sm" />
  <Switch v-model:checked="tf2" size="lg" />
  <Switch loading />
</view>