Element-UI
表单组件

多选框（Checkbox）

# 多选框（Checkbox）

Element-UI 的多选框组件用于在一组选项中进行多选。通过简单的属性和事件配置，可以实现多种功能和样式。

在 Vue 组件中使用 <el-checkbox> 标签即可创建一个多选框。要使用 Checkbox 组件，只需要设置 v-model 绑定变量。多选框可以单独使用，也可以通过 Checkbox Group 组合使用。

提示

多选框（Checkbox）官方文档：https://element.eleme.cn/#/zh-CN/component/checkbox (opens new window)

# 1. 多选框基本用法

基本语法：单独使用可以表示两种状态之间的切换。

<template>
  <el-checkbox v-model="checked">备选项</el-checkbox>
</template>

<script>
export default {
  data() {
    return {
      checked: false // 多选框的初始状态
    };
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13

切换机制：通过 v-model 绑定的布尔值变量 checked 控制多选框的选中状态。用户勾选或取消勾选时，checked 的值会自动更新。

# Checkbox 属性

参数	说明	类型	可选值	默认值
value / v-model	绑定值	string / number / boolean	—	—
label	选中状态的值（只有在 `checkbox-group` 或者绑定对象类型为 `array` 时有效）	string / number / boolean	—	—
true-label	选中时的值	string / number	—	—
false-label	没有选中时的值	string / number	—	—
disabled	是否禁用	boolean	—	false
border	是否显示边框	boolean	—	false
size	Checkbox 的尺寸，仅在 border 为真时有效	string	medium / small / mini	—
name	原生 name 属性	string	—	—
checked	当前是否勾选	boolean	—	false
indeterminate	设置 indeterminate 状态，只负责样式控制	boolean	—	false

# Checkbox 事件

事件名称	说明	回调参数
change	当绑定值变化时触发的事件	更新后的值

# 2. 常见多选框示例

# 基础多选框

使用 v-model 绑定一个布尔值，通过切换该值来控制多选框的选中状态。

<template>
  <el-checkbox v-model="checked">备选项</el-checkbox>
</template>

<script>
export default {
  data() {
    return {
      checked: false // 多选框的初始状态
    };
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13

# 带边框的多选框

通过 border 属性使多选框带有边框，增加视觉效果。

<template>
  <el-checkbox v-model="checked" border>备选项</el-checkbox>
</template>

1
2
3

# 不确定状态的多选框

使用 indeterminate 属性设置多选框为不确定状态，仅负责样式控制。

<template>
  <el-checkbox v-model="checked" indeterminate>不确定选项</el-checkbox>
</template>

1
2
3

# 3. 多选框组

Checkbox Group 用于将一组 Checkbox 组件组合在一起，便于管理和使用。通过 v-model 绑定一个数组，控制选中的选项。

# Checkbox-group 属性

参数	说明	类型	可选值	默认值
value / v-model	绑定值	array	—	—
size	多选框组尺寸，仅对按钮形式的 Checkbox 或带有边框的 Checkbox 有效	string	medium / small / mini	—
disabled	是否禁用	boolean	—	false
min	可被勾选的 checkbox 的最小数量	number	—	—
max	可被勾选的 checkbox 的最大数量	number	—	—
text-color	按钮形式的 Checkbox 激活时的文本颜色	string	—	#ffffff
fill	按钮形式的 Checkbox 激活时的填充色和边框色	string	—	#409EFF

# Checkbox-group 事件

事件名称	说明	回调参数
change	当绑定值变化时触发的事件	更新后的值

# 4. 多选框组示例

# 基础多选框组

使用 v-model 将一组多选框绑定到一个数组，实现切换。

<template>
  <el-checkbox-group v-model="checkList">
    <el-checkbox label="Option A">备选项 A</el-checkbox>
    <el-checkbox label="Option B">备选项 B</el-checkbox>
    <el-checkbox label="Option C">备选项 C</el-checkbox>
  </el-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      checkList: ['Option A'] // 初始选中的选项
    };
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

切换机制：通过 v-model 绑定的数组 checkList 控制选中的选项。数组包含所有已选中项的 label 值。

# 限制选择数量的多选框组

通过 min 和 max 属性限制多选框组中可选项的数量。

<template>
  <el-checkbox-group v-model="checkList" :min="1" :max="2">
    <el-checkbox label="Option A">备选项 A</el-checkbox>
    <el-checkbox label="Option B">备选项 B</el-checkbox>
    <el-checkbox label="Option C">备选项 C</el-checkbox>
  </el-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      checkList: [] // 初始选中的选项
    };
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 按钮形式的多选框组

使用 el-checkbox-button 实现按钮形式的多选框组，适合用于工具栏等场景。

<template>
  <el-checkbox-group v-model="checkList" size="medium" text-color="#ff0000" fill="#ffcccc">
    <el-checkbox-button label="Option A">备选项 A</el-checkbox-button>
    <el-checkbox-button label="Option B">备选项 B</el-checkbox-button>
    <el-checkbox-button label="Option C">备选项 C</el-checkbox-button>
  </el-checkbox-group>
</template>

1
2
3
4
5
6
7

# 5. 多选按钮

Checkbox Button 提供了一种按钮风格的多选框形式，通常用于更具交互性的场景。

# Checkbox-button 属性

参数	说明	类型	可选值	默认值
label	选中状态的值（只有在 `checkbox-group` 或者绑定对象类型为 `array` 时有效）	string / number / boolean	—	—
true-label	选中时的值	string / number	—	—
false-label	没有选中时的值	string / number	—	—
disabled	是否禁用	boolean	—	false
name	原生 name 属性	string	—	—
checked	当前是否勾选	boolean	—	false

# 6. 多选按钮示例

# 基础按钮多选框

使用 el-checkbox-button 代替普通的 el-checkbox，实现按钮形式的多选框。

<template>
  <el-checkbox-group v-model="checkList">
    <el-checkbox-button label="Option A">备选项 A</el-checkbox-button>
    <el-checkbox-button label="Option B">备选项 B</el-checkbox-button>
    <el-checkbox-button label="Option C">备选项 C</el-checkbox-button>
  </el-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      checkList: ['Option A'] // 初始选中的按钮
    };
  }
};
</script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 禁用状态的按钮多选框

通过 disabled 属性禁用整个按钮组或其中的某个按钮。

<template>
  <el-checkbox-group v-model="checkList" disabled>
    <el-checkbox-button label="Option A">备选项 A</el-checkbox-button>
    <el-checkbox-button label="Option B">备选项 B</el-checkbox-button>
    <el-checkbox-button label="Option C">备选项 C</el-checkbox-button>
  </el-checkbox-group>
</template>

1
2
3
4
5
6
7

总结

多样化的多选框类型：Element-UI 提供了普通、带边框、按钮形式的多选框，适应不同的应用场景。
灵活的属性和事件：通过 v-model 绑定值，支持多选框和多选框组的状态管理，同时支持多种样式配置。
良好的交互体验：支持禁用、尺寸调整、最小/最大选择数量和自定义颜色，增强用户的交互体验。

编辑此页

上次更新: 2024/12/28, 18:32:08

← 单选框（Radio）输入框（Input）→