rice-ui

暗黑模式

Checkbox 复选框 ​

点击扫码预览
23:47
组件名：rice-checkbox-group、rice-checkbox
演示示例可扫模拟器状态栏上的二维码预览或 点击在线预览

在一组备选项中进行多选。

平台兼容性 ​

uni-app x ​

AndroidiOS鸿蒙Next微信小程序h5
√√√√√

基础用法 ​

通过 v-model 绑定变量，选中意味着变量的值为对应 Checkbox value 属性的值。

vue
<template>
  <rice-checkbox-group v-model="checked" custom-class="demo-checkbox-group" @change="onChange">
    <rice-checkbox label="苹果" value="apple" />
    <rice-checkbox label="香蕉" value="banner" />
    <rice-checkbox label="榴莲" value="durian" />
    <rice-checkbox label="西瓜" value="watermelon" />
  </rice-checkbox-group>
</template>

<script setup>
  const checked = ref(["apple"])
  const onChange = (value : string[]) => {
    console.log('value', value)
  }
</script>
css
<style scoped lang="scss">
	.demo-checkbox-group {
		padding: 16px 16px 6px;
		background-color: #fff;

		.rice-checkbox {
			margin-bottom: 10px;
		}
	}
</style>

水平排列 ​

将 direction 属性设置为 horizontal 后，多选框组会变成水平排列。

html
<rice-checkbox-group v-model="checked" direction="horizontal">
  <rice-checkbox label="苹果" value="apple"/>
  <rice-checkbox label="香蕉" value="banner"/>
  <rice-checkbox label="榴莲" value="durian"/>
  <rice-checkbox label="西瓜" value="watermelon"/>
</rice-checkbox-group>

最大可选数量 ​

通过 max 属性可以限制复选框组的最大可选数。

html
<rice-checkbox-group v-model="checked" :max="2">
  <rice-checkbox label="苹果" value="apple"/>
  <rice-checkbox label="香蕉" value="banner"/>
  <rice-checkbox label="榴莲" value="durian"/>
  <rice-checkbox label="西瓜" value="watermelon"/>
</rice-checkbox-group>

自定义形状 ​

shape 属性可选值为 circle 圆形。

html
<rice-checkbox-group v-model="checked" shape="circle">
  <rice-checkbox label="苹果" value="apple" />
  <rice-checkbox label="香蕉" value="banner" />
  <rice-checkbox label="榴莲" value="durian" />
  <rice-checkbox label="西瓜" value="watermelon" />
</rice-checkbox-group>

自定义颜色 ​

通过 active-color 修改 Checkbox 选中时的背景颜色。

html
<rice-checkbox-group v-model="checked4" active-color="#ff4d4f" :custom-class="customClass">
  <rice-checkbox label="苹果" value="apple" />
  <rice-checkbox label="香蕉" value="banner" />
  <rice-checkbox label="榴莲" value="durian" />
  <rice-checkbox label="西瓜" value="watermelon" active-color="#e6a23c" />
</rice-checkbox-group>

自定义图标 ​

通过 icon 插槽可以自定义图标，并通过 checked 判断是否为选择状态，disabled 判断是否为禁用状态。

html
<rice-checkbox-group v-model="checked" :custom-class="customClass">
  <rice-checkbox label="苹果" value="apple">
    <template #icon="{checked}">
      <image v-if="checked" src="/static/images/apple-select.png" class="icon-img"></image>
      <image v-else src="/static/images/apple-normal.png" class="icon-img"></image>
    </template>
  </rice-checkbox>
  <rice-checkbox label="香蕉" value="banner">
    <template #icon="{checked}">
      <image v-if="checked" src="/static/images/banner-select.png" class="icon-img"></image>
      <image v-else src="/static/images/banner-normal.png" class="icon-img"></image>
    </template>
  </rice-checkbox>
  <rice-checkbox label="榴莲" value="durian">
    <template #icon="{checked,disabled}">
      <image v-if="checked" src="/static/images/durian-select.png" class="icon-img"></image>
      <image v-else src="/static/images/durian-normal.png" class="icon-img"></image>
    </template>
  </rice-checkbox>
</rice-checkbox-group>

水平两端对齐 ​

在 direction 为 vertical 的前提下，可以通过设置 space-between 为 true ，让 Checkbox 水平两端对齐。可以通过设置 icon-position 为 left 或 right，将选择框的位置设置为左边或右边。

html
<rice-checkbox-group v-model="checked" space-between icon-position="right">
  <rice-checkbox label="苹果" value="apple" />
  <rice-checkbox label="香蕉" value="banner" />
  <rice-checkbox label="榴莲" value="durian" />
  <rice-checkbox label="西瓜" value="watermelon" />
</rice-checkbox-group>

禁用状态 ​

将 disabled 设置为 true，即可禁用 Checkbox 。

html
<rice-checkbox-group v-model="checked" disabled>
  <rice-checkbox label="苹果" value="apple" />
  <rice-checkbox label="香蕉" value="banner" />
  <rice-checkbox label="榴莲" value="durian" />
  <rice-checkbox label="西瓜" value="watermelon" />
</rice-checkbox-group>

不确定状态 ​

将 Checkbox 的 indeterminate 属性设置为 true 用以表示不确定状态，一般用于实现全选的效果。

vue
<template>
  <rice-checkbox v-model="isCheckAll" :indeterminate="isIndeterminate" :label="`${isCheckAll?'取消全选':'全选'}`" :custom-style="{marginBottom:'16px'}"  @change="checkAllChange" />
  <rice-checkbox-group v-model="checkedIndeter" direction="horizontal" @change="onIndeterminateChange">
    <rice-checkbox v-for="item in list" :key="item" :value="item" :label="item" />
  </rice-checkbox-group>
</template>

<script setup>
  const isCheckAll = ref(false)
  const isIndeterminate = ref(true)
  const checkedIndeter = ref<string[]>(['香蕉'])
  const list = ref<string[]>(['苹果', '香蕉', '榴莲', '西瓜'])

  const checkAllChange = (value : boolean) => {
    checkedIndeter.value = value ? list.value : [];
    isIndeterminate.value = false
  }

  const onIndeterminateChange = (value : string[]) => {
    const checkedCount = value.length
    isCheckAll.value = checkedCount == list.value.length
    isIndeterminate.value = checkedCount > 0 && checkedCount < list.value.length
  }
</script>

单独使用 ​

Checkbox 支持单独使用，一般用于勾选是否同意某项协议。

vue
<template>
  <rice-checkbox v-model="isAgree" :label="`我已经阅读并且同意某某协议（当前${isAgree?'已':'未'}同意）`" />
  <!-- 协议2 -->
  <rice-checkbox v-model="isAgree2" active-value="yes" inactive-value="no" @change="agreementChange">
    <view class="slot-label">
      <text class="slot-label-text" :style="{color:'#409eff'}" @click="agreementClick">点击可查看协议内容，</text>
      <text class="slot-label-text">当前值为 {{isAgree2}}</text>
    </view>
  </rice-checkbox>
</template>

<script setup>
  const isAgree = ref(false);
  const isAgree2 = ref('yes');

  const agreementClick = (e : UniPointerEvent) => {
    //点击查看协议的时候阻止冒泡
    e.stopPropagation()
    uni.showToast({
      title: '点击了查看协议',
      icon: 'none'
    })
  }

  const agreementChange = (value : string) => {
    console.log('value',value)
  }
</script>

API ​

CheckboxGroup Props ​

参数说明类型默认值
v-model选中项绑定值Array<string|number|boolean>-
max最大可选数量，0 为不限制number-
disabled是否禁用整个 CheckboxGroupbooleanfalse
readonly是否只读booleanfalse
direction排列方向，可选 horizontalstringvertical
activeColor选中状态下的颜色string-
iconSizeicon的大小，单位支持 px和 rpxstring|number20px
labelColor文字的颜色string-
labelSize文字的大小，单位支持 px和 rpxstring|number15px
shape形状，可选 方形：squarestringsquare
iconPosition选择框的对齐方式，可选rightstringleft
spaceBetween是否水平两端对齐，direction 为 vertical 时有效booleanfalse
customClass自定义classstring-
customStyle自定义styleObject-

Checkbox Props ​

参数说明类型默认值
v-model选中项绑定值，单独使用Checkbox时该属性才有意义string|number|boolean-
value多选框的值string|number|boolean-
label多选框的文字string|number\-
activeValue选中时的值，单独使用Checkbox时该属性才有意义string|number|booleantrue
inactiveValue未选中时的值，单独使用Checkbox时该属性才有意义string|number|booleanfalse
indeterminate是否为不确定状态，仅负责样式控制booleanfalse
disabled是否禁用booleanfalse
readonly是否只读booleanfalse
activeColor选中状态下的颜色，如设置此值，将会覆盖CheckboxGroup的activeColor值string-
iconSizeicon的大小，单位支持 px和 rpx，如设置此值，将会覆盖CheckboxGroup的iconSize值string|number20px
labelColor文字的颜色，如设置此值，将会覆盖CheckboxGroup的labelColor值string-
labelSize文字的大小，单位支持 px和 rpx，如设置此值，将会覆盖CheckboxGroup的labelSize值string|number15px
shape形状，可选 方形：square，如设置此值，将会覆盖CheckboxGroup的shape值stringsquare
iconPosition选择框的对齐方式，可选right，如设置此值，将会覆盖CheckboxGroup的iconPosition值stringleft
spaceBetween是否水平两端对齐，direction 为 vertical 时有效，如设置此值，将会覆盖CheckboxGroup的spaceBetween值booleanfalse
customClass自定义classstring-
customStyle自定义styleObject-

CheckboxGroup Events ​

事件名说明回调参数
change绑定值改变时触发value:(string|number|boolean)[]

Checkbox Events ​

事件名说明回调参数
change绑定值改变时触发value:(string|number|boolean)[]

Checkbox Slots ​

名称说明参数
default自定义文本{ checked : boolean, disabled : boolean }
icon自定义图标{ checked : boolean, disabled : boolean }

类型定义 ​

组件导出如下类型

ts
import { CheckboxDirection, CheckboxShape, CheckboxIconPosition, CheckboxValueType, CheckboxProps, CheckboxGroupProps } from '@/uni_modules/rice-ui'
// 组件类型
const checkboxGroupRef = ref<RiceCheckboxGroupComponentPublicInstance | null>(null)
const checkboxRef = ref<RiceCheckboxComponentPublicInstance | null>(null)