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	存储从后端获取的字典项数据
selectedValuesArray	Ref	存储当前选中的值，以数组形式存储

六、组件方法

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 函数，从后端获取字典项数据。

八、使用示例

<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 内部元素发生变化时也会触发监听回调，可能会影响性能，需注意。