Skip to content

Checkbox 复选框 ​

复选框组件,用于多选或开关选项。

何时使用:需要用户从一组选项中选择多个,或切换一个布尔值时使用。单选请使用 Radio。

注意:Checkbox 组件只负责复选框本身,错误消息需要由使用者自行渲染。

基础用法 ​

v-model 绑定 ​

多选(数组模式) ​

通过 value 属性实现多选,v-model 绑定数组。

尺寸 ​

禁用状态 ​

错误状态 ​

error 属性仅控制复选框边框颜色,不渲染错误消息。

自定义标签(插槽) ​

API ​

Props ​

属性类型默认值说明
modelValueboolean | any[]false复选框值(v-model)
labelstring''标签文字
valuestring | numberundefined复选框的值(用于数组绑定)
size'sm' | 'md' | 'lg''md'尺寸
disabledbooleanfalse是否禁用
errorbooleanfalse是否显示错误状态

Slots ​

名称说明
default标签内容(优先级高于 label)

Events ​

事件参数说明
update:modelValue(value: boolean | any[])值变化时触发
change(event: Event)原生 change 事件

注意事项 ​

  • 复选框默认使用自定义样式,不依赖浏览器原生样式
  • error 属性仅控制边框颜色,不渲染错误消息
  • 支持两种模式:
    • 布尔模式:v-model 绑定 boolean,无 value 属性
    • 数组模式:v-model 绑定数组,设置 value 属性
  • 聚焦时显示聚焦环,确保可访问性

Released under the MIT License