企业官网建设流程全解析

Element Plus Checkbox 完全指南：从基础用法到 API 深度解析

【免费下载链接】element-plus🎉 A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus

Element Plus 的 Checkbox（复选框）组件用于一组多选选项，支持单选切换、分组绑定、全选反选、数量限制、按钮样式与边框样式等多种形态，是表单场景中高频使用的交互组件。本文以 docs/en-US/component/checkbox.md 文档为主线，结合 packages/components/checkbox 目录下的源码实现与 docs/examples/checkbox 中的全部示例，系统讲解el-checkbox、el-checkbox-group、el-checkbox-button的用法、value/label新旧 API 的演进与迁移要点，以及全部配置项与事件。

版本与 API 演进：label与value的正确用法

在深入示例之前，必须先理解本组件最关键的 API 演进问题。文档开篇即给出两条重要说明：

• label作为value使用的行为已被标记为deprecated（废弃），label今后只作为展示文本使用，该兼容行为将在 ^(3.0.0) 版本中移除，应尽早迁移到新 API。
• 新 APIvalue于^(2.6.0)版本加入，文档中的示例全部使用value。

如果在checkbox-group中使用旧版本（低于 2.6.0），文档给出了兼容两种版本的写法：

<template> <el-checkbox-group v-model="checkList"> <!-- 版本 >= 2.6.0 时生效（推荐 ✔️），版本 < 2.6.0 时 value 不生效 ❌ --> <el-checkbox label="Option 1" value="Value 1" /> <!-- 版本 < 2.6.0 时生效；版本 >= 3.0.0 时作为 value 使用的行为被移除（deprecated） --> <el-checkbox label="Option 2 & Value 2" /> </el-checkbox-group> </template>

从源码 checkbox.ts 可以看到，value与label的类型均被定义为[String, Boolean, Number, Object]，而trueLabel/falseLabel属性在源码注释中明确标注了@deprecated use trueValue instead，即旧属性true-label/false-label已被true-value/false-value取代。因此在编写新代码时，应统一使用value+true-value/false-value组合。

基础用法：单独使用切换两种状态

单个el-checkbox即可独立使用，用于在两个状态之间切换。通过v-model绑定变量，默认值为Boolean类型——选中时变为true，取消选中时变为false。el-checkbox标签内部的内容会渲染为复选框按钮后方的描述文字。

参考完整示例 docs/examples/checkbox/basic.vue，同时展示了三种尺寸：

<template> <div> <el-checkbox v-model="checked1" label="Option 1" size="large" /> <el-checkbox v-model="checked2" label="Option 2" size="large" /> </div> <div class="my-2"> <el-checkbox v-model="checked3" label="Option 1" /> <el-checkbox v-model="checked4" label="Option 2" /> </div> <div class="mt-2"> <el-checkbox v-model="checked5" label="Option 1" size="small" /> <el-checkbox v-model="checked6" label="Option 2" size="small" /> </div> </template> <script lang="ts" setup> import { ref } from 'vue' const checked1 = ref(true) const checked2 = ref(false) const checked3 = ref(false) const checked4 = ref(false) const checked5 = ref(false) const checked6 = ref(false) </script>

size属性支持'large' | 'default' | 'small'三个取值，在源码中通过useSizeProp定义（见 checkbox.ts），未设置时继承组件库全局的尺寸配置。

禁用状态

给复选框设置disabled属性即可使其不可交互，同时保留其选中状态的展示。参考 docs/examples/checkbox/disabled.vue：

<template> <el-checkbox v-model="checked1" disabled>Disabled</el-checkbox> <el-checkbox v-model="checked2">Not disabled</el-checkbox> </template> <script lang="ts" setup> import { ref } from 'vue' const checked1 = ref(false) const checked2 = ref(true) </script>

disabled属性的默认值为false。需要说明的是，单个复选框的disabled仅控制自身；而在分组场景下，checkbox-group上的disabled会作用于组内所有嵌套复选框（详见下文 CheckboxGroup API）。

复选框组：checkbox-group多选管理

checkbox-group用于将多个复选框绑定为一组，通过v-model绑定一个数组来管理选中项，并据此判断每个选项是否被选中。

文档明确了两条规则：

• el-checkbox上的value就是该复选框的值；
• 如果标签内没有嵌套内容，label会被渲染为复选框按钮后的描述文字；
• value与数组中的元素一一对应——数组中存在该值则选中，否则不选中。

参考 docs/examples/checkbox/grouping.vue：

<template> <el-checkbox-group v-model="checkList"> <el-checkbox label="Option A" value="Value A" /> <el-checkbox label="Option B" value="Value B" /> <el-checkbox label="Option C" value="Value C" /> <el-checkbox label="disabled" value="Value disabled" disabled /> <el-checkbox label="selected and disabled" value="Value selected and disabled" disabled /> </el-checkbox-group> </template> <script lang="ts" setup> import { ref } from 'vue' const checkList = ref(['Value selected and disabled', 'Value A']) </script>

分组模式下，绑定值的类型在源码 checkbox-group.ts 中被定义为CheckboxGroupValueType = Exclude<CheckboxValueType, boolean>[]，即string[] | number[]，排除了布尔值；modelValue默认值为空数组[]。组件的change与update:modelValue事件均要求参数是数组（isArray校验）。

Options 属性：通过数据快捷渲染（^(2.11.2)）

自 ^(2.11.2) 起，checkbox-group支持options属性，可直接传入数据数组，省去手写多个el-checkbox的模板代码，是基础分组用法的快捷方式。同时通过props属性自定义options中字段的别名映射。

参考 docs/examples/checkbox/options.vue：

<template> <el-checkbox-group v-model="checkList" :options="options" :props="props" /> </template> <script lang="ts" setup> import { ref } from 'vue' const checkList = ref(['Value selected and disabled', 'Value A']) const props = { label: 'name', value: 'id', disabled: 'unable' } const options = [ { name: 'Option A', id: 'Value A' }, { name: 'Option B', id: 'Value B' }, { name: 'Option C', id: 'Value C' }, { name: 'disabled', id: 'Value disabled', unable: true }, { name: 'selected and disabled', id: 'Value selected and disabled', unable: true, }, ] </script>

从源码 checkbox-group.ts 可以看到：

• options的类型为CheckboxOption[]，其中CheckboxOption = CheckboxProps & Record<string, any>，即每个选项可以携带复选框的全部属性及任意自定义字段；
• props的默认值为{ label: 'label', value: 'value', disabled: 'disabled' }（见checkboxDefaultProps），即默认约定数据项中的label、value、disabled三个字段名；
• 上面的例子把字段映射为{ label: 'name', value: 'id', disabled: 'unable' }，因此渲染时读取name作为展示文本、id作为选中值、unable作为禁用标志；
• 此外还提供type属性（^(2.11.5)），取值为'checkbox' | 'button'，默认'checkbox'，设置为'button'时即可将选项渲染为按钮样式，无需改用el-checkbox-button。

Indeterminate：实现「全选」效果

indeterminate属性用于表达"部分选中"的中间态，它只负责样式控制（复选框显示为半选状态），并不参与实际的值绑定逻辑，因此常与"全选"复选框配合使用，手动维护全选与中间态的状态。

参考 docs/examples/checkbox/intermediate.vue：

<template> <el-checkbox v-model="checkAll" :indeterminate="isIndeterminate" @change="handleCheckAllChange" > Check all </el-checkbox> <el-checkbox-group v-model="checkedCities" @change="handleCheckedCitiesChange" > <el-checkbox v-for="city in cities" :key="city" :label="city" :value="city"> {{ city }} </el-checkbox> </el-checkbox-group> </template> <script lang="ts" setup> import { ref } from 'vue' import type { CheckboxValueType } from 'element-plus' const checkAll = ref(false) const isIndeterminate = ref(true) const checkedCities = ref(['Shanghai', 'Beijing']) const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen'] const handleCheckAllChange = (val: CheckboxValueType) => { checkedCities.value = val ? cities : [] isIndeterminate.value = false } const handleCheckedCitiesChange = (value: CheckboxValueType[]) => { const checkedCount = value.length checkAll.value = checkedCount === cities.length isIndeterminate.value = checkedCount > 0 && checkedCount < cities.length } </script>

核心逻辑梳理：

1. 初始时isIndeterminate为true，展示"部分选中"样式；
2. 点击"全选"复选框时，若勾选则将cities全部写入checkedCities，否则清空，并将isIndeterminate置为false；
3. 监听checkbox-group的change事件：选中数量等于总城市数时checkAll为true（全选）；选中数量在0与总数之间时isIndeterminate为true（部分选中）。

最小 / 最大选中数量限制

checkbox-group提供min与max属性，分别限制最少与最多可勾选的项数。参考 docs/examples/checkbox/limitation.vue：

<template> <el-checkbox-group v-model="checkedCities" :min="1" :max="2"> <el-checkbox v-for="city in cities" :key="city" :label="city" :value="city"> {{ city }} </el-checkbox> </el-checkbox-group> </template> <script lang="ts" setup> import { ref } from 'vue' const checkedCities = ref(['Shanghai', 'Beijing']) const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen'] </script>

示例中min="1"表示至少保留 1 项被勾选，max="2"表示最多勾选 2 项，达到上限后未选中的复选框将被禁止勾选。在源码 checkbox-group.ts 中，min与max均为Number类型、无默认值，即不设置时不作限制。

按钮样式：el-checkbox-button

将el-checkbox替换为el-checkbox-button即可获得按钮样式的复选框，同样支持size尺寸属性。参考 docs/examples/checkbox/button-style.vue：

<template> <div> <el-checkbox-group v-model="checkboxGroup1" size="large"> <el-checkbox-button v-for="city in cities" :key="city" :value="city"> {{ city }} </el-checkbox-button> </el-checkbox-group> </div> <div class="demo-button-style"> <el-checkbox-group v-model="checkboxGroup2"> <el-checkbox-button v-for="city in cities" :key="city" :value="city"> {{ city }} </el-checkbox-button> </el-checkbox-group> </div> <div class="demo-button-style"> <el-checkbox-group v-model="checkboxGroup3" size="small"> <el-checkbox-button v-for="city in cities" :key="city" :value="city" :disabled="city === 'Beijing'" > {{ city }} </el-checkbox-button> </el-checkbox-group> </div> <div class="demo-button-style"> <el-checkbox-group v-model="checkboxGroup4" size="small" disabled> <el-checkbox-button v-for="city in cities" :key="city" :value="city"> {{ city }} </el-checkbox-button> </el-checkbox-group> </div> </template> <script lang="ts" setup> import { ref } from 'vue' const checkboxGroup1 = ref(['Shanghai']) const checkboxGroup2 = ref(['Shanghai']) const checkboxGroup3 = ref(['Shanghai']) const checkboxGroup4 = ref(['Shanghai']) const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen'] </script>

示例依次展示了：large尺寸、默认尺寸、small尺寸且单个按钮禁用（Beijing）、small尺寸且整组禁用。整组禁用只需在el-checkbox-group上设置disabled，组内所有按钮会一并不可交互。按钮激活时的背景色与文字颜色可通过组件的fill（默认#409eff）与text-color（默认#ffffff）属性自定义。

带边框样式

border属性可以为复选框添加边框，同样可与size配合使用，且支持单独复选框与分组两种场景。参考 docs/examples/checkbox/with-border.vue：

<template> <div> <el-checkbox v-model="checked1" label="Option1" size="large" border /> <el-checkbox v-model="checked2" label="Option2" size="large" border /> </div> <div class="mt-4"> <el-checkbox v-model="checked3" label="Option1" border /> <el-checkbox v-model="checked4" label="Option2" border /> </div> <div class="mt-4"> <el-checkbox-group v-model="checkboxGroup1" size="small"> <el-checkbox label="Option1" value="Value1" border /> <el-checkbox label="Option2" value="Value2" border /> </el-checkbox-group> </div> <div class="mt-4"> <el-checkbox-group v-model="checkboxGroup1" size="small"> <el-checkbox label="Option1" value="Value1" border disabled /> <el-checkbox label="Option2" value="Value2" border disabled /> </el-checkbox-group> </div> </template> <script lang="ts" setup> import { ref } from 'vue' const checked1 = ref(true) const checked2 = ref(false) const checked3 = ref(false) const checked4 = ref(true) const checkboxGroup1 = ref(['Value1']) </script>

在分组中使用时需注意：示例中两个分组复用了同一个checkboxGroup1变量，实际项目中建议每个分组使用独立的绑定变量，避免互相影响。

Checkbox API 全量参考

Checkbox Attributes

上述属性定义可在 checkbox.ts 中逐一对照：trueValue/falseValue与废弃的trueLabel/falseLabel均限定为string | number；ariaControls通过useAriaProps(['ariaControls'])注入；validateEvent默认值为true，即复选框变化默认会触发所在表单的校验。

Checkbox Events

在源码 checkbox.ts 中，change事件与update:modelValue事件的参数都经过isString || isNumber || isBoolean校验。

Checkbox Slots

CheckboxGroup API 全量参考

CheckboxGroup Attributes

以上定义均可在 checkbox-group.ts 中核对：modelValue默认值为空数组；tag默认渲染为div；fill与textColor影响按钮激活态配色；options+props提供数据驱动的快捷渲染。

CheckboxGroup Events

CheckboxGroup Slots

CheckboxButton API 全量参考

CheckboxButton Attributes

CheckboxButton Slots

源码结构一览与扩展阅读

如果希望深入理解组件实现，可以关注 packages/components/checkbox/src 目录下的组成：

• checkbox.ts：checkboxProps属性定义、checkboxEmits事件校验；
• checkbox-group.ts：checkboxGroupProps属性定义（含options、props、type）、分组事件校验；
• checkbox.vue 与 checkbox-button.vue：组件渲染模板；
• checkbox-group.vue：分组容器，负责options数据到选项的转换与渲染；
• composables：use-checkbox-model（值绑定）、use-checkbox-status（选中状态）、use-checkbox-disabled（禁用状态）、use-checkbox-event（事件）等组合式逻辑；
• constants.ts：供父组件与子组件通信的注入 key；
• tests/checkbox.test.tsx：组件测试用例，覆盖基本选中、分组、禁用、限制等行为。

迁移建议小结

1. 新项目与 2.6.0+ 版本请统一使用value指定选项值，label只负责展示文本，避免未来 3.0.0 升级时出现行为断裂；
2. 复杂的分组选项优先使用options+props+type="button"数据驱动写法，减少模板重复；
3. 全选/半选场景将indeterminate视作纯样式开关，配合change事件手动维护状态；
4. 需要限制选择范围时使用min/max，并结合表单校验场景保留validate-event的默认开启行为。

【免费下载链接】element-plus🎉 A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus