# XCheckbox

基于配置的多选框组件，支持从配置中动态加载选项和默认值。

## 何时使用

当需要一个通过配置动态加载的多选控件时使用，特别是选项需要从后端获取的场景。

## 引用方式

```javascript
import XCheckbox from '@vue2-client/base-client/components/his/XCheckbox/XCheckbox'

export default {
  components: {
    XCheckbox
  }
}
```

## 代码演示

```html
<x-checkbox
  :queryParamsName="checkboxConfigName"
  v-model="selectedValues"
  @change="handleChange"
  @init="handleInit">
</x-checkbox>
```

## API

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|------|
| queryParamsName | 查询配置名称 | String/Object | null |
| value (v-model) | 当前选中值数组 | Array | [] |

### 事件

| 事件名 | 说明 | 回调参数 |
|------|------|------|
| change | 选项变化时的回调 | function(checkedValues: array) |
| init | 组件初始化完成时的回调 | function({config, options, value}) |

## 配置说明

组件通过 `queryParamsName` 从后端获取配置，配置格式如下：

```json
{
  "checkbox": [
    {
      "label": "选项A",
      "value": 1
    },
    {
      "label": "选项B",
      "value": 2
    },
    {
      "label": "选项C",
      "value": 3
    }
  ],
  "defaultValue": [1, 2]
}
```

## 配置示例

### 基本配置

```json
{
  "checkbox": [
    {
      "label": "全部",
      "value": "all"
    },
    {
      "label": "已过期",
      "value": "expired"
    },
    {
      "label": "30天内",
      "value": "30days"
    },
    {
      "label": "90天内",
      "value": "90days"
    }
  ],
  "defaultValue": ["all"]
}
```

### 带禁用选项的配置

```json
{
  "checkbox": [
    {
      "label": "选项A",
      "value": "a",
      "disabled": false
    },
    {
      "label": "选项B",
      "value": "b",
      "disabled": true
    },
    {
      "label": "选项C",
      "value": "c",
      "disabled": false
    }
  ],
  "defaultValue": ["a"]
}
```

## 使用示例

### 1. 基础使用

```html
<template>
  <x-checkbox
    :queryParamsName="'MyCheckboxConfig'"
    v-model="selectedValues"
    @change="onChange"
  />
</template>

<script>
export default {
  data() {
    return {
      selectedValues: []
    }
  },
  methods: {
    onChange(checkedValues) {
      console.log('选中的值：', checkedValues)
    }
  }
}
</script>
```

### 2. 带初始值的使用

```html
<template>
  <x-checkbox
    :queryParamsName="checkboxConfig"
    v-model="selectedValues"
    @change="onChange"
    @init="onInit"
  />
</template>

<script>
export default {
  data() {
    return {
      selectedValues: ['a', 'b'],
      checkboxConfig: {
        checkbox: [
          { label: '选项A', value: 'a' },
          { label: '选项B', value: 'b' },
          { label: '选项C', value: 'c' }
        ],
        defaultValue: ['a', 'b']
      }
    }
  },
  methods: {
    onChange(checkedValues) {
      console.log('选中的值：', checkedValues)
    },
    onInit({ config, options, value }) {
      console.log('组件初始化完成', { config, options, value })
    }
  }
}
</script>
```

## 注意事项

1. 如果配置中有 `defaultValue`，组件将默认选中这些值
2. `defaultValue` 必须是数组类型
3. 选项的 `value` 值必须是唯一的
4. 可以通过 `v-model` 或 `value` 属性从外部控制选中值
5. 组件会自动处理选项的禁用状态
6. 所有的事件回调都会返回选中值的数组

## 常见问题解答（FAQ）

### 1. 如何设置默认选中的选项？

可以通过配置中的 `defaultValue` 字段设置：
```json
{
  "defaultValue": ["value1", "value2"]
}
```

或者通过 v-model 绑定：
```html
<x-checkbox v-model="selectedValues"></x-checkbox>
```

```javascript
export default {
  data() {
    return {
      selectedValues: ["value1", "value2"]
    }
  }
}
```

### 2. 如何禁用某些选项？

在选项配置中添加 `disabled` 属性：
```json
{
  "checkbox": [
    {
      "label": "选项A",
      "value": "a",
      "disabled": true
    }
  ]
}
```

### 3. 如何获取选中的值？

可以通过 `change` 事件或 `v-model` 获取：
```html
<x-checkbox v-model="selectedValues" @change="onChange"></x-checkbox>
```

```javascript
methods: {
  onChange(checkedValues) {
    console.log('当前选中的值：', checkedValues)
  }
}
``` 