复选框组件

checkbox 组件是 Uniapp 中用于实现复选框功能的基础组件。通过 checkbox-group 和 checkbox 组件的组合，可以实现一组复选框的选择功能，用户可以选择多个选项。checkbox 组件具有丰富的属性配置，支持自定义颜色、禁用状态、默认选中等。它也支持跨平台的样式和交互行为。

1. 什么是 checkbox 组件？

checkbox 组件用于实现多选功能。用户可以通过复选框选择多个选项，并将选中的值通过事件返回给开发者。复选框通常与 checkbox-group 组件一起使用，checkbox-group 用于包裹一组复选框并管理它们的状态。

使用场景

• 表单选择：允许用户在多个选项中选择一到多个值，常用于表单中的多选题。
• 过滤功能：用于商品筛选、内容过滤等功能，用户可以通过复选框选择多个条件进行过滤。
• 配置设置：用于在设置页面中启用或禁用多项配置。

2. checkbox-group 组件的常用属性

checkbox-group 组件用于包裹多个 checkbox 复选框，统一管理它们的状态。当复选框的状态发生变化时，会触发 change 事件，并返回选中的复选框值。

属性名	类型	默认值	说明
@change	EventHandle		当选中项发生变化时触发 change 事件，事件参数 detail 返回一个对象 {value: [选中的 checkbox 的 value]}

2.1 @change 事件

• 说明：当 checkbox-group 中的复选框选中项发生变化时，会触发 @change 事件。事件参数会返回一个包含所有选中复选框的 value 数组。
• 类型：EventHandle

<template>
  <view>
    <!-- checkbox-group 组件包裹一组复选框 -->
    <checkbox-group @change="onCheckboxChange">
      <label>
        <!-- 单个 checkbox 复选框 -->
        <checkbox value="option1" checked /> 选中
      </label>
      <label>
        <checkbox value="option2" /> 未选中
      </label>
    </checkbox-group>
  </view>
</template>

<script setup>
const onCheckboxChange = (e) => {
  // 获取选中的复选框值
  console.log('选中的值:', e.detail.value);
};
</script>

3. checkbox 组件的常用属性

checkbox 组件是复选框的核心部分，通过配置属性控制其选中状态、禁用状态、颜色等效果。它也支持跨平台的样式自定义，如颜色、大小等。

属性名	类型	默认值	说明	平台差异说明
value	String		checkbox 的标识值，选中时会触发 checkbox-group 的 change 事件，并携带该 checkbox 的 value。
disabled	Boolean	false	是否禁用复选框，禁用后复选框无法被点击。
checked	Boolean	false	当前复选框是否选中。可以用于设置默认选中状态。
color	Color		复选框的颜色，同 css 的 color 属性，用于自定义复选框的颜色。
backgroundColor	Color	#ffffff	复选框默认的背景颜色。	H5(3.99+)、App-Vue(3.99+)
borderColor	Color	#d1d1d1	复选框默认的边框颜色。	H5(3.99+)、App-Vue(3.99+)
activeBackgroundColor	Color	#ffffff	复选框选中时的背景颜色。	H5(3.99+)、App-Vue(3.99+)
activeBorderColor	Color	#d1d1d1	复选框选中时的边框颜色。	H5(3.99+)、App-Vue(3.99+)
iconColor	Color	#007aff	复选框图标的颜色。	H5(3.99+)、App-Vue(3.99+)

3.1 设置复选框的颜色和大小

• 说明：可以通过 color 属性设置复选框的颜色，通过 style 属性中的 transform: scale 调整复选框的大小。

<template>
  <view>
    <!-- 设置复选框颜色和大小 -->
    <checkbox-group>
      <label>
        <checkbox value="option1" checked color="#FFCC33" style="transform: scale(0.7);" /> 选中
      </label>
      <label>
        <checkbox value="option2" color="#FFCC33" style="transform: scale(0.7);" /> 未选中
      </label>
    </checkbox-group>
  </view>
</template>

4. 复选框组合使用案例

以下案例展示了 checkbox-group 组件和 checkbox 组件的实际应用，演示了复选框的选中、禁用、颜色和大小设置。通过这些组合，可以实现多选表单、设置选项等功能。

<template>
  <view>
    <!-- 默认样式的复选框 -->
    <view class="uni-padding-wrap uni-common-mt">
      <view class="uni-title uni-common-mt">默认样式</view>
      <checkbox-group>
        <label>
          <checkbox value="option1" checked /> 选中
        </label>
        <label>
          <checkbox value="option2" /> 未选中
        </label>
      </checkbox-group>
    </view>

    <!-- 自定义颜色和尺寸的复选框 -->
    <view class="uni-title uni-common-mt">自定义颜色和尺寸</view>
    <checkbox-group>
      <label>
        <checkbox value="option1" checked color="#FFCC33" style="transform:scale(0.7)" /> 选中
      </label>
      <label>
        <checkbox value="option2" color="#FFCC33" style="transform:scale(0.7)" /> 未选中
      </label>
    </checkbox-group>

    <!-- 使用 uni-list 布局的复选框列表 -->
    <view class="uni-list">
      <checkbox-group @change="onCheckboxChange">
        <label class="uni-list-cell uni-list-cell-pd" v-for="item in items" :key="item.value">
          <view>
            <checkbox :value="item.value" :checked="item.checked" />
          </view>
          <view>{{ item.name }}</view>
        </label>
      </checkbox-group>
    </view>
  </view>
</template>

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

// 复选框列表数据
const items = ref([
  { value: 'USA', name: '美国' },
  { value: 'CHN', name: '中国', checked: true },
  { value: 'BRA', name: '巴西' },
  { value: 'JPN', name: '日本' },
  { value: 'ENG', name: '英国' },
  { value: 'FRA', name: '法国' }
]);

// 复选框选中项变化时的处理函数
const onCheckboxChange = (e) => {
  const values = e.detail.value;
  items.value.forEach(item => {
    item.checked = values.includes(item.value);
  });
};
</script>

<style scoped>
/* uni-list 布局样式 */
.uni-list-cell {
  justify-content: flex-start;
}
</style>