Checkbox 复选框
多选框,在一组备选项中进行多选。
警告
label 作为 value 使用已被弃用,label 现在仅用作显示文本,此行为将在 3.0.0 版本中移除,请考虑切换到新的 API。
提示
新的 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>基础用法
复选框可以单独使用,用于在两个状态之间切换。
在 el-checkbox 中定义 v-model(绑定变量)。 对于单个 checkbox,默认值为 Boolean 类型,选中时变为 true。 el-checkbox 标签内的内容将作为复选框后的描述文字。
禁用状态
多选框不可用状态。
设置 disabled 属性即可。
多选框组
适用于多个勾选框绑定到同一个数组的情景,通过是否勾选来表示选中的选项。
checkbox-group 元素能通过 v-model 绑定 Array 数组来管理多个复选框。 在 el-checkbox 元素中,value 是复选框的值。 如果没有嵌套内容,label 将被渲染为复选框后的描述。 value 也与数组中的元素值相对应。 如果指定的值存在于数组中,则为选中状态,反之亦然。
Options 属性 2.11.2
基础 el-checkbox-group 用法的快捷方式。 您可以通过 props 属性自定义 options 的别名。
不确定状态
indeterminate 属性用以表示复选框的不确定状态,通常用于实现全选效果。
可选项目数量的限制
min 和 max 属性能够限制可以选中的复选框数量。
按钮样式
按钮样式的复选框。
只需将 el-checkbox 元素替换为 el-checkbox-button 元素即可。 我们还提供了 size 属性。
带有边框
border 属性可以为复选框添加边框。
Checkbox API
Checkbox 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string / number / boolean | — |
| value 2.6.0 | 当在 checkbox-group 中使用时,Checkbox 的值 | string / number / boolean / object | — |
| label | 当在 checkbox-group 中使用时,Checkbox 的标签。 如果没有 value,label 将作为 value 使用 | string / number / boolean / object | — |
| true-value 2.6.0 | 选中时的值 | string / number | — |
| false-value 2.6.0 | 未选中时的值 | string / number | — |
| disabled | 是否禁用 | boolean | false |
| 边框 | 是否显示边框 | boolean | false |
| size | Checkbox 的尺寸 | 枚举 | — |
| 名称 | 原生 name 属性 | string | — |
| checked | 是否选中 | boolean | false |
| indeterminate | 设置不确定状态,仅负责样式控制 | boolean | false |
| validate-event | 是否触发表单验证 | boolean | true |
| tabindex | 输入框的 tabindex | string / number | — |
| id | 输入框 ID | string | — |
| aria-controls a11y 2.7.2 | 与 aria-controls 相同,在 indeterminate 为 true 时生效 | string | — |
| aria-label 无障碍 | 原生 aria-label 属性 | string | — |
| true-label 已弃用 | 选中时的值 | string / number | — |
| false-label 已弃用 | 未选中时的值 | string / number | — |
| controls a11y 已弃用 | 与 aria-controls 相同,在 indeterminate 为 true 时生效 | string | — |
Checkbox 事件
| 名称 | 描述 | 类型 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | Function |
Checkbox 插槽
| 名称 | 描述 |
|---|---|
| default | 自定义默认内容 |
CheckboxGroup API
CheckboxGroup 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | array | [] |
| size | 多选框组尺寸 | 枚举 | — |
| disabled | 是否禁用所有复选框 | boolean | false |
| min | 最小选择数量 | number | — |
| max | 最大选择数量 | number | — |
| aria-label a11y 2.7.2 | 原生 aria-label 属性 | string | — |
| text-color | 按钮激活时的字体颜色 | string | #ffffff |
| 填充色 | 按钮激活时的填充色和边框色 | string | #409eff |
| tag | 多选框组自定义元素标签 | string | div |
| validate-event | 是否触发表单验证 | boolean | true |
| label a11y 已废弃 | 原生 aria-label 属性 | string | — |
| options 2.11.2 | 选项数据,其中 `value` 和 `label` 和 `disabled` 的键名可以通过 `props` 自定义 | array | — |
| props 2.11.2 | 配置选项 | object | {value: 'value', label: 'label', disabled: 'disabled'} |
| type 2.11.5 | 渲染选项的组件类型(例如:'button') | 枚举 | 'checkbox' |
CheckboxGroup 事件
| 名称 | 描述 | 类型 |
|---|---|---|
| change | 当绑定值变化时触发的事件 | Function |
CheckboxGroup 插槽
| 名称 | 描述 | 子标签 |
|---|---|---|
| default | 自定义默认内容 | Checkbox / Checkbox-button (默认插槽) |
CheckboxButton API
CheckboxButton 属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| value 2.6.0 | 当在 checkbox-group 中使用时,多选框的值 | string / number / boolean / object | — |
| label | 当在 checkbox-group 中使用时,多选框的标签。 如果没有 value,label 将作为 value 使用 | string / number / boolean / object | — |
| true-value 2.6.0 | 选中时的值 | string / number | — |
| false-value 2.6.0 | 未选中时的值 | string / number | — |
| disabled | 是否禁用 | boolean | false |
| 名称 | 原生 name 属性 | string | — |
| checked | 是否选中 | boolean | false |
| true-label 已弃用 | 选中时的值 | string / number | — |
| false-label 已弃用 | 未选中时的值 | string / number | — |
CheckboxButton 插槽
| 名称 | 描述 |
|---|---|
| default | 自定义默认内容 |