Checkbox 多选框

在一组备选项中进行多选。

基础用法

单独使用可以表示两种状态之间的切换，写在标签中的内容为 checkbox 按钮后的介绍。

checkbox-group元素能把多个 checkbox 管理为一组，只需要在 Group 中使用 v-model 绑定 Array 类型的变量即可。 只有一个选项时的默认值类型为 Boolean，当选中时值为true。 el-checkbox 标签中的内容将成为复选框按钮之后的描述。

Checkbox 多选框 - 图1

  1. <template>
  2.   <div>
  3.     <el-checkbox v-model="checked1" label="Option 1" size="large" />
  4.     <el-checkbox v-model="checked2" label="Option 2" size="large" />
  5.   </div>
  6.   <div>
  7.     <el-checkbox v-model="checked3" label="Option 1" />
  8.     <el-checkbox v-model="checked4" label="Option 2" />
  9.   </div>
  10.   <div>
  11.     <el-checkbox v-model="checked5" label="Option 1" size="small" />
  12.     <el-checkbox v-model="checked6" label="Option 2" size="small" />
  13.   </div>
  14.   <div>
  15.     <el-checkbox v-model="checked5" label="Option 1" size="small" disabled />
  16.     <el-checkbox v-model="checked6" label="Option 2" size="small" disabled />
  17.   </div>
  18. </template>
  20. <script lang="ts" setup>
  21. import { ref } from 'vue'
  23. const checked1 = ref(true)
  24. const checked2 = ref(false)
  25. const checked3 = ref(false)
  26. const checked4 = ref(false)
  27. const checked5 = ref(false)
  28. const checked6 = ref(false)
  29. </script>

禁用状态

多选框不可用状态。

设置 disabled 属性即可。

Checkbox 多选框 - 图2

  1. <template>
  2.   <el-checkbox v-model="checked1" disabled>Disabled</el-checkbox>
  3.   <el-checkbox v-model="checked2">Not disabled</el-checkbox>
  4. </template>
  6. <script lang="ts" setup>
  7. import { ref } from 'vue'
  8. const checked1 = ref(false)
  9. const checked2 = ref(true)
  10. </script>

多选框组

适用于多个勾选框绑定到同一个数组的情景，通过是否勾选来表示这一组选项中选中的项。

在 el-checkbox 元素中定义 v-model 绑定变量，单一的 checkbox 中，默认绑定变量的值会是 Boolean，选中为 true。 在 el-checkbox 组件中，label 是选择框的值。 如果该组件下没有被传入内容，那么 label 将会作为 checkbox 按钮后的介绍。 label 也与数组中的元素值相对应。 如果指定的值存在于数组中，就处于选择状态，反之亦然。

Checkbox 多选框 - 图3

  1. <template>
  2.   <el-checkbox-group v-model="checkList">
  3.     <el-checkbox label="Option A" />
  4.     <el-checkbox label="Option B" />
  5.     <el-checkbox label="Option C" />
  6.     <el-checkbox label="disabled" disabled />
  7.     <el-checkbox label="selected and disabled" disabled />
  8.   </el-checkbox-group>
  9. </template>
  11. <script lang="ts" setup>
  12. import { ref } from 'vue'
  14. const checkList = ref(['selected and disabled', 'Option A'])
  15. </script>

中间状态

indeterminate 属性用以表示 checkbox 的不确定状态，一般用于实现全选的效果

Checkbox 多选框 - 图4

  1. <template>
  2.   <el-checkbox
  3.     v-model="checkAll"
  4.     :indeterminate="isIndeterminate"
  5.     @change="handleCheckAllChange"
  6.     >Check all</el-checkbox
  7.   >
  8.   <el-checkbox-group
  9.     v-model="checkedCities"
  10.     @change="handleCheckedCitiesChange"
  11.   >
  12.     <el-checkbox v-for="city in cities" :key="city" :label="city">{{
  13.       city
  14.     }}</el-checkbox>
  15.   </el-checkbox-group>
  16. </template>
  18. <script lang="ts" setup>
  19. import { ref } from 'vue'
  21. const checkAll = ref(false)
  22. const isIndeterminate = ref(true)
  23. const checkedCities = ref(['Shanghai', 'Beijing'])
  24. const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
  26. const handleCheckAllChange = (val: boolean) => {
  27.   checkedCities.value = val ? cities : []
  28.   isIndeterminate.value = false
  29. }
  30. const handleCheckedCitiesChange = (value: string[]) => {
  31.   const checkedCount = value.length
  32.   checkAll.value = checkedCount === cities.length
  33.   isIndeterminate.value = checkedCount > 0 && checkedCount < cities.length
  34. }
  35. </script>

可选项目数量的限制

使用 min 和 max 属性能够限制可以被勾选的项目的数量。

Checkbox 多选框 - 图5

  1. <template>
  2.   <el-checkbox-group v-model="checkedCities" :min="1" :max="2">
  3.     <el-checkbox v-for="city in cities" :key="city" :label="city">{{
  4.       city
  5.     }}</el-checkbox>
  6.   </el-checkbox-group>
  7. </template>
  9. <script lang="ts" setup>
  10. import { ref } from 'vue'
  12. const checkedCities = ref(['Shanghai', 'Beijing'])
  13. const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
  14. </script>

按钮样式

按钮样式的多选组合。

只需要把 el-checkbox 元素替换为 el-checkbox-button 元素即可。 此外，Element Plus 还提供了size属性。

Checkbox 多选框 - 图6

  1. <template>
  2.   <div>
  3.     <el-checkbox-group v-model="checkboxGroup1" size="large">
  4.       <el-checkbox-button v-for="city in cities" :key="city" :label="city">
  5.         {{ city }}
  6.       </el-checkbox-button>
  7.     </el-checkbox-group>
  8.   </div>
  9.   <div class="demo-button-style">
  10.     <el-checkbox-group v-model="checkboxGroup2">
  11.       <el-checkbox-button v-for="city in cities" :key="city" :label="city">{{
  12.         city
  13.       }}</el-checkbox-button>
  14.     </el-checkbox-group>
  15.   </div>
  16.   <div class="demo-button-style">
  17.     <el-checkbox-group v-model="checkboxGroup3" size="small">
  18.       <el-checkbox-button
  19.         v-for="city in cities"
  20.         :key="city"
  21.         :label="city"
  22.         :disabled="city === 'Beijing'"
  23.         >{{ city }}</el-checkbox-button
  24.       >
  25.     </el-checkbox-group>
  26.   </div>
  27.   <div class="demo-button-style">
  28.     <el-checkbox-group v-model="checkboxGroup4" size="small" disabled>
  29.       <el-checkbox-button v-for="city in cities" :key="city" :label="city">{{
  30.         city
  31.       }}</el-checkbox-button>
  32.     </el-checkbox-group>
  33.   </div>
  34. </template>
  36. <script lang="ts" setup>
  37. import { ref } from 'vue'
  38. const checkboxGroup1 = ref(['Shanghai'])
  39. const checkboxGroup2 = ref(['Shanghai'])
  40. const checkboxGroup3 = ref(['Shanghai'])
  41. const checkboxGroup4 = ref(['Shanghai'])
  42. const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
  43. </script>
  45. <style scoped>
  46. .demo-button-style {
  47.   margin-top: 24px;
  48. }
  49. </style>

带有边框

设置border属性可以渲染为带有边框的多选框。

Checkbox 多选框 - 图7

  1. <template>
  2.   <div>
  3.     <el-checkbox v-model="checked1" label="Option1" size="large" border />
  4.     <el-checkbox v-model="checked2" label="Option2" size="large" border />
  5.   </div>
  6.   <div class="mt-4">
  7.     <el-checkbox v-model="checked3" label="Option1" border />
  8.     <el-checkbox v-model="checked4" label="Option2" border />
  9.   </div>
  10.   <div class="mt-4">
  11.     <el-checkbox-group v-model="checkboxGroup1" size="small">
  12.       <el-checkbox label="Option1" border />
  13.       <el-checkbox label="Option2" border />
  14.     </el-checkbox-group>
  15.   </div>
  16.   <div class="mt-4">
  17.     <el-checkbox-group v-model="checkboxGroup1" size="small">
  18.       <el-checkbox label="Option1" border disabled />
  19.       <el-checkbox label="Option2" border disabled />
  20.     </el-checkbox-group>
  21.   </div>
  22. </template>
  24. <script lang="ts" setup>
  25. import { ref } from 'vue'
  27. const checked1 = ref(true)
  28. const checked2 = ref(false)
  29. const checked3 = ref(false)
  30. const checked4 = ref(true)
  31. const checkboxGroup1 = ref(['Option1'])
  32. </script>

Checkbox 属性

属性说明类型可选值默认值
model-value / v-model选中项绑定值string / number / boolean——
label选中状态的值（只有在checkbox-group或者绑定对象类型为array时有效）string / number / boolean / object——
true-label选中时的值string / number——
false-label没有选中时的值string / number——
disabled是否禁用boolean—false
border是否显示边框boolean—false
sizeCheckbox 的尺寸stringlarge / default / small—
name原生 name 属性string——
checked当前是否勾选boolean—false
indeterminate设置 indeterminate 状态，只负责样式控制boolean—false
validate-event输入时是否触发表单的校验boolean-true

Checkbox 事件

事件名说明回调参数
change当绑定值变化时触发的事件value

Checkbox 插槽

插槽名说明
—自定义默认内容

Checkbox-Group 属性

属性说明类型可选值默认值
model-value / v-model绑定值array—[]
size多选框组尺寸stringlarge / default / small—
disabled是否禁用boolean—false
min可被勾选的 checkbox 的最小数量number——
max可被勾选的 checkbox 的最大数量number——
label为屏幕阅读器准备的标签string——
text-color当按钮为活跃状态时的字体颜色string—#ffffff
fill当按钮为活跃状态时的边框和背景颜色string—#409EFF
validate-event输入时是否触发表单的校验boolean-true

Checkbox-Group 事件

事件名说明回调参数
change当绑定值变化时触发的事件value

Checkbox-Group 插槽

插槽名说明子标签
-自定义默认内容Checkbox / Checkbox-button

Checkbox-Button 属性

属性说明类型可选值默认值
label选中状态的值，只有在绑定对象类型为 array 时有效。string / number / boolean / object——
true-label选中时的值string / number——
false-label没有选中时的值string / number——
disabled是否禁用boolean—false
name原生 name 属性string——
checked当前是否勾选boolean—false

Checkbox-Button 插槽

插槽名描述
—自定义默认内容

源代码

组件 Checkbox 多选框 - 图8 • 文档 Checkbox 多选框 - 图9

贡献者

Checkbox 多选框 - 图10 云游君

Checkbox 多选框 - 图11 三咲智子

Checkbox 多选框 - 图12 JeremyWuuuuu

Checkbox 多选框 - 图13 Xc

Checkbox 多选框 - 图14 zz

Checkbox 多选框 - 图15 C.Y.Kun

Checkbox 多选框 - 图16 Delyan Haralanov

Checkbox 多选框 - 图17 msidolphin

Checkbox 多选框 - 图18 kooriookami

Checkbox 多选框 - 图19 LIUCHAO

Checkbox 多选框 - 图20 Hefty

Checkbox 多选框 - 图21 ytx

Checkbox 多选框 - 图22 一昂

Checkbox 多选框 - 图23 opengraphica

Checkbox 多选框 - 图24 gjfei

Checkbox 多选框 - 图25 btea

Checkbox 多选框 - 图26 iceman

Checkbox 多选框 - 图27 神楽坂みずき

Checkbox 多选框 - 图28 on the field of hope

Checkbox 多选框 - 图29 Hades-li

Checkbox 多选框 - 图30 qiang