rice-ui

暗黑模式

Checkbox 复选框 ​

手机扫码预览
01:50
组件名：rice-checkbox-group、rice-checkbox

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

平台兼容性 ​

uni-app x ​

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

基础用法 ​

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

html
<rice-checkbox v-model="value" label="复选框" @change="onChange"/>

<script setup>
const value=ref(false)
const onChange = (value:boolean) => {
  console.log('value',value)
}

</script>

复选框组 ​

复选框组通过 v-model 数组绑定复选框的勾选状态

html
<rice-checkbox-group v-model="values" @change="onGroupChange">
  <rice-checkbox value="apple" label="苹果"></rice-checkbox>
  <rice-checkbox value="banana" label="香蕉"></rice-checkbox>
  <rice-checkbox value="watermelon" label="西瓜"></rice-checkbox>
</rice-checkbox-group>

<script setup>
const values = ref(["apple"])
const onGroupChange = (values : string[]) => {
  console.log('values', values)
}
</script>

自定义颜色 ​

通过 checked-color 设置复选框选中状态下的颜色，Checkbox 中设置的颜色会覆盖 CheckboxGroup 中的值

html
<rice-checkbox-group v-model="values2" checked-color="#07c160">
  <rice-checkbox value="red" label="红色" checked-color="#f56c6c"></rice-checkbox>
  <rice-checkbox value="yellow" label="黄色" checked-color="#e6a23c"></rice-checkbox>
  <rice-checkbox value="green" label="绿色"></rice-checkbox>
</rice-checkbox-group>

禁用选项 ​

在 Checkbox 上 设置 disabled 属性可以禁用该复选框，在 CheckboxGroup 上设置 disabled 会禁用整个复选框

html
<rice-checkbox-group>
  <rice-checkbox value="a" label="好评"></rice-checkbox>
  <rice-checkbox value="b" label="还可以"></rice-checkbox>
  <rice-checkbox value="c" label="差评" disabled></rice-checkbox>
</rice-checkbox-group>

限制最大可选数量 ​

通过设置 max 属性可以设置最大可选数量，注意 max 只能为数字类型

html
<rice-checkbox-group v-model="valuesMax" :max="2">
  <rice-checkbox value="a" label="西游记"></rice-checkbox>
  <rice-checkbox value="b" label="水浒传"></rice-checkbox>
  <rice-checkbox value="c" label="三国演义"></rice-checkbox>
  <rice-checkbox value="d" label="红楼梦"></rice-checkbox>
</rice-checkbox-group>

左侧文本 ​

设置 icon-position 为 right 文本会显示在左侧，space-between 属性可以使图标和文本两端对齐

html
<rice-checkbox-group :model-value="['yes']" icon-position="right" space-between>
  <rice-checkbox value="yes" label="读书"></rice-checkbox>
  <rice-checkbox value="oh" label="看报"></rice-checkbox>
  <rice-checkbox value="no" label="睡大觉"></rice-checkbox>
</rice-checkbox-group>

水平排列 ​

设置 direction 为 row 即可水平排列

html
<rice-checkbox-group v-model="values" direction="row">
  <rice-checkbox value="apple" label="苹果"></rice-checkbox>
  <rice-checkbox value="banana" label="香蕉"></rice-checkbox>
  <rice-checkbox value="watermelon" label="西瓜"></rice-checkbox>
</rice-checkbox-group>

自定义图标 ​

可以通过插槽实现自定义图标，插槽会传递 checked 和 disabled 参数

html
<rice-checkbox-group v-model="values" direction="row">
  <rice-checkbox value="apple" label="苹果">
    <template #icon="{checked}">
      <rice-icon :name="checked?'like-fill':'like'" color="#ee0a24" size="22px" />
    </template>
  </rice-checkbox>
  <rice-checkbox value="banana" label="香蕉">
    <template #icon="{checked}">
      <rice-icon :name="checked?'like-fill':'like'" color="#ee0a24" size="22px" />
    </template>
  </rice-checkbox>
  <rice-checkbox value="watermelon" label="西瓜">
    <template #icon="{checked}">
      <rice-icon :name="checked?'like-fill':'like'" color="#ee0a24" size="22px" />
    </template>
  </rice-checkbox>
</rice-checkbox-group>

不确定状态 ​

通过 indeterminate 设置复选框是否为不确定状态

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

<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>

搭配单元格使用 ​

html
<rice-checkbox-group v-model="valuesCell" shape="round">
  <rice-cell-group radius="8px">
    <rice-cell v-for="item in 3" :key="item" :title="`复选框${item}`" center @click="toggle(item)">
      <template #rightIcon>
        <rice-checkbox :value="item" :custom-style="{marginBottom:'0px'}"></rice-checkbox>
      </template>
    </rice-cell>

  </rice-cell-group>
</rice-checkbox-group>

<script setup>
const valuesCell = ref<number[]>([])
const toggle = (item : number) => {
  const index = valuesCell.value.findIndex(v => v == item)
  if (index == -1) {
    valuesCell.value.push(item)
  } else {
    valuesCell.value.splice(index, 1)
  }
}
</script>

API ​

CheckboxGroup Props ​

参数说明类型默认值
v-model/model-value选中项绑定值Array<string|number|boolean>-
max最大可选数量，0 为不限制number-
disabled是否禁用整个 CheckboxGroupbooleanfalse
readonly是否只读booleanfalse
direction排列方向，可选 rowstringcol
checked-color选中状态下的颜色string-
icon-sizeicon的大小，单位支持 px和 rpxstring|number20px
label-color文字的颜色string-
label-size文字的大小，单位支持 px和 rpxstring|number15px
shape形状，可选 圆形：roundstringsquare
icon-position选择框的对齐方式，可选rightstringleft
space-between是否水平两端对齐，direction 为 row 时有效booleanfalse
customStyle自定义styleObject-

Checkbox Props ​

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

CheckboxGroup Events ​

事件名说明回调参数
change绑定值改变时触发value:Array<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 } from '@/uni_modules/rice-ui'
// 组件类型
const checkboxGroupRef = ref<RiceCheckboxGroupComponentPublicInstance | null>(null)
const checkboxRef = ref<RiceCheckboxComponentPublicInstance | null>(null)