---
name: "CheckboxGroup"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "CheckboxGroup - 多项选择器组"
---

## CheckboxGroup

> [VERSION] @ray-js/ray >= 0.5.10

### 描述

多项选择器组，由多个 Checkbox 组成。options 与 children 二选一。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 废弃 | 描述 |
| --- | --- | --- | --- | --- | --- |
| `options` | `CheckboxGroupOption[]` | 否 | - | - | 选项列表，与 children 二选一 |
| `children` | `any \| any[] \| string` | 否 | - | - | 子节点，通常为多个 Checkbox，与 options 二选一 |
| `name` | `string` | 否 | - | - | 表单控件名称，提交表单时作为键名 |
| `disabled` | `boolean` | 否 | `false` | - | 是否禁用 |
| `onChange` | `(event: CheckboxGroupChangeEvent) => void` | 否 | - | - | 选中项发生改变时触发 |
| `id` | `string` | 否 | - | - | ID  undefined |
| `className` | `string` | 否 | - | - | css 类名  undefined |
| `style` | `any` | 否 | - | - | 样式  undefined |
| `onClick` | `(e: TouchEvent) => any` | 否 | - | - | 点击回调  undefined |
| `onTouchStart` | `( : TouchEvent) => any` | 否 | - | - | 开始触摸事件回调  undefined |
| `onTouchMove` | `(t: TouchEvent) => any` | 否 | - | - | 触摸移动事件回调  undefined |
| `onTouchCancel` | `(o: TouchEvent) => any` | 否 | - | - | 触摸取消事件回调  undefined |
| `onTouchEnd` | `(c: TouchEvent) => any` | 否 | - | - | 触摸结束事件回调  undefined |
| `onLongPress` | `(:: TouchEvent) => any` | 否 | - | - | 长按事件回调, 不再触发点击事件  undefined |
| `slot` | `string` | 否 | - | 是: 该属性仅在小程序基础组件中使用, 不建议在 React DSL 中使用 | 小程序组件插槽标识  undefined |
| `onLongClick` | `(e: TouchEvent) => any` | 否 | - | - | 长按触发  undefined |

### 引用对象

##### `type` CheckboxGroupOption

CheckboxGroup 选项数据。
继承 `CheckboxProps` 的全部属性（如 `value`、`checked`、`disabled`、`color` 等），并额外要求 `label` 作为展示文本。

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `label` | `string` | 选项标签文本 |

##### `interface` CheckboxGroupChangeEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `"change"` | 事件类型 |
| `detail` | `CheckboxGroupChangeDetail` | 事件数据 |

##### `interface` TouchEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `touches` | `T[]` | 触摸事件，当前停留在屏幕中的触摸点信息的数组 |
| `changedTouches` | `T[]` | 触摸事件，当前变化的触摸点信息的数组 |

##### `interface` CheckboxProps

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `value` | `string` | 选中时触发所属 checkbox-group 的 change 事件，并携带该 value |
| `checked` | `boolean` | 当前是否选中，可作默认选中 |
| `disabled` | `boolean` | 是否禁用 |
| `color` | `string` | 多选框颜色，同 CSS color |

##### `interface` CheckboxGroupChangeDetail

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `value` | `string[]` | 选中项的值列表 |

##### `interface` BaseEvent

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `type` | `string` | 事件类型 |
| `timeStamp` | `number` | 页面打开到触发事件所经过的毫秒数 |
| `target` | `Target` | 触发事件的源组件 |
| `currentTarget` | `Target` | 当前组件的一些属性值集合 |
| `mark` | `any` | 事件标记数据 |

##### `interface` Target

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 事件源组件的id |
| `dataset` | `Record<string, unknown>` | 事件源组件上的 `dataset` 自定义属性组成的集合 |


### 示例代码

#### 基础用法

```tsx
import React from 'react';
import { CheckboxGroup, Label, Checkbox } from '@ray-js/ray';

export default function () {
  const options = [
    { label: 'Apple', value: 'Apple' },
    { label: 'Pear', value: 'Pear' },
  ];

  return (
    <CheckboxGroup onChange={(e) => console.log('选中值:', e.detail.value)}>
      {options.map((item) => (
        <Label key={item.value}>
          <Checkbox value={item.value} />
          {item.label}
        </Label>
      ))}
    </CheckboxGroup>
  );
}
```

#### options 数据驱动

```tsx
import React from 'react';
import { CheckboxGroup, View, Text } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Text style={{ marginBottom: '10px' }}>使用 options 渲染:</Text>
      <CheckboxGroup
        name="fruits"
        disabled={false}
        options={[
          { label: '苹果', value: 'apple', checked: true },
          { label: '香蕉', value: 'banana' },
          { label: '葡萄', value: 'grape', disabled: true },
        ]}
        onChange={(e) => console.log('选中:', e.detail.value)}
      />
    </View>
  );
}
```