xtf-checkbox-group

组件说明

xtf-checkbox-group 是复选框组容器组件，用于管理多个 xtf-checkbox 的选中值。支持 options 快速生成选项、方向布局、最大/最小选中数限制、变更拦截和全选/反选方法，是表单多选场景的核心组件。

基础用法

1. 最简示例

通过 v-model 绑定选中值数组，包裹 xtf-checkbox 并用 name 标识：

vue

<template>
  <xtf-checkbox-group v-model="selected" direction="column">
    <xtf-checkbox name="apple" label="苹果" />
    <xtf-checkbox name="banana" label="香蕉" />
    <xtf-checkbox name="orange" label="橙子" />
  </xtf-checkbox-group>
</template>

<script>
export default {
  data() {
    return {
      selected: ['apple']
    }
  }
}
</script>

2. Options 快速生成

通过 options 属性直接传入选项数组，无需手动写 xtf-checkbox：

vue

<template>
  <xtf-checkbox-group v-model="selected" :options="fruitOptions" direction="row" :gap="24" />
</template>

<script>
export default {
  data() {
    return {
      selected: ['apple'],
      fruitOptions: [
        { label: '苹果', value: 'apple' },
        { label: '香蕉', value: 'banana' },
        { label: '橙子', value: 'orange' },
        { label: '葡萄', value: 'grape', disabled: true }
      ]
    }
  }
}
</script>

3. 方向与间距

通过 direction 切换排列方向，通过 gap 调整间距：

vue

<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx">
    <xtf-text level="caption" color="secondary">水平排列</xtf-text>
    <xtf-checkbox-group v-model="h1" direction="row" :gap="32">
      <xtf-checkbox name="a" label="选项A" />
      <xtf-checkbox name="b" label="选项B" />
      <xtf-checkbox name="c" label="选项C" />
    </xtf-checkbox-group>

    <xtf-text level="caption" color="secondary">垂直排列</xtf-text>
    <xtf-checkbox-group v-model="h2" direction="column" :gap="16">
      <xtf-checkbox name="a" label="选项A" />
      <xtf-checkbox name="b" label="选项B" />
      <xtf-checkbox name="c" label="选项C" />
    </xtf-checkbox-group>
  </view>
</template>

<script>
export default {
  data() {
    return {
      h1: ['a'],
      h2: ['a']
    }
  }
}
</script>

4. 选中数限制与全选

通过 max / min 限制选中数量，通过 checkAll 方法实现全选/反选：

vue

<template>
  <view>
    <xtf-button-group :gap="12" style="margin-bottom: 16rpx">
      <xtf-button label="全选" size="sm" type="light" @click="selectAll" />
      <xtf-button label="反选" size="sm" type="light" @click="deselectAll" />
    </xtf-button-group>
    <xtf-checkbox-group ref="checkGroup" v-model="selected" :max="3" :min="1" direction="column">
      <xtf-checkbox name="reading" label="阅读" />
      <xtf-checkbox name="music" label="音乐" />
      <xtf-checkbox name="sports" label="运动" />
      <xtf-checkbox name="travel" label="旅行" />
      <xtf-checkbox name="cooking" label="烹饪" />
    </xtf-checkbox-group>
    <xtf-text level="caption" color="secondary">最多选3项，最少选1项</xtf-text>
  </view>
</template>

<script>
export default {
  data() {
    return {
      selected: ['reading']
    }
  },
  methods: {
    selectAll() {
      this.$refs.checkGroup.checkAll(true)
    },
    deselectAll() {
      this.$refs.checkGroup.checkAll(false)
    }
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`modelValue`	`Array`	`undefined`	绑定值（Vue 3）	双向绑定
`value`	`Array`	`[]`	绑定值（Vue 2）	双向绑定
`name`	`String`	`''`	表单字段名	表单提交
`options`	`Array`	`[]`	选项数组，支持字符串或 `{ label, value, disabled }` 对象	快速生成
`optionLabelKey`	`String`	`'label'`	选项文字字段名	自定义字段映射
`optionValueKey`	`String`	`'value'`	选项值字段名	自定义字段映射
`optionDisabledKey`	`String`	`'disabled'`	选项禁用字段名	自定义字段映射
`disabled`	`Boolean`	`false`	是否全局禁用	禁用交互
`theme`	`String`	`'primary'`	主题色	切换主题色
`color`	`String`	`''`	自定义颜色	自定义色
`activeColor`	`String`	`''`	选中时颜色	自定义选中色
`variant`	`String`	`'default'`	子复选框变体	统一视觉风格
`checkAnimation`	`String`	`'scale'`	子复选框勾选动画	统一动画
`iconSize`	`String \| Number`	`''`	子复选框图标大小	统一图标大小
`checkedIcon`	`String`	`''`	子复选框选中图标	统一选中图标
`uncheckedIcon`	`String`	`''`	子复选框未选图标	统一未选图标
`indeterminateIcon`	`String`	`''`	子复选框半选图标	统一半选图标
`size`	`String`	`'md'`	子复选框尺寸：`'sm'` / `'md'` / `'lg'`	统一大小
`shape`	`String`	`''`	子复选框形状	统一形状
`direction`	`String`	`'column'`	排列方向：`'column'` / `'row'`	控制方向
`gap`	`String \| Number`	`20`	子项间距（rpx）	调整间距
`max`	`String \| Number`	`0`	最大选中数，0 不限制	限制选中数
`min`	`String \| Number`	`0`	最小选中数，0 不限制	限制选中数
`beforeChange`	`Function`	`null`	变更拦截函数	变更拦截
`customClass`	`String`	`''`	自定义类名	样式覆盖
`customStyle`	`String \| Object`	`''`	自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`change`	选中值变更时触发	`(value: Array)`	新的选中值数组
`input`	Vue 2 双向绑定更新	`(value: Array)`	新的选中值数组
`update:modelValue`	Vue 3 双向绑定更新	`(value: Array)`	新的选中值数组

事件使用示例

vue

<template>
  <xtf-checkbox-group v-model="selected" :options="options" @input="onInput" @change="onChange" />
</template>

<script>
export default {
  data() {
    return { selected: [], options: [{ label: '阅读', value: 'reading' }] }
  },
  methods: {
    onInput(value) {
      console.log('绑定值', value)
    },
    onChange(value) {
      console.log('已选择', value)
    }
  }
}
</script>

插槽

插槽名	说明
默认插槽	未提供 `options` 时，放置 `xtf-checkbox` 子组件。

方法

方法名	参数	返回值	说明
`checkAll`	`(checked: Boolean, values?: Array)`	`Promise<Boolean>`	全选或反选，可指定特定值列表
`updateValue`	`(optionValue, checked: Boolean)`	`Promise<Boolean>`	手动更新某个选项的选中状态

主题说明

子项间距使用 --xtf-checkbox-group-gap
方向布局通过 flex-direction 控制

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

xtf-checkbox-group ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. Options 快速生成 ​

3. 方向与间距 ​

4. 选中数限制与全选 ​

全部属性 ​

事件 ​

事件使用示例 ​

插槽 ​

方法 ​

主题说明 ​