uView Next
4.0.105

外观

Checkbox 复选框

约 1683 字大约 6 分钟

2025-10-31

Checkbox 复选框组件是用于用户进行多选操作的表单控件，支持多种样式和交互方式。该组件具有高度的可定制性，可以满足各种多选场景的需求，包括选项筛选、协议确认、兴趣选择等。通过丰富的属性配置和事件支持，可以轻松实现美观且功能完善的多选界面。

基本使用

通过v-model绑定选中的值，通过placement设置排列方式。

<template>
	<un-checkbox-group v-model="checkboxValue1" placement="column" @change="checkboxChange">
		<un-checkbox 
			v-for="(item, index) in checkboxList1" 
			:key="index" 
			:label="item.name" 
			:name="item.name"
			:customStyle="{marginBottom: '8px'}" 
		/>
	</un-checkbox-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checkboxValue1 = ref<string[]>([])
const checkboxList1 = ref([
	{ name: '苹果', disabled: false },
	{ name: '香蕉', disabled: false },
	{ name: '橙子', disabled: false }
])

const checkboxChange = (n: string[]) => {
	console.log('change', n)
}
</script>

自定义图标

通过设置icon和activeIcon属性，自定义复选框的图标。

<template>
	<un-checkbox-group v-model="checkboxValue4" placement="column" @change="checkboxChange">
		<un-checkbox 
			:customStyle="{marginBottom: '8px'}" 
			v-for="(item, index) in checkboxList4" 
			:key="index" 
			:label="item.name" 
			:name="item.name"
			icon="star" 
			activeIcon="star-fill"
		/>
	</un-checkbox-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checkboxValue4 = ref<string[]>([])
const checkboxList4 = ref([
	{ name: '苹果', disabled: false },
	{ name: '香蕉', disabled: false },
	{ name: '橙子', disabled: false }
])

const checkboxChange = (n: string[]) => {
	console.log('change', n)
}
</script>

禁用状态

设置disabled为true，即可禁用某个组件，让用户无法点击。

<template>
	<un-checkbox-group v-model="checkboxValue2" placement="column" @change="checkboxChange">
		<un-checkbox 
			:customStyle="{marginBottom: '8px'}" 
			v-for="(item, index) in checkboxList2" 
			:key="index" 
			:label="item.name" 
			:name="item.name" 
			:disabled="item.disabled"
		/>
	</un-checkbox-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checkboxValue2 = ref<string[]>([])
const checkboxList2 = ref([
	{ name: '苹果', disabled: false },
	{ name: '香蕉', disabled: true },
	{ name: '橙子', disabled: false }
])

const checkboxChange = (n: string[]) => {
	console.log('change', n)
}
</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="checked">
		<un-checkbox activeColor="red" label="光影"></un-checkbox>
	</un-checkbox-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checked = ref<string[]>([])
</script>

独立使用

可以单独使用un-checkbox组件，通过v-model:checked绑定选中状态。

<template>
	<un-checkbox v-model:checked="checked">
		<view style="display: flex; flex-direction: row; align-items: center;">
			<text>我已经阅读并同意</text>
			<text style="color:#007AFF" @click.stop="handleClick">《用户协议》</text>
			<text>和</text>
			<text style="color:#007AFF" @click.stop="handleClick">《隐私政策》</text>
		</view>
	</un-checkbox>
</template>
<script setup lang="uts">
import { ref } from 'vue'

const checked = ref(false)

const handleClick = () => {
	uni.navigateTo({
		url: '/pages/componentsA/checkbox/checkbox'
	})
}
</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="checked" iconPlacement="right" 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>

API

Checkbox Props 属性

参数说明类型默认值
namecheckbox 的名称string | number | boolean-
shape形状，square 为方形，circle 为圆型，button 为按钮
Enum
square
size整体的大小string | number-
checked是否默认选中booleanfalse
indeterminate设置不确定状态，仅负责样式控制booleanfalse
disabled是否禁用string | boolean-
activeColor选中状态下的颜色，如设置此值，将会覆盖 parent 的 activeColor 值string-
inactiveColor未选中的颜色string-
iconSize图标的大小，单位 pxstring | number-
iconColor图标颜色string-
labellabel提示文字，因为nvue下，直接slot进来的文字，由于特殊的结构，无法修改样式string | number-
labelSizelabel的字体大小，px单位string | number-
labelColorlabel的颜色string-
labelDisabled是否禁止点击提示语选中复选框string | boolean-
activeLabelColor选中状态下label的颜色string-
plain镂空样式booleantrue
customStyle自定义样式object | string-

CheckboxGroup Props 属性

参数说明类型默认值
name标识符string-
v-model / modeValue / value绑定的值any[][]
shape形状，circle-圆形，square-方形, button为按钮
Enum
square
disabled是否禁用全部checkboxbooleanfalse
activeColor选中状态下的颜色，如子Checkbox组件设置此值，将会覆盖本值string#2979ff
inactiveColor未选中的颜色string#c8c9cc
size整个组件的尺寸，默认pxstring18
placement布局方式，row-横向，column-纵向
Enum
row
labelSizelabel的字体大小，px单位string | number14
labelColorlabel的字体颜色string#303133
labelDisabled是否禁止点击文本操作booleanfalse
icon图标string-
iconColor图标颜色string#ffffff
iconSize图标的大小，单位pxstring | number12
iconPlacement勾选图标的对齐方式，left-左边，right-右边
Enum
left
borderBottom竖向排列时，是否显示下划线booleanfalse
activeLabelColor选中状态下label的颜色string-
plain镂空样式booleantrue

Checkbox Slots 插槽

名称说明
default自定义label样式
icon自定义icon图标

Checkbox Event 事件

事件名说明类型
change复选框状态发生变化时触发
Function

CheckboxGroup Event 事件

事件名说明类型
change复选框组状态发生变化时触发
Function

Scss 变量

关于组件 SCSS 变量的用法，请参考 组件 SCSS 变量用法。

变量名默认值说明
$un-checkbox-label-border0.5px solid $border-color标签边框样式
$un-checkbox-icon-margin-right6px图标右边距
$un-checkbox-icon-border1px solid $border-color图标边框样式
$un-checkbox-icon-width18px图标宽度
$un-checkbox-icon-height18px图标高度
$un-checkbox-icon-checked-bg-color$color-primary选中图标背景颜色
$un-checkbox-icon-checked-border1px solid $color-primary选中图标边框样式
$un-checkbox-icon-disabled-bg-color$bg-color-disabled禁用图标背景颜色
$un-checkbox-icon-disabled-border1px solid $border-color禁用图标边框样式
$un-checkbox-icon-circle-radius$radius-circle圆形图标圆角
$un-checkbox-icon-square-radius$radius-sm方形图标圆角
$un-checkbox-button-padding5px 15px按钮内边距
$un-checkbox-button-border1px solid $border-color按钮边框样式
$un-checkbox-button-radius$radius-circle按钮圆角
$un-checkbox-button-checked-bg-color$color-primary选中按钮背景颜色
$un-checkbox-button-checked-border1px solid $color-primary选中按钮边框样式
$un-checkbox-label-text-font-size$text-base标签字体大小
$un-checkbox-label-text-color$text-color标签颜色
$un-checkbox-label-disabled-color$bg-color-disabled禁用标签颜色

Copyright © 2026 uView Next