uv-ui

# Checkbox 复选框

✈

组件名：uv-checkbox-group > uv-checkbox

点击下载&安装 (opens new window)

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

# 平台兼容性

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

# 基本使用

  • 该组件需要搭配checkboxGroup组件使用，以便用户进行操作时，获得当前复选框组的选中情况。
  • 通过v-model给checkboxGroup组件绑定一个变量，对应的name将会被选中。
<template>
	<view>
		<uv-checkbox-group v-model="checkboxValue">
			<uv-checkbox 
				:customStyle="{marginBottom: '8px'}" 
				v-for="(item, index) in checkboxList" 
				:key="index" :label="item.name" 
				:name="item.name"
			></uv-checkbox>
		</uv-checkbox-group>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				checkboxValue: ['苹果'],
				// 基本案列数据
				checkboxList: [{
					name: '苹果',
					disabled: false
				}, {
					name: '香蕉',
					disabled: false
				}, {
					name: '橙子',
					disabled: false
				}]
			}
		}
	}
</script>

# 自定义形状

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

<template>
	<view>
		<uv-checkbox-group 
			v-model="checkboxValue" 
			shape="circle">
			<uv-checkbox 
				:customStyle="{marginBottom: '8px'}" 
				v-for="(item, index) in checkboxList" 
				:key="index" :label="item.name" 
				:name="item.name"
			></uv-checkbox>
		</uv-checkbox-group>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				checkboxValue: ['苹果'],
				// 基本案列数据
				checkboxList: [{
					name: '苹果',
					disabled: false
				}, {
					name: '香蕉',
					disabled: false
				}, {
					name: '橙子',
					disabled: false
				}]
			}
		}
	}
</script>

# 禁用checkbox

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

<template>
	<view>
		<uv-checkbox-group 
			v-model="checkboxValue" 
			shape="circle">
			<uv-checkbox 
				:customStyle="{marginBottom: '8px'}" 
				v-for="(item, index) in checkboxList" 
				:key="index" :label="item.name" 
				:name="item.name"
				:disabled="index===0"
			></uv-checkbox>
		</uv-checkbox-group>
	</view>
</template>
<script>
	export default {
		data() {
			return {
				checkboxValue: ['苹果'],
				// 基本案列数据
				checkboxList: [{
					name: '苹果',
					disabled: false
				}, {
					name: '香蕉',
					disabled: false
				}, {
					name: '橙子',
					disabled: false
				}]
			}
		}
	}
</script>

# 自定义颜色

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

<template>
	<view>
		<uv-checkbox-group v-model="checkboxValue">
			<uv-checkbox activeColor="red" name="apple" label="苹果"></uv-checkbox>
		</uv-checkbox-group>
	</view>
</template>
<script>
	export default {
		data(){
			return {
				checkboxValue: ['apple']
			}
		}
	}
</script>

# 横向排列形式

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

<template>
	<view>
		<uv-checkbox-group v-model="checkboxValue" placement="column">
			<uv-checkbox name="apple" label="苹果"></uv-checkbox>
			<uv-checkbox name="banana" label="香蕉"></uv-checkbox>
		</uv-checkbox-group>
	</view>
</template>
<script>
	export default {
		data(){
			return {
				checkboxValue: ['apple']
			}
		}
	}
</script>

# 横向两端排列形式

在placement="column"前提下，可以通过设置iconPlacement为left或者right，将复选框勾选图标的对齐设置为左对齐或者右对齐。

<template>
	<view>
		<uv-checkbox-group 
			v-model="checkboxValue" 
			iconPlacement="right"
			placement="column">
			<uv-checkbox name="apple" label="苹果"></uv-checkbox>
			<uv-checkbox name="banana" label="香蕉"></uv-checkbox>
		</uv-checkbox-group>
	</view>
</template>
<script>
	export default {
		data(){
			return {
				checkboxValue: ['apple']
			}
		}
	}
</script>

# 完整示例

完整示例下载地址

https://ext.dcloud.net.cn/plugin?name=uv-ui (opens new window)

# API

# CheckboxGroup Props

参数 说明 类型 默认值 可选值
value / v-model 选中name的值，eg：['a','b'] Array [] -
value 绑定的值 Array [] -
shape 形状，circle-圆形，square-方形 String square square | circle
disabled 是否禁用全部checkbox Boolean false true | false
activeColor 选中状态下的颜色，如子Checkbox组件设置此值，将会覆盖本值 String #2979ff -
inactiveColor 未选中的颜色 String #c8c9cc -
size 整个组件的尺寸，默认px。注意：该参数和iconSize应该同步设置，才能改变选框大小 String 18 -
placement 布局方式，row-横向，column-纵向 String row row | column
labelSize label的字体大小，单位 px(rpx) String | Number 14 -
labelColor label的字体颜色 String #303133 -
labelDisabled 是否禁止点击文本操作 Boolean false true | false
iconColor 图标颜色 String #ffffff -
iconSize 图标的大小，单位 px(rpx) String | Number 12 -
iconPlacement 勾选图标的对齐方式，left-左边，right-右边 String left left | right
borderBottom 竖向配列时，是否显示下划线 Boolean false true | false
customStyle 自定义样式，某些事件需要用到调整位置等作用 Object - -

# Checkbox Props

注意：checkbox和checkbox-group二者同名参数中，checkbox的参数优先级更高。

参数 说明 类型 默认值 可选值
name checkbox的名称 String | Number | Boolean - -
shape 形状，square为方形，circle为圆型 String square square | circle
size 整体的大小 String | Number - -
checked 是否默认选中 Boolean false true | false
disabled 是否禁用 String | Boolean - -
activeColor 选中状态下的颜色，如设置此值，将会覆盖parent的activeColor值 String - -
inactiveColor 未选中的颜色 String - -
iconSize 图标的大小，单位px String | Number - -
iconColor 图标颜色 String - -
label label提示文字。如果文本较长存在文本不换行的问题，使用customStyle设置一个宽度即可，eg：customStyle="maxWidth: 300rpx;" String | Number - -
labelSize label的字体大小，px单位 String | Number - -
labelColor label的颜色 String - -
labelDisabled 是否禁止点击提示语选中复选框 String | Boolean - -
customStyle 自定义样式 Object | String - -

# Checkbox Slots

名称 说明
default 自定义label内容，自定义后，labelDisabled设置将会失效
icon 自定义选中图标

# CheckboxGroup Events

事件名 说明 回调参数
@change 任一个checkbox状态发生变化时触发，回调为一个对象 detail = array( [元素为被选中的checkbox的name] )

# Checkbox Events

事件名 说明 回调参数
@change 某个checkbox状态发生变化时触发(选中状态) name: 通过props传递的name参数

← Radio 单选框 →