UseElCheckbox - 多选框

组件介绍

UseElCheckbox 是基于 Element Plus 的 ElCheckbox 与 ElCheckboxGroup 二次封装的复选框组组件，专注于为复选框场景提供开箱即用的全选 / 半选状态管理、多数据格式兼容、字符串自动拼接能力，同时标准化选项字段映射配置，完整兼容原生 ElCheckbox 核心属性，可直接替换原生复选框组使用，大幅降低多选场景的重复开发成本。

核心能力

开箱即用的全选能力

内置全选复选框功能（showCheckAll），开启后自动显示全选选项，自动维护全选 / 半选 / 未选三种状态逻辑，无需手动编写全选切换与状态判断代码，勾选全选时自动选中所有选项，取消全选时清空所有选中项，选中部分选项时自动展示半选状态，满足批量选择场景需求。

多格式数据自动兼容

内置数据格式自动转换能力，同时支持对象数组与基础类型数组（String/Number）两种数据源格式：传入对象数组时直接渲染，传入基础类型数组时自动转换为 {label, value} 标准格式，无需业务侧手动做数据格式转换，降低数据适配成本。

灵活的双向绑定格式

支持两种 v-model 绑定格式：默认使用数组格式存储选中值，开启 toJoin 配置后自动将选中值转换为逗号分隔字符串格式，适配后端接口字符串传参场景；接收字符串格式值时自动按逗号分割解析为数组，并根据选项 value 类型自动做 Number 类型转换，保证数据类型一致性。

标准化的字段映射配置

通过 defaultProps 配置项自定义选项的 label 与 value 字段映射，默认使用 {label: 'label', value: 'value'} 标准字段，业务侧可根据后端返回数据结构灵活配置字段名，无需手动遍历数据做字段转换，适配不同接口返回格式。

原生复选框完全兼容

基于 ElCheckbox 与 ElCheckboxGroup 封装，完整保留原生复选框的核心交互与样式特性，支持水平与垂直两种布局方式（vertical 配置），垂直布局下自动调整复选框为块级排列，可直接替换原生 ElCheckboxGroup 使用，无迁移成本。

智能的状态管理

内部自动维护全选状态与半选状态的联动逻辑：单个选项勾选变化时自动计算全选状态，全部选中时自动勾选全选框，部分选中时自动展示半选状态，无需业务侧监听 change 事件手动计算状态，保证交互逻辑的准确性与一致性。

类型安全的双向绑定

基于 TypeScript 类型系统，完整推导 props 与 emits 类型，update:modelValue 事件同时支持 string、number 与 (string | number)[] 多种返回值类型，与 toJoin 配置联动保证类型匹配，避免类型错误，提升开发体验。

简洁的 API 设计

采用极简 API 设计，仅暴露 data（必传选项数据）、v-model（绑定值）、showCheckAll（全选开关）、vertical（布局方向）、toJoin（字符串拼接开关）、defaultProps（字段映射）六个核心配置项，学习成本低，覆盖 90% 以上复选框组业务场景，开箱即用。

使用

UseElCheckbox

Props

import type { PropType } from 'vue'

/**
 * 组件props
 */
export default {
  /**
   * 双向绑定数据源
   */
  modelValue: {
    type: [Array, String, Number, Boolean],
    default: () => []
  },
  /**
   * 选项数据源 如不传则默认为单个复选框
   */
  data: {
    type: Array as PropType<Record<string, any>[] | string[] | number[]>,
    default: undefined
  },
  /**
   * 选项默认配置
   */
  defaultProps: {
    type: Object,
    default: () => ({ label: 'label', value: 'value' })
  },
  // 是否显示全选按钮
  showCheckAll: {
    type: Boolean,
    default: false
  },
  /**
   * 是否垂直布局
   */
  vertical: {
    type: Boolean,
    default: false
  },
  /**
   * 是否字符串拼接
   */
  toJoin: {
    type: Boolean,
    default: false
  }
}

Types

import type { ExtractPropTypes } from 'vue'
import componentProps from './props'

/**
 * props类型
 */
export type Props = ExtractPropTypes<typeof componentProps>

/**
 * emits类型
 */
export type Emits = {
  /** 更新value值 */
  (
    e: 'update:modelValue',
    value: string | number | boolean | (string | number)[]
  ): void
}

UseElCheckbox - 多选框 ​

组件介绍 ​

核心能力 ​

使用 ​

Props ​

Types ​

UseElCheckbox - 多选框

组件介绍

核心能力

使用

Props

Types