ui-form-checkbox-group 复选框组组件

版本：v2.3.11

复选框组容器组件，用于包裹多个 ui-form-checkbox-bar 子组件，统一管理选中值，支持最小/最大选中数量限制

基本使用

<template>
  <view class="checkbox-group-demo">
    <ui-form-checkbox-group v-model="selectedValues">
      <ui-form-checkbox-bar label="选项1" value="1" />
      <ui-form-checkbox-bar label="选项2" value="2" />
      <ui-form-checkbox-bar label="选项3" value="3" />
    </ui-form-checkbox-group>
    <text>选中值：{{ selectedValues }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const selectedValues = ref([])
</script>

<style scoped>
.checkbox-group-demo {
  padding: 20px;
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>

Props

参数	类型	默认值	说明
size	String	''	尺寸，可选值：''、mini、xs、sm、lg，会传递给子组件
modelValue	String/Object/Number/Boolean/Array	{}	绑定值（v-model），通常为选中 label 值的数组
disabled	Boolean	false	是否禁用所有子复选框
min	String/Number	null	最小选中数量
max	String/Number	null	最大选中数量

Events

事件名	说明	回调参数
change	选中值变化时触发	(value: Array) 当前选中的值数组

Slots

名称	说明
default	放置 ui-form-checkbox-bar 子组件

示例

限制选中数量

<template>
  <view class="checkbox-group-limit-demo">
    <ui-form-checkbox-group v-model="selectedValues" :min="1" :max="3">
      <ui-form-checkbox-bar label="选项1" value="1" />
      <ui-form-checkbox-bar label="选项2" value="2" />
      <ui-form-checkbox-bar label="选项3" value="3" />
      <ui-form-checkbox-bar label="选项4" value="4" />
      <ui-form-checkbox-bar label="选项5" value="5" />
    </ui-form-checkbox-group>
    <text>选中值：{{ selectedValues }}（至少选1项，最多选3项）</text>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const selectedValues = ref([])
</script>

统一设置尺寸和禁用

<template>
  <view class="checkbox-group-size-demo">
    <ui-form-checkbox-group v-model="selectedValues" size="sm">
      <ui-form-checkbox-bar label="小尺寸1" value="1" />
      <ui-form-checkbox-bar label="小尺寸2" value="2" />
    </ui-form-checkbox-group>

    <ui-form-checkbox-group v-model="disabledValues" disabled>
      <ui-form-checkbox-bar label="禁用1" value="1" />
      <ui-form-checkbox-bar label="禁用2" value="2" />
    </ui-form-checkbox-group>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const selectedValues = ref([])
const disabledValues = ref(['1'])
</script>

平台兼容

平台	支持情况
H5	✅
微信小程序	✅
支付宝小程序	✅
百度小程序	✅
字节跳动小程序	✅
QQ小程序	✅
APP	✅

注意事项

1. 子组件需使用 ui-form-checkbox-bar，通过 provide/inject 机制通信
2. size 和 disabled 属性会自动传递给子组件
3. min 和 max 限制在用户交互时生效，程序设置值不受限制
4. modelValue 通常为选中 label 值的数组