当前位置：首页 > news >正文

uniapp中组件库的Checkbox 复选框的丰富使用方法

news 2025/8/21 1:58:37

#平台差异说明

#基本使用

#自定义形状

#禁用checkbox

#自定义形状

#自定义颜色

#横向排列形式

#横向两端排列形式

API

#Checkbox Props

#CheckboxGroup Props

#CheckboxGroup Event

复选框组件一般用于需要多个选择的场景，该组件功能完整，使用方便

#平台差异说明

App（vue）	App（nvue）	H5	小程序
√	√	√	√

#基本使用

<template><view><u-checkbox-groupv-model="checkboxValue1"placement="column"@change="checkboxChange"><u-checkbox:customStyle="{marginBottom: '8px'}"v-for="(item, index) in checkboxList1":key="index":label="item.name":name="item.name"></u-checkbox></u-checkbox-group></view>
</template>
<script>
export default {data() {return {checkboxValue1:[],// 基本案列数据checkboxList1: [{name: '苹果',disabled: false},{name: '香蕉',disabled: false},{name: '橙子',disabled: false}],}},methods: {checkboxChange(n) {console.log('change', n);}}
}
</script>

copy

#自定义形状

通过shape可以设置选择形状

<template><view><u-checkbox-groupv-model="checkboxValue1"placement="column"@change="checkboxChange"><u-checkbox:customStyle="{marginBottom: '8px'}"v-for="(item, index) in checkboxList1":key="index":label="item.name":name="item.name"></u-checkbox></u-checkbox-group></view>
</template>
<script>
export default {data() {return {checkboxValue1:[],// 基本案列数据checkboxList1: [{name: '苹果',disabled: false},{name: '香蕉',disabled: false},{name: '橙子',disabled: false}],}},methods: {checkboxChange(n) {console.log('change', n);}}
}
</script>

copy

#禁用checkbox

设置disabled为true，即可禁用某个组件，让用户无法点击，禁用分为两种状态，一是未勾选前禁用，这时只显示一个灰色的区域。二是已勾选后再禁用，会有灰色的已勾选的图标，但此时依然是不可操作的。

<template><view><u-checkbox-groupv-model="checkboxValue1"placement="column"@change="checkboxChange"><u-checkbox:customStyle="{marginBottom: '8px'}"v-for="(item, index) in checkboxList1":key="index":label="item.name":name="item.name":disabled="item.disabled"></u-checkbox></u-checkbox-group></view>
</template>
<script>
export default {data() {return {checkboxValue1:[],// 基本案列数据checkboxList1: [{name: '苹果',disabled: false},{name: '香蕉',disabled: false},{name: '橙子',disabled: true}],}},methods: {checkboxChange(n) {console.log('change', n);}}
}
</script>

copy

#自定义形状

可以通过设置shape为square或者circle，将复选框设置为方形或者圆形

<u-checkbox-group><u-checkbox v-model="checked" shape="circle" label="明月"></u-checkbox>
</u-checkbox-group>

copy

#自定义颜色

此处所指的颜色，为checkbox选中时的背景颜色，参数为activeColor

<u-checkbox-group v-model="checked"><u-checkbox  activeColor="red" label="光影"></u-checkbox>
</u-checkbox-group>

copy

#横向排列形式

可以通过设置placement为row或者column，将复选框设置为横向排列或者竖向排列

<u-checkbox-group v-model="checked" placement="row"><u-checkbox activeColor="red" label="红色"></u-checkbox><u-checkbox activeColor="green" label="绿色"></u-checkbox>
</u-checkbox-group>

copy

#横向两端排列形式

可以通过设置iconPlacement为left或者right，将复选框勾选图标的对齐设置为左对齐或者右对齐

<u-checkbox-group v-model="checked"iconPlacement="right" placement="row"><u-checkbox activeColor="red" label="红色"></u-checkbox><u-checkbox activeColor="green" label="绿色"></u-checkbox>
</u-checkbox-group>

API

#Checkbox Props

参数	说明	类型	默认值	可选值
name	checkbox的名称	String \ Number \ Boolean	-	-
shape	形状，square为方形，circle为圆型	String	square	circle
size	整体的大小	String \ Number	-	-
checked	是否默认选中	Boolean	false	true
disabled	是否禁用	String \ Boolean	-	-
activeColor	选中状态下的颜色，如设置此值，将会覆盖parent的activeColor值	String	-	-
inactiveColor	未选中的颜色	String	-	-
iconSize	图标的大小，单位px	String \ Number	-	-
iconColor	图标颜色	String	-	-
label	label提示文字，因为nvue下，直接slot进来的文字，由于特殊的结构，无法修改样式	String \ Number	-	-
labelSize	label的字体大小，px单位	String \ Number	-	-
labelColor	label的颜色	String	-	-
labelDisabled	是否禁止点击提示语选中复选框	String \ Boolean	-	-

#CheckboxGroup Props

参数	说明	类型	默认值	可选值
name	标识符	String	-	-
value	绑定的值	Array	[]	-
shape	形状，circle-圆形，square-方形	String	square	circle
disabled	是否禁用全部checkbox	Boolean	false	true
activeColor	选中状态下的颜色，如子`Checkbox`组件设置此值，将会覆盖本值	String	#2979ff	-
inactiveColor	未选中的颜色	String	#c8c9cc	-
size	整个组件的尺寸，默认px	String	18	-
placement	布局方式，row-横向，column-纵向	Boolean	row	column
labelSize	label的字体大小，px单位	String \ Number	14	-
labelColor	label的字体颜色	String	#303133	-
labelDisabled	是否禁止点击文本操作	Boolean	false	true
iconColor	图标颜色	String	#ffffff	-
iconSize	图标的大小，单位px	String \ Number	12	-
iconPlacement	勾选图标的对齐方式，left-左边，right-右边	String	left	right
borderBottom	竖向配列时，是否显示下划线	Boolean	false	true