外观
Checkbox 复选框
约 2515 字大约 8 分钟
2025-10-31
Checkbox 复选框组件是用于用户进行多选操作的表单控件，支持多种样式和交互方式。该组件具有高度的可定制性，可以满足各种多选场景的需求，包括选项筛选、协议确认、兴趣选择等。通过丰富的属性配置和事件支持，可以轻松实现美观且功能完善的多选界面。
基本使用
通过v-model绑定选中的值。
<template>
<un-checkbox-group v-model="checkboxValueCity">
<un-checkbox v-for="(item, index) in checkboxListCity" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
// 基本案例数据 - 城市
const checkboxListCity = ref<CheckboxItem[]>([
{ name: '苹果' },
{ name: '香蕉' },
{ name: '橙子' },
{ name: '草莓' },
{ name: '葡萄' },
{ name: '西瓜' },
{ name: '猕猴桃' }
]);
const checkboxValueCity = ref<string[]>(['苹果', '橙子']);
</script>圆点样式 v4.1.0
通过设置shape为circle，可以将复选框设置为圆点样式。
<template>
<un-checkbox-group v-model="checkboxValueDot" shape="circle">
<un-checkbox v-for="(item, index) in checkboxListDot" :key="index" :label="item.name" :name="item.name">
</un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
// 圆点样式数据 - 节日
const checkboxListDot = ref<CheckboxItem[]>([
{ name: '春节' },
{ name: '元宵节' },
{ name: '清明节' },
{ name: '端午节' },
{ name: '中秋节' },
{ name: '国庆节' }
]);
const checkboxValueDot = ref<string[]>(['春节']);
</script>勾选样式 v4.1.0
通过设置shape为check，可以将复选框设置为勾选样式。
<template>
<un-checkbox-group v-model="checkboxValueCheck" shape="check">
<un-checkbox v-for="(item, index) in checkboxListCheck" :key="index" :label="item.name" :name="item.name">
</un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
// 勾选样式数据 - 音乐类型
const checkboxListCheck = ref<CheckboxItem[]>([
{ name: '流行音乐' },
{ name: '摇滚音乐' },
{ name: '古典音乐' },
{ name: '爵士音乐' },
{ name: '电子音乐' },
{ name: '民谣音乐' },
{ name: '嘻哈音乐' }
]);
const checkboxValueCheck = ref<string[]>(['流行音乐']);
</script>按钮样式 v4.1.0
通过设置shape为button，可以将复选框设置为按钮样式。
<template>
<un-checkbox-group v-model="checkboxValueButton" shape="button">
<un-checkbox v-for="(item, index) in checkboxListButton" :key="index" :label="item.name" :name="item.name">
</un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
// 按钮样式数据 - 游戏类型
const checkboxListButton = ref<CheckboxItem[]>([
{ name: '动作游戏' },
{ name: '角色扮演' },
{ name: '射击游戏' },
{ name: '策略游戏' },
{ name: '模拟经营' },
{ name: '体育游戏' },
{ name: '解谜游戏' }
]);
const checkboxValueButton = ref<string[]>(['动作游戏']);
</script>禁用状态
通过设置disabled属性为true，可以禁用复选框，使其无法被点击。
<template>
<un-checkbox-group v-model="checkboxValueDisabled" :disabled="disabled">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueDisabled" :disabled="disabled" shape="square">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueDisabled" :disabled="disabled" shape="circle">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueDisabled" :disabled="disabled" shape="button">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
// 纵向排列案例
const checkboxListDisabled = ref<CheckboxItem[]>([
{ name: '自行车' },
{ name: '电动车' },
{ name: '汽车' },
{ name: '火车' },
{ name: '飞机' },
]);
const checkboxValueDisabled = ref<string[]>(['自行车']);
const disabled = ref<boolean>(false);
setTimeout(() => {
disabled.value = true;
}, 1000);
</script>自定义形状
通过设置shape为square、circle或button，将复选框设置为方形、圆形或按钮样式。
<template>
<un-checkbox-group v-model="checkboxValue3" placement="column" @change="checkboxChange">
<un-checkbox
:customStyle="{marginBottom: '8px'}"
v-for="(item, index) in checkboxList3"
:key="index"
:label="item.name"
:name="item.name"
shape="square"
/>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue'
const checkboxValue3 = ref<string[]>([])
const checkboxList3 = ref([
{ name: '苹果', disabled: false },
{ name: '香蕉', disabled: false },
{ name: '橙子', disabled: false }
])
const checkboxChange = (n: string[]) => {
console.log('change', n)
}
</script>自定义颜色
通过activeColor属性可以设置复选框选中时的颜色。
<template>
<un-checkbox-group v-model="checkboxValueCustom" activeColor="#19be6b">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueCustom" shape="square" activeColor="#19be6b">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueCustom" shape="circle" activeColor="#19be6b">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueCustom" shape="button" activeColor="#19be6b">
<un-checkbox v-for="(item, index) in checkboxListDisabled" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
// 纵向排列案例
const checkboxListDisabled = ref<CheckboxItem[]>([
{ name: '自行车' },
{ name: '电动车' },
{ name: '汽车' },
{ name: '火车' },
{ name: '飞机' },
]);
const checkboxValueCustom = ref<string[]>(['自行车']);
</script>使用插槽自定义图标
通过插槽可以自定义复选框的图标和内容，实现更加个性化的效果。
<template>
<un-checkbox-group v-model="checkboxValueCustom">
<un-checkbox label="男" name="man">
<template #icon="{ checked }">
<un-icon type="primary" name="man" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
</template>
</un-checkbox>
<un-checkbox label="女" name="woman">
<template #icon="{ checked }">
<un-icon type="primary" name="woman" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
</template>
</un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueCustom" shape="button">
<un-checkbox name="man">
<template #default="{ checked }">
<un-icon type="primary" name="man" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
<text style="font-size: 14px;margin-left: 5px;">男</text>
</template>
</un-checkbox>
<un-checkbox name="woman">
<template #default="{ checked }">
<un-icon type="primary" name="woman" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
<text style="font-size: 14px;margin-left: 5px;">女</text>
</template>
</un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
const checkboxValueCustom = ref<string[]>(['自行车']);
</script>独立使用
可以单独使用un-checkbox组件，通过v-model:checked绑定选中状态。
<template>
<un-checkbox v-model:checked="checkboxValueSingle">
<view style="display: flex; flex-direction: row; align-items: center;">
<text>我已经阅读并同意</text>
<text style="color:#007AFF">《用户协议》</text>
<text>和</text>
<text style="color:#007AFF">《隐私政策》</text>
</view>
</un-checkbox>
<view>
状态：{{checkboxValueSingle}}
</view>
</template>
<script setup lang="uts">
import { ref } from 'vue';
// 独立使用的复选框状态
const checkboxValueSingle = ref<boolean>(true);
</script>中间状态
通过设置indeterminate属性，可以实现复选框的中间状态。
<template>
<un-checkbox :indeterminate="isIndeterminate" v-model:checked="checkboxValueSingle" label="全选"></un-checkbox>
</template>
<script setup lang="uts">
import { ref } from 'vue';
// 独立使用的复选框状态
const checkboxValueSingle = ref<boolean>(true);
// 中间状态
const isIndeterminate = ref<boolean>(true);
</script>纵向排列
通过设置direction为column，可以将复选框设置为纵向排列。
<template>
<un-checkbox-group v-model="checkboxValueColumn" direction="column">
<un-checkbox v-for="(item, index) in checkboxListColumn" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueColumn" direction="column" shape="square">
<un-checkbox v-for="(item, index) in checkboxListColumn" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueColumn" direction="column" shape="circle">
<un-checkbox v-for="(item, index) in checkboxListColumn" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueColumn" direction="column" shape="button">
<un-checkbox v-for="(item, index) in checkboxListColumn" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
// 纵向排列案例
const checkboxListColumn = ref<CheckboxItem[]>([
{ name: '自行车' },
{ name: '电动车' },
{ name: '汽车' },
{ name: '火车' },
{ name: '飞机' },
]);
const checkboxValueColumn = ref<string[]>(['自行车']);
</script>横向排列
通过设置placement为row，将复选框设置为横向排列。
<template>
<un-checkbox-group v-model="checked" placement="row">
<un-checkbox activeColor="red" label="红色"></un-checkbox>
<un-checkbox activeColor="green" label="绿色"></un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue'
const checked = ref<string[]>([])
</script>横向两端排列
通过设置iconPlacement为right，可以将复选框的图标放在右侧，实现横向两端排列的效果。
<template>
<un-checkbox-group v-model="checkboxValueIconRight" iconPlacement="right">
<un-checkbox v-for="(item, index) in checkboxListIconRight" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueIconRight" shape="square" iconPlacement="right">
<un-checkbox v-for="(item, index) in checkboxListIconRight" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueIconRight" shape="circle" iconPlacement="right">
<un-checkbox v-for="(item, index) in checkboxListIconRight" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
<un-checkbox-group v-model="checkboxValueIconRight" shape="button" iconPlacement="right">
<un-checkbox v-for="(item, index) in checkboxListIconRight" :key="index" :label="item.name" :name="item.name"></un-checkbox>
</un-checkbox-group>
</template>
<script setup lang="uts">
import { ref } from 'vue';
type CheckboxItem = {
name: string;
desc?: string;
};
const checkboxListIconRight = ref<CheckboxItem[]>([
{ name: '男' },
{ name: '女' },
]);
const checkboxValueIconRight = ref<string[]>(['男']);
</script>API
Checkbox Props 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | checkbox 的名称 | string | number | boolean | - |
| shape | 外观形状 | Enum | square |
| checked | 是否默认选中 | boolean | false |
| indeterminate | 设置不确定状态，仅负责样式控制 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| activeColor | 选中状态下的颜色，如设置此值，将会覆盖 parent 的 activeColor 值 | string | - |
| inactiveColor | 未选中的颜色 | string | - |
| icon | 图标 | string | - |
| iconSize | 图标的大小，单位 px | string | number | - |
| iconColor | 图标颜色 | string | - |
| label | label提示文字，因为nvue下，直接slot进来的文字，由于特殊的结构，无法修改样式 | string | number | - |
| labelSize | label的字体大小，px单位 | string | number | - |
| labelColor | label的颜色 | string | - |
| labelDisabled | 是否禁止点击提示语选中复选框 | boolean | false |
| activeLabelColor | 选中状态下label的颜色 | string | - |
| iconPlacement | 图标与文字的对齐方式 | string | - |
| customStyle | 自定义样式 | object | string | '' |
CheckboxGroup Props 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标识符 | string | - |
| v-model / modelValue | 绑定的值 | Array<string | number> | [] |
| shape | 外观形状 | Enum | square |
| disabled | 是否禁用全部checkbox | boolean | false |
| activeColor | 选中状态下的颜色，如子Checkbox组件设置此值，将会覆盖本值 | string | - |
| inactiveColor | 未选中的颜色 | string | - |
| size | 整个组件的尺寸，单位px | string | number | 20 |
| placement | 布局方式，row-横向，column-纵向 | Enum | row |
| label | label的文本 | string | - |
| labelSize | label的字体大小，px单位 | string | number | - |
| labelColor | label的颜色 | string | - |
| labelDisabled | 是否禁止点击文本操作checkbox | boolean | false |
| iconColor | 图标颜色 | string | - |
| iconSize | 图标的大小，单位px | string | number | - |
| iconPlacement | 图标与文字的对齐方式 | string | left |
| borderBottom | 竖向配列时，是否显示下划线 | boolean | false |
| activeLabelColor | 选中状态下label的颜色 | string | - |
| plain | 是否镂空 | boolean | true |
Checkbox Slots 插槽
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义label样式 | checked: boolean（是否选中） |
| icon | 自定义icon图标 | checked: boolean（是否选中） |
Checkbox Event 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 复选框状态发生变化时触发 | Function |
| update:checked | 复选框状态发生变化时触发（v-model:checked双向绑定） | Function |
CheckboxGroup Event 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 任一个checkbox状态发生变化时触发 | Function |
| update:modelValue | 复选框组状态发生变化时触发（v-model双向绑定） | Function |