Checkbox 复选框
uni-appH5微信小程序App
跨端布尔复选框,使用 v-model 双向绑定。
何时使用
多项选择、协议勾选、全选/半选层级选择。
何时不使用
单选场景用 Radio;开关状态切换用 Switch。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | boolean | false | 绑定值,配合 v-model 使用(等价 v-model:checked) |
label | string | "" | 标签文本;默认插槽存在时被覆盖 |
disabled | boolean | false | 禁用,不响应点击 |
checked | boolean | false | 选中状态,对应 v-model:checked |
indeterminate | boolean | false | 半选状态(横杠),视觉上优先于 checked,常用于全选父项 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | boolean | - |
change | boolean | 选中状态变化时触发,携带新值;disabled 时不触发 |
update:checked | boolean | 点击切换时触发,用于 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>