# Checkbox

复选框组件，用于在一组选项中进行多项选择。支持单独使用和分组使用。

## 适用场景

- 表单中的多选项
- 全选/部分选中的联动控制
- 选项分组展示（水平/垂直布局）
- 按钮样式的多选组

## Props - Checkbox

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| onChange | `(e: ChangeEvent<HTMLInputElement>, checked: boolean, data: any) => void` | `-` | 否 | checked 变化时的回调 |
| onClick | `(e: MouseEvent<Element, MouseEvent>) => void` | `-` | 否 | 点击回调 |
| defaultChecked | `boolean` | `false` | 否 | 默认是否勾选 |
| className | `string` | `""` | 否 | 自定义 class |
| type | `"normal" \| "intensive" \| "important"` | `"normal"` | 否 | 类型 |
| size | `"sm" \| "md" \| "lg"` | `-` | 否 | 尺寸，默认使用 config context `baseSize` |
| checked | `boolean` | `-` | 否 | 控制是否勾选 |
| disabled | `boolean` | `false` | 否 | 是否禁用 |
| indeterminate | `boolean` | `false` | 否 | 是否部分选中 |
| data | `unknown` | `-` | 否 | 数据，onChange 回调时带回 |

## Props - CheckboxGroup

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| onChange | `((nextValue: string[]) => void) \| ((nextValue: number[]) => void)` | `-` | 否 | 值变化回调 |
| defaultValue | `CheckboxOptionValue[]` | `[]` | 否 | 默认选中值 |
| className | `string` | `""` | 否 | 自定义 class |
| type | `"normal" \| "intensive" \| "important"` | `"normal"` | 否 | 类型 |
| size | `"sm" \| "md" \| "lg"` | `-` | 否 | 尺寸，默认使用 config context `baseSize` |
| disabled | `boolean` | `-` | 否 | 是否整组禁用 |
| value | `CheckboxOptionValue[]` | `-` | 否 | 控制选中值 |
| layout | `"horizontal" \| "vertical"` | `"horizontal"` | 否 | 选项布局 |
| options | `GenericCheckboxGroupOptions` | `[]` | 否 | 选项列表 |
| onCheck | `GenericCheckboxGroupCheckHandler` | `-` | 否 | 点选 option 的回调 |
| onUncheck | `GenericCheckboxGroupCheckHandler` | `-` | 否 | 反选 option 的回调 |

## 典型用法

### 单独使用

```tsx
import {useState, useCallback, ChangeEvent} from 'react'
import {Checkbox} from '@befe/brick'

const [checked, setChecked] = useState(true)

const handleChange = useCallback((e: ChangeEvent, checked: boolean) => {
    setChecked(checked)
}, [])

<Checkbox checked={checked} onChange={handleChange}>一个选项</Checkbox>
<Checkbox disabled checked={checked}>禁用的选项</Checkbox>
```

### CheckboxGroup

```tsx
import {useState, useCallback} from 'react'
import {CheckboxGroup} from '@befe/brick'

const [value, setValue] = useState(['item-1'])
const options = [
    {value: 'item-1', label: '方案'},
    {value: 'item-2', label: '禁用方案', disabled: true},
    {value: 'item-3', label: '备选方案 XXX'},
]

<CheckboxGroup value={value} options={options} onChange={setValue} />
<CheckboxGroup disabled value={value} options={options} />
```

### 全选联动

> 使用 `indeterminate` 控制部分选择的样式

```tsx
import {Checkbox, CheckboxGroup} from '@befe/brick'

const options = ['React', 'Vue', 'Angular']
const isMasterChecked = checkedList.length === options.length
const isIndeterminate = checkedList.length > 0 && checkedList.length < options.length

<Checkbox
    checked={isMasterChecked}
    indeterminate={isIndeterminate}
    onClick={handleClickMaster}
>
    全选
</Checkbox>
<CheckboxGroup onChange={handleChange} value={checkedList} options={options} />
```

### 按钮样式与垂直布局

```tsx
// 加强/重要样式
<CheckboxGroup type={'intensive'} value={value} options={options} onChange={handleChange} />
<CheckboxGroup type={'important'} value={value} options={options} onChange={handleChange} />

// 垂直布局，每个选项占 1 行
<CheckboxGroup options={options} layout={'vertical'} />
```

## 注意事项

- 2021 BREAKING CHANGES：原 `intensive` 类型改名为 `important`，新增 `intensive` 为加强样式
- 不再支持 `props.style`
- 横向多行需要等宽效果时，通过 CSS 修饰 `.brick-checkbox` 的宽度实现
- `indeterminate` 用于全选联动场景，表示部分选中的视觉状态，与 `checked` 独立控制