Checkbox 多选框组件是基于 Element Plus 的 el-checkbox 和 el-checkbox-group 组件封装而成，提供了更简洁的配置方式，支持通过 options 数组快速生成多选框组。

INFO

Checkbox 组件完全继承了 Element Plus Checkbox 组件的所有属性和事件，因此支持所有 Element Plus Checkbox 组件的功能。

注意

option配置的事件名统一约定为 'on[事件名]'，例如：'onChange'等

基础用法

通过 v-model 进行双向绑定，可以单独使用单个多选框。

loading

组模式

通过 enable-group 属性启用组模式，组件会在外层包裹 el-checkbox-group，提供更好的语义和样式控制。组模式适合需要统一管理多个多选框的场景，使用 options 数组配置选项。

loading

属性说明

属性名	类型	默认值	说明
options	Array	[]	选项列表，每个选项是一个对象，详见下方 options 选项配置
modelValue / v-model	Boolean | Array	undefined	绑定值，单个多选框时为布尔值，多选框组时为数组，数组中的值对应 options 中选项的 value
enableGroup	Boolean	false	是否启用组模式，启用后会在外层包裹 el-checkbox-group，提供更好的语义和样式控制
label	String	''	单个多选框的显示文本（非组模式时使用）
disabled	Boolean	false	是否禁用（非组模式时使用）
其他属性	-	-	支持透传 Element Plus el-checkbox 和 el-checkbox-group 组件的所有属性（如 size、border、min、max 等）

options 选项配置

options 数组中的每个选项对象支持以下属性：

属性名	类型	必填	说明
label	String	是	选项的显示文本
value	String | Number	是	选项的值，必须唯一，用于标识该选项
disabled	Boolean	否	是否禁用该选项，默认为 false
onChange	Function	否	该选项的 change 事件处理函数，接收选中的值作为参数
其他属性	-	-	支持透传 Element Plus el-checkbox 组件的所有属性（如 size、border 等）

TIP

• options 中的 onChange 或 change 事件处理函数会接收 Element Plus 传递的完整参数
• 除了上述属性外，options 中的每个选项对象还支持透传 Element Plus el-checkbox 组件的所有属性和事件
• value 的值类型可以是字符串或数字，但必须与 modelValue 数组中的值类型保持一致
• 在组模式下，modelValue 必须是一个数组，数组中的值对应已选中的选项的 value

事件说明

事件名	说明	回调参数	触发时机
change	绑定值变化时触发的事件	(value: Boolean | Array) - 选中的值	当用户选择或取消选择选项时触发
update:modelValue	绑定值更新时触发（用于 v-model 双向绑定）	(value: Boolean | Array) - 新的值	当 modelValue 值发生变化时触发，用于实现双向绑定

TIP

• change 事件会在用户交互时触发，而 update:modelValue 事件会在值更新时触发（包括程序修改值的情况）
• 组件级别的 @change 事件会在任何选项变化时触发
• 选项级别的 onChange 事件只在该选项被选中或取消选中时触发
• 单个多选框时，change 事件传递的是布尔值
• 多选框组时，change 事件传递的是数组，包含所有选中项的 value 值

注意事项

1. 组模式 vs 非组模式：

   • 非组模式（enableGroup: false）：每个 checkbox 独立管理，适合简单的多选场景，代码更简洁
   • 组模式（enableGroup: true）：使用 el-checkbox-group 包裹，提供更好的语义和样式控制，推荐在复杂场景中使用，特别是需要统一管理多个多选框时

2. 值绑定：

   • 使用 v-model 进行双向绑定，这是推荐的方式
   • 单个多选框时，modelValue 为布尔值（true 表示选中，false 表示未选中）
   • 多选框组时，modelValue 必须是一个数组，数组中的值对应 options 中已选中选项的 value 值
   • value 和 modelValue 数组中的值类型必须保持一致（都是字符串或都是数字）

3. 事件处理优先级：

   • 选项对象中的事件处理函数（如 onChange）优先级最高
   • 如果选项对象中没有配置，则使用组件级别的事件处理函数
   • 组件级别的 @change 事件会在任何选项变化时触发，不受上述优先级影响

4. 事件处理：

   • 组件级别的 @change 事件会在任何选项变化时触发
   • 选项级别的 onChange 或 change 事件只在该选项被选中或取消选中时触发
   • 所有事件处理函数都会接收 Element Plus 传递的完整参数

5. Element Plus 兼容性：

   • 组件完全兼容 Element Plus Checkbox 的所有功能和 API
   • 可以参考 Element Plus Checkbox 文档 了解更多高级用法
   • 支持透传 Element Plus el-checkbox 和 el-checkbox-group 的所有属性和事件
   • 支持 min 和 max 属性限制多选框组的最小和最大选中数量