Checkbox 多选框

多选框用于在一组备选项中进行多选，也可以单独表示开关式的选中状态。VISTA B 直接使用 Element Plus 的 el-checkbox，样式沿用组件库，适合权限选择、功能模块选择、筛选条件、批量操作确认等场景。

Element Plus 2.6.0 起推荐使用 value 表示选项值，label 只作为展示文案；label 作为值的旧用法已废弃。

基础用法

单独使用时，v-model 默认绑定布尔值；写在标签中的内容会作为多选框后的说明文字。可以通过 size 设置尺寸。

vue

<script setup>
import { ref } from 'vue'

const checked1 = ref(true)
const checked2 = ref(false)
</script>

<template>
  <el-checkbox v-model="checked1" size="large">启用项目提醒</el-checkbox>
  <el-checkbox v-model="checked2">同步客户信息</el-checkbox>
</template>

禁用状态

设置 disabled 后，多选框不可操作。

已锁定可编辑

vue

<el-checkbox v-model="checked1" disabled>已锁定</el-checkbox>
<el-checkbox v-model="checked2">可编辑</el-checkbox>

多选框组

用 el-checkbox-group 管理一组多选框，并通过 v-model 绑定数组。每个 el-checkbox 的 value 会对应数组中的一项。

vue

<script setup>
import { ref } from 'vue'

const checkList = ref(['project', 'quote'])
</script>

<template>
  <el-checkbox-group v-model="checkList">
    <el-checkbox value="project">项目管理</el-checkbox>
    <el-checkbox value="quote">报价配置</el-checkbox>
    <el-checkbox value="material">素材管理</el-checkbox>
    <el-checkbox value="archive" disabled>归档数据</el-checkbox>
  </el-checkbox-group>
</template>

Options 属性

el-checkbox-group 支持通过 options 快速渲染选项。使用 props 可以把业务字段映射为 label、value 和 disabled。

项目管理报价配置素材管理归档数据

vue

<script setup>
import { ref } from 'vue'

const checkList = ref(['project'])
const props = { label: 'name', value: 'id', disabled: 'unable' }
const options = [
  { name: '项目管理', id: 'project' },
  { name: '报价配置', id: 'quote' },
  { name: '归档数据', id: 'archive', unable: true }
]
</script>

<template>
  <el-checkbox-group v-model="checkList" :options="options" :props="props" />
</template>

中间状态

indeterminate 用于表现不确定状态，常见于“全选 / 半选 / 未选”的联动场景。它只控制视觉状态，仍需要在业务代码中维护选中值。

vue

<script setup>
import { ref } from 'vue'

const modules = ['project', 'quote', 'material', 'customer']
const checkAll = ref(false)
const isIndeterminate = ref(true)
const checkedModules = ref(['project', 'quote'])

const handleCheckAllChange = (value) => {
  checkedModules.value = value ? modules : []
  isIndeterminate.value = false
}

const handleCheckedModulesChange = (value) => {
  const checkedCount = value.length
  checkAll.value = checkedCount === modules.length
  isIndeterminate.value = checkedCount > 0 && checkedCount < modules.length
}
</script>

可选数量限制

使用 min 和 max 可以限制多选框组中可勾选的数量。

项目管理报价配置素材管理客户跟进

vue

<el-checkbox-group v-model="checkedModules" :min="1" :max="2">
  <el-checkbox value="project">项目管理</el-checkbox>
  <el-checkbox value="quote">报价配置</el-checkbox>
  <el-checkbox value="material">素材管理</el-checkbox>
  <el-checkbox value="customer">客户跟进</el-checkbox>
</el-checkbox-group>

按钮样式

把 el-checkbox 替换为 el-checkbox-button 后，可以得到按钮式多选组合。尺寸由外层 el-checkbox-group 的 size 控制。

vue

<el-checkbox-group v-model="checkedModules" size="large">
  <el-checkbox-button value="project">项目管理</el-checkbox-button>
  <el-checkbox-button value="quote">报价配置</el-checkbox-button>
  <el-checkbox-button value="material">素材管理</el-checkbox-button>
</el-checkbox-group>

带有边框

设置 border 后，多选框会显示边框，适合在表单块、配置项或空间较松的筛选面板中使用。

vue

<el-checkbox v-model="checked" border>项目管理</el-checkbox>

<el-checkbox-group v-model="checkedModules" size="small">
  <el-checkbox value="project" border>项目管理</el-checkbox>
  <el-checkbox value="quote" border>报价配置</el-checkbox>
</el-checkbox-group>

API

Checkbox 属性

属性	说明	类型	默认值
`model-value` / `v-model`	选中项绑定值	`string` / `number` / `boolean`	空
`value`	选中状态的值，在 `checkbox-group` 或绑定值为数组时有效	`string` / `number` / `boolean` / `object`	空
`label`	展示文本；未设置 `value` 时旧版本也会作为值使用，该用法已废弃	`string` / `number` / `boolean` / `object`	空
`true-value`	选中时的值	`string` / `number`	空
`false-value`	未选中时的值	`string` / `number`	空
`disabled`	是否禁用	`boolean`	`false`
`border`	是否显示边框	`boolean`	`false`
`size`	多选框尺寸	`large` / `default` / `small`	空
`name`	原生 `name` 属性	`string`	空
`checked`	当前是否勾选	`boolean`	`false`
`indeterminate`	是否为不确定状态，仅控制样式	`boolean`	`false`
`validate-event`	输入时是否触发表单校验	`boolean`	`true`
`tabindex`	输入框的 `tabindex`	`string` / `number`	空
`id`	原生 input `id`	`string`	空
`aria-controls`	原生 `aria-controls` 属性，`indeterminate` 为 `true` 时生效	`string`	空
`aria-label`	原生 `aria-label` 属性	`string`	空

Checkbox 事件

事件名	说明	类型
`change`	绑定值变化时触发	`(value: string \| number \| boolean) => void`

Checkbox 插槽

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

CheckboxGroup 属性

属性	说明	类型	默认值
`model-value` / `v-model`	绑定值	`array`	`[]`
`size`	多选框组尺寸	`large` / `default` / `small`	空
`disabled`	是否禁用	`boolean`	`false`
`min`	可被勾选的最小数量	`number`	空
`max`	可被勾选的最大数量	`number`	空
`aria-label`	原生 `aria-label` 属性	`string`	空
`text-color`	按钮激活时的字体颜色	`string`	`#ffffff`
`fill`	按钮激活时的边框和背景颜色	`string`	`#409eff`
`tag`	多选框组元素标签	`string`	`div`
`validate-event`	是否触发表单校验	`boolean`	`true`
`options`	选项数据源	`array`	空
`props`	`options` 的字段映射配置	`object`	`{ value: 'value', label: 'label', disabled: 'disabled' }`
`type`	使用 `options` 渲染时的组件类型	`checkbox` / `button`	`checkbox`

CheckboxGroup 事件

事件名	说明	类型
`change`	绑定值变化时触发	`(value: array) => void`

CheckboxGroup 插槽

插槽	说明	子标签
`default`	自定义默认内容	`Checkbox` / `CheckboxButton`

CheckboxButton 属性

属性	说明	类型	默认值
`value`	选中状态的值，在绑定值为数组时有效	`string` / `number` / `boolean` / `object`	空
`label`	展示文本；未设置 `value` 时旧版本也会作为值使用，该用法已废弃	`string` / `number` / `boolean` / `object`	空
`true-value`	选中时的值	`string` / `number`	空
`false-value`	未选中时的值	`string` / `number`	空
`disabled`	是否禁用	`boolean`	`false`
`name`	原生 `name` 属性	`string`	空
`checked`	当前是否勾选	`boolean`	`false`

CheckboxButton 插槽

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

Checkbox 多选框 ​

基础用法 ​

禁用状态 ​

多选框组 ​

Options 属性 ​

中间状态 ​

可选数量限制 ​

按钮样式 ​

带有边框 ​

API ​

Checkbox 属性 ​

Checkbox 事件 ​

Checkbox 插槽 ​

CheckboxGroup 属性 ​

CheckboxGroup 事件 ​

CheckboxGroup 插槽 ​

CheckboxButton 属性 ​

CheckboxButton 插槽 ​