Checkbox 多选框

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

基础用法

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

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

<template>
  <div>
    <el-checkbox v-model="checked1" label="Option 1" size="large" />
    <el-checkbox v-model="checked2" label="Option 2" size="large" />
  </div>
  <div>
    <el-checkbox v-model="checked3" label="Option 1" />
    <el-checkbox v-model="checked4" label="Option 2" />
  </div>
  <div>
    <el-checkbox v-model="checked5" label="Option 1" size="small" />
    <el-checkbox v-model="checked6" label="Option 2" size="small" />
  </div>
  <div>
    <el-checkbox v-model="checked5" label="Option 1" size="small" disabled />
    <el-checkbox v-model="checked6" label="Option 2" size="small" disabled />
  </div>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const checked1 = ref(true)
const checked2 = ref(false)
const checked3 = ref(false)
const checked4 = ref(false)
const checked5 = ref(false)
const checked6 = ref(false)
</script>

禁用状态

多选框不可用状态。

设置 disabled 属性即可。

<template>
  <el-checkbox v-model="checked1" disabled>Disabled</el-checkbox>
  <el-checkbox v-model="checked2">Not disabled</el-checkbox>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const checked1 = ref(false)
const checked2 = ref(true)
</script>

多选框组

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

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

<template>
  <el-checkbox-group v-model="checkList">
    <el-checkbox label="Option A" />
    <el-checkbox label="Option B" />
    <el-checkbox label="Option C" />
    <el-checkbox label="disabled" disabled />
    <el-checkbox label="selected and disabled" disabled />
  </el-checkbox-group>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const checkList = ref(['selected and disabled', 'Option A'])
</script>

中间状态

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

<template>
  <el-checkbox
    v-model="checkAll"
    :indeterminate="isIndeterminate"
    @change="handleCheckAllChange"
    >Check all</el-checkbox
  >
  <el-checkbox-group
    v-model="checkedCities"
    @change="handleCheckedCitiesChange"
  >
    <el-checkbox v-for="city in cities" :key="city" :label="city">{{
      city
    }}</el-checkbox>
  </el-checkbox-group>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const checkAll = ref(false)
const isIndeterminate = ref(true)
const checkedCities = ref(['Shanghai', 'Beijing'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
const handleCheckAllChange = (val: boolean) => {
  checkedCities.value = val ? cities : []
  isIndeterminate.value = false
}
const handleCheckedCitiesChange = (value: string[]) => {
  const checkedCount = value.length
  checkAll.value = checkedCount === cities.length
  isIndeterminate.value = checkedCount > 0 && checkedCount < cities.length
}
</script>

可选项目数量的限制

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

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

按钮样式

按钮样式的多选组合。

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

<template>
  <div>
    <el-checkbox-group v-model="checkboxGroup1" size="large">
      <el-checkbox-button v-for="city in cities" :key="city" :label="city">
        {{ city }}
      </el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup2">
      <el-checkbox-button v-for="city in cities" :key="city" :label="city">{{
        city
      }}</el-checkbox-button>
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup3" size="small">
      <el-checkbox-button
        v-for="city in cities"
        :key="city"
        :label="city"
        :disabled="city === 'Beijing'"
        >{{ city }}</el-checkbox-button
      >
    </el-checkbox-group>
  </div>
  <div class="demo-button-style">
    <el-checkbox-group v-model="checkboxGroup4" size="small" disabled>
      <el-checkbox-button v-for="city in cities" :key="city" :label="city">{{
        city
      }}</el-checkbox-button>
    </el-checkbox-group>
  </div>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const checkboxGroup1 = ref(['Shanghai'])
const checkboxGroup2 = ref(['Shanghai'])
const checkboxGroup3 = ref(['Shanghai'])
const checkboxGroup4 = ref(['Shanghai'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
</script>
<style scoped>
.demo-button-style {
  margin-top: 24px;
}
</style>

带有边框

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

<template>
  <div>
    <el-checkbox v-model="checked1" label="Option1" size="large" border />
    <el-checkbox v-model="checked2" label="Option2" size="large" border />
  </div>
  <div class="mt-4">
    <el-checkbox v-model="checked3" label="Option1" border />
    <el-checkbox v-model="checked4" label="Option2" border />
  </div>
  <div class="mt-4">
    <el-checkbox-group v-model="checkboxGroup1" size="small">
      <el-checkbox label="Option1" border />
      <el-checkbox label="Option2" border />
    </el-checkbox-group>
  </div>
  <div class="mt-4">
    <el-checkbox-group v-model="checkboxGroup1" size="small">
      <el-checkbox label="Option1" border disabled />
      <el-checkbox label="Option2" border disabled />
    </el-checkbox-group>
  </div>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const checked1 = ref(true)
const checked2 = ref(false)
const checked3 = ref(false)
const checked4 = ref(true)
const checkboxGroup1 = ref(['Option1'])
</script>

Checkbox 属性

Checkbox 事件

Checkbox 插槽

Checkbox-Group 属性

Checkbox-Group 事件

Checkbox-Group 插槽

Checkbox-Button 属性

Checkbox-Button 插槽

源代码

组件 • 文档

贡献者

云游君

三咲智子

JeremyWuuuuu

Xc

zz

C.Y.Kun

Delyan Haralanov

msidolphin

kooriookami

LIUCHAO

Hefty

ytx

一昂

opengraphica

gjfei

btea

iceman

神楽坂みずき

on the field of hope

Hades-li

qiang