Checkbox 多选框
一组备选项中进行多选。
WARNING
label 作为 value 使用的写法已被弃用,label 将仅作为展示文本,请迁移到新 API。
基础用法
单独使用可在两种状态间切换。
在 el-checkbox 上使用 v-model 绑定变量;单独使用时为布尔值,选中为 true。标签内文本会显示在复选框按钮之后。
禁用状态
禁用多选框。
设置 disabled 属性。
多选框组
用于管理一组绑定的多选框。
checkbox-group 通过数组类型的 v-model 管理多个选项。内部 el-checkbox 的 value 为选中值;若无默认插槽内容,会渲染 label 作为描述。数组包含对应 value 时该项为选中。
选项属性
基于 options 的快捷用法;可通过 props 自定义字段别名。
中间状态
通过 indeterminate 实现「全选」等半选样式。
可选数量限制
通过 min、max 限制可选数量。
按钮样式
按钮外观的多选框。
将 el-checkbox 换为 el-checkbox-button,并可设置 size。
带边框
设置 border 为复选框增加边框样式。
多选框 API
多选框 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string / number / boolean | — |
| value | 在 checkbox-group 中作为选项值 | string / number / boolean / object | — |
| label | 在 checkbox-group 中的标签;未提供 value 时 label 仍会按旧版充当 value | string / number / boolean / object | — |
| true-value | 选中时的绑定值 | string / number | — |
| false-value | 未选中时的绑定值 | string / number | — |
| disabled | 是否禁用 | boolean | false |
| border | 是否显示边框 | boolean | false |
| size | 尺寸 | enum | — |
| name | 原生 name | string | — |
| checked | 是否选中 | boolean | false |
| indeterminate | 不确定状态,仅控制样式 | boolean | false |
| validate-event | 是否触发表单校验 | boolean | true |
| tabindex | 原生 tabindex | string / number | — |
| id | 原生 id | string | — |
| aria-controls a11y | 同 aria-controls,在 indeterminate 为 true 时生效 | string | — |
| aria-label a11y | 原生 aria-label | string | — |
多选框 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 绑定值变化时 | Function |
多选框 插槽
| 名称 | 说明 |
|---|---|
| default | 自定义默认内容 |
多选框组 API
多选框组 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | array | [] |
| size | 尺寸 | enum | — |
| disabled | 是否禁用组内所有多选框 | boolean | false |
| min | 最少勾选数 | number | — |
| max | 最多勾选数 | number | — |
| aria-label a11y | 原生 aria-label | string | — |
| text-color | 按钮样式激活态文字颜色 | string | #ffffff |
| fill | 按钮样式激活态边框与背景色 | string | #2F54EB |
| tag | 多选框组根元素标签 | string | div |
| validate-event | 是否触发表单校验 | boolean | true |
| options | 选项数据;value、label、disabled 等键名可通过 props 映射 | array | — |
| props | 选项字段映射配置 | object | {value: 'value', label: 'label', disabled: 'disabled'} |
| type | 批量渲染类型,如 'button' | enum | 'checkbox' |
多选框组 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 绑定值变化时 | Function |
多选框组 插槽
| 名称 | 说明 | 子标签 |
|---|---|---|
| default | 自定义默认内容 | 多选框 / 多选框按钮 |
多选框按钮 API
多选框按钮 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 在 checkbox-group 中作为选项值 | string / number / boolean / object | — |
| label | 在 checkbox-group 中的标签;未提供 value 时 label 仍会按旧版充当 value | string / number / boolean / object | — |
| true-value | 选中时的绑定值 | string / number | — |
| false-value | 未选中时的绑定值 | string / number | — |
| disabled | 是否禁用 | boolean | false |
| name | 原生 name | string | — |
| checked | 是否选中 | boolean | false |
多选框按钮 插槽
| 名称 | 说明 |
|---|---|
| default | 自定义默认内容 |