跳到主要内容

Checkbox 复选框 ​

uni-appH5微信小程序App

跨端布尔复选框,使用 v-model 双向绑定。

何时使用 ​

多项选择、协议勾选、全选/半选层级选择。

何时不使用 ​

单选场景用 Radio;开关状态切换用 Switch。

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

9:41
Checkbox 复选框 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuebooleanfalse绑定值,配合 v-model 使用(等价 v-model:checked)
labelstring""标签文本;默认插槽存在时被覆盖
disabledbooleanfalse禁用,不响应点击
checkedbooleanfalse选中状态,对应 v-model:checked
indeterminatebooleanfalse半选状态(横杠),视觉上优先于 checked,常用于全选父项

Events ​

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

示例 ​

基础用法 ​

vue
<Checkbox v-model="agree" label="同意用户协议" />

多选组合 ​

vue
<Stack :gap="10">
  <Checkbox v-model="r1" label="Vue 3" />
  <Checkbox v-model="r2" label="uni-app" />
  <Checkbox v-model="r3" label="uni-app X" />
</Stack>

禁用 ​

vue
<view class="row">
  <Checkbox v-model="tf1" disabled label="已锁定" />
  <Checkbox disabled label="不可选" />
</view>

半选状态 ​

vue
<view class="row">
  <Checkbox v-model:checked="tf1" label="已选" />
  <Checkbox indeterminate label="半选(部分子项选中)" />
</view>