cxc-szcx-uniapp/uni_modules/cxc-szcx-dictSelect/readme.md

# cxc-szcx-dictSelect
### 组件说明：`uni-data-checkbox` 多选字典项选择组件

#### 一、组件概述
该组件基于 Vue 3 和 `uni-data-checkbox` 实现了一个多选的字典项选择器。它通过传入字典编码（`dictCode`）从后端接口获取字典项数据，并将其展示为多选框列表。组件支持双向数据绑定，可将选中的值同步给父组件，同时在选中值发生变化时触发 `change` 事件。

#### 二、组件使用的技术栈
- **框架**：Vue 3（使用组合式 API）
- **UI 组件**：`uni-data-checkbox`（用于展示多选框列表）
- **请求库**：假设使用了自定义的 `getDictItemsApi` 函数进行后端数据请求

#### 三、组件输入（Props）

| 属性名 | 类型 | 是否必填 | 默认值 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| `dictCode` | String | 是 | 无 | 用于从后端获取字典项数据的字典编码 |
| `modelValue` | String | 否 | '' | 双向绑定的选中值，多个值以逗号分隔 |

#### 四、组件输出（Emits）

| 事件名 | 说明 | 参数 |
| ---- | ---- | ---- |
| `update:modelValue` | 当选中值发生变化时，用于更新父组件的 `modelValue` | 选中值的字符串，多个值以逗号分隔 |
| `change` | 当选中值发生变化时触发 | 选中值的字符串，多个值以逗号分隔 |

#### 五、组件内部数据

| 变量名 | 类型 | 说明 |
| ---- | ---- | ---- |
| `dictItems` | Ref<Array> | 存储从后端获取的字典项数据 |
| `selectedValuesArray` | Ref<Array> | 存储当前选中的值，以数组形式存储 |

#### 六、组件方法

##### 1. `loadDictItems`
- **功能**：异步从后端接口获取字典项数据，并将其赋值给 `dictItems`。
- **实现逻辑**：
  - 调用 `getDictItemsApi` 函数，传入 `props.dictCode` 进行数据请求。
  - 若请求成功，将响应数据的 `result` 字段赋值给 `dictItems.value`。
  - 若请求失败，在控制台输出错误信息。

##### 2. 监听 `selectedValuesArray` 的变化
- **功能**：当 `selectedValuesArray` 发生变化时，将选中的值转换为字符串，并触发 `update:modelValue` 和 `change` 事件通知父组件。
- **实现逻辑**：
  - 使用 `watch` 函数监听 `selectedValuesArray` 的变化。
  - 当变化发生时，将新的选中值数组使用 `join(',')` 方法转换为字符串。
  - 触发 `update:modelValue` 和 `change` 事件，将转换后的字符串作为参数传递。

##### 3. 监听 `props.modelValue` 的变化
- **功能**：当父组件传递的 `modelValue` 发生变化时，更新 `selectedValuesArray`。
- **实现逻辑**：
  - 使用 `watch` 函数监听 `props.modelValue` 的变化。
  - 当变化发生时，将新的 `modelValue` 使用 `split(',')` 方法转换为数组，并赋值给 `selectedValuesArray.value`。
  - `immediate: true` 表示在组件初始化时就会执行一次监听回调，确保初始值能正确同步。

#### 七、组件生命周期钩子

##### `onMounted`
- **功能**：在组件挂载后调用 `loadDictItems` 函数，从后端获取字典项数据。

#### 八、使用示例
```vue
<template>
  <div>
    <MyDictCheckbox
      :dictCode="myDictCode"
      v-model="selectedValues"
      @change="handleChange"
    />
    <p>当前选中的值: {{ selectedValues }}</p>
  </div>
</template>

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

const myDictCode = 'exampleDictCode';
const selectedValues = ref('');

const handleChange = (newValue) => {
  console.log('选中值发生变化:', newValue);
};
</script>
```

#### 九、注意事项
- 确保 `getDictItemsApi` 函数能正确获取后端数据，且响应数据的格式符合 `{ result: [...] }`。
- 若 `modelValue` 初始值为空字符串，`selectedValuesArray` 会初始化为空数组。
- 由于使用了 `watch` 的 `deep: true` 选项，在 `selectedValuesArray` 内部元素发生变化时也会触发监听回调，可能会影响性能，需注意。