Checkbox 多选框

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

WARNING

label 作为 value 来使用已经被 废弃, 建议label 只用来表示展示的文字,这个被废弃的用法将会在 3.0.0 版本被移除,请考虑使用新 API 替换.

TIP

新的 API value 已在 2.6.0 版本添加,文档中的示例都将使用 value。 如果您使用的版本 低于 2.6.0 并且使用 checkbox-group,请参考:

vue
<template>
  <el-checkbox-group v-model="checkList">
    <!-- works when >=2.6.0, recommended ✔️ value not work when <2.6.0 ❌ -->
    <el-checkbox label="Option 1" value="Value 1" />
    <!-- works when <2.6.0, deprecated act as value when >=3.0.0 -->
    <el-checkbox label="Option 2 & Value 2" />
  </el-checkbox-group>
</template>

基础用法

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

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

禁用状态

多选框不可用状态。

设置 disabled 属性即可。

多选框组

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

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

中间状态

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

可选项目数量的限制

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

按钮样式

按钮样式的多选组合。

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

带有边框

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

Checkbox API

Checkbox Attributes

属性名说明类型默认值
model-value / v-model选中项绑定值string / number / boolean
value 2.6.0选中状态的值(只有在checkbox-group或者绑定对象类型为array时有效)string / number / boolean / object
label选中状态的值,只有在绑定对象类型为 array 时有效。 如果没有 value, label则作为value使用string / number / boolean / object
true-value 2.6.0选中时的值string / number
false-value 2.6.0没有选中时的值string / number
disabled是否禁用booleanfalse
border是否显示边框booleanfalse
sizeCheckbox 的尺寸enum
name原生 name 属性string
checked当前是否勾选booleanfalse
indeterminate设置不确定状态,仅负责样式控制booleanfalse
validate-event输入时是否触发表单的校验booleantrue
tabindex输入框的 tabindexstring / number
idinput idstring
aria-controls a11y 2.7.2aria-control一致, 当 indeterminatetrue时生效string
true-label deprecated选中时的值string / number
false-label deprecated没有选中时的值string / number
controls a11y deprecatedaria-control一致。当 indeterminatetrue 时生效string

Checkbox Events

事件名说明类型
change当绑定值变化时触发的事件Function

Checkbox Slots

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

CheckboxGroup API

CheckboxGroup Attributes

属性名说明类型默认值
model-value / v-model绑定值object[]
size多选框组尺寸enum
disabled是否禁用booleanfalse
min可被勾选的 checkbox 的最小数量number
max可被勾选的 checkbox 的最大数量number
aria-label a11y 2.7.2原生 aria-label属性string
text-color当按钮为活跃状态时的字体颜色string#ffffff
fill当按钮为活跃状态时的边框和背景颜色string#409eff
tag复选框组元素标签stringdiv
validate-event是否触发表单验证booleantrue
label a11y deprecated原生 aria-label属性string

CheckboxGroup Events

事件名说明类型
change当绑定值变化时触发的事件Function

CheckboxGroup Slots

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

CheckboxButton API

CheckboxButton Attributes

名称详情类型默认值
value 2.6.0选中状态的值,只有在绑定对象类型为 array 时有效。string / number / boolean / object
label选中状态的值,只有在绑定对象类型为 array 时有效。 如果没有 value, label则作为value使用string / number / boolean / object
true-value 2.6.0选中时的值string / number
false-value 2.6.0没有选中时的值string / number
disabled是否禁用booleanfalse
name原生 name 属性string
checked当前是否勾选booleanfalse
true-label deprecated选中时的值string / number
false-label deprecated没有选中时的值string / number

CheckboxButton Slots

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

源代码

组件样式文档

贡献者