From 9712b76d7835a81af3b90febcd4c344fcb973677 Mon Sep 17 00:00:00 2001 From: zeyan <258785420@qq.com> Date: Tue, 1 Jul 2025 17:04:48 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=90=88=E5=90=8C=E7=AD=BE?= =?UTF-8?q?=E8=AE=A2=E6=A8=A1=E5=9D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- uniapp/common/dictUtil使用说明.md | 283 ++++++++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 uniapp/common/dictUtil使用说明.md diff --git a/uniapp/common/dictUtil使用说明.md b/uniapp/common/dictUtil使用说明.md new file mode 100644 index 00000000..b8e9330b --- /dev/null +++ b/uniapp/common/dictUtil使用说明.md @@ -0,0 +1,283 @@ +# 字典工具类使用说明 + +## 概述 + +`dictUtil.js` 是一个专门用于批量获取和缓存字典数据的工具类，解决了原有单个接口调用次数过多、用户体验不佳的问题。 + +## 主要功能 + +1. **批量获取字典数据** - 一次性获取多个字典，减少接口调用 +2. **智能缓存机制** - 自动缓存数据，避免重复请求 +3. **业务场景支持** - 根据业务场景批量获取相关字典 +4. **兼容性保障** - 保持与原有代码的兼容性 + +## API 接口 + +### 后端接口 + +```php +// 批量获取字典数据 +GET /api/dict/batch?keys=key1,key2,key3 + +// 根据业务场景获取字典 +GET /api/dict/scene/{scene} + +// 获取单个字典 +GET /api/dict/single/{key} + +// 获取字典映射关系 +GET /api/dict/mapping + +// 清除字典缓存 +POST /api/dict/clear_cache +``` + +## 前端使用方法 + +### 1. 导入工具类 + +```javascript +import dictUtil from '@/common/dictUtil.js' +``` + +### 2. 批量获取字典数据 + +```javascript +// 方法一：直接批量获取 +const dictKeys = ['SourceChannel', 'source', 'customer_purchasing_power'] +const dictData = await dictUtil.getBatchDict(dictKeys) + +// 结果格式： +// { +// 'SourceChannel': [ +// {name: '抖音', value: '1', sort: 0, memo: ''}, +// {name: '微信', value: '2', sort: 1, memo: ''} +// ], +// 'source': [...], +// 'customer_purchasing_power': [...] +// } +``` + +### 3. 根据业务场景获取 + +```javascript +// 获取客户添加场景的所有字典 +const dictData = await dictUtil.getDictByScene('customer_add') + +// 或者使用便捷方法 +const dictData = await dictUtil.getCustomerAddDict() +``` + +### 4. 单个字典获取 + +```javascript +// 获取单个字典（与原有 util.getDict 兼容） +const sourceData = await dictUtil.getDict('source') +``` + +### 5. 预加载字典数据 + +```javascript +onLoad() { + // 在页面加载时预加载，提升用户体验 + const dictKeys = ['SourceChannel', 'source', 'customer_purchasing_power'] + dictUtil.preloadDict(dictKeys) +} +``` + +### 6. 缓存管理 + +```javascript +// 清除指定字典缓存 +dictUtil.clearCache(['SourceChannel', 'source']) + +// 清除所有字典缓存 +dictUtil.clearCache() +``` + +## 在页面中的完整使用示例 + +### 原有方式（多次接口调用） + +```javascript +// 原有方式 - 问题：多次接口调用，用户体验差 +async init() { + await this.getDict('source_channel') + await this.getDict('source') + await this.getDict('purchasing_power') + await this.getDict('initial_intent') + await this.getDict('cognitive_idea') + await this.getDict('status') + await this.getDict('decision_maker') + await this.getDict('distance') +} +``` + +### 优化后的方式（批量获取） + +```javascript +// 优化方式 - 一次接口调用获取所有数据 +import dictUtil from '@/common/dictUtil.js' + +export default { + onLoad() { + // 预加载字典数据 + this.preloadDictData() + }, + + methods: { + // 预加载字典数据 + async preloadDictData() { + const dictKeys = [ + 'SourceChannel', 'source', 'customer_purchasing_power', + 'preliminarycustomerintention', 'cognitive_concept', + 'kh_status', 'decision_maker', 'distance' + ] + + // 静默预加载，不阻塞页面显示 + dictUtil.preloadDict(dictKeys).catch(error => { + console.warn('字典预加载失败:', error) + }) + }, + + // 批量获取字典数据 + async getBatchDictData() { + try { + uni.showLoading({ title: '加载字典数据...', mask: true }) + + const dictKeys = [ + 'SourceChannel', // 来源渠道 + 'source', // 来源 + 'customer_purchasing_power', // 购买力 + 'preliminarycustomerintention', // 客户初步意向度 + 'cognitive_concept', // 认知理念 + 'kh_status', // 客户状态 + 'decision_maker', // 决策人 + 'distance' // 距离 + ] + + // 批量获取字典数据 + const dictData = await dictUtil.getBatchDict(dictKeys) + + // 处理字典数据 + this.processDictData(dictData) + + } catch (error) { + console.error('批量获取字典数据失败:', error) + // 如果批量获取失败，回退到单个获取 + await this.fallbackGetDict() + } finally { + uni.hideLoading() + } + }, + + // 处理批量获取的字典数据 + processDictData(dictData) { + const keyMapping = { + 'SourceChannel': 'source_channel', + 'source': 'source', + 'customer_purchasing_power': 'purchasing_power', + 'preliminarycustomerintention': 'initial_intent', + 'cognitive_concept': 'cognitive_idea', + 'kh_status': 'status', + 'decision_maker': 'decision_maker', + 'distance': 'distance' + } + + Object.keys(keyMapping).forEach(dictKey => { + const localKey = keyMapping[dictKey] + const dictItems = dictData[dictKey] || [] + + if (Array.isArray(dictItems) && dictItems.length > 0) { + const formattedOptions = dictItems.map(item => ({ + text: item.name || '', + value: item.value || '' + })) + + if (this.picker_config[localKey]) { + this.picker_config[localKey].options = formattedOptions + } + } + }) + } + } +} +``` + +## 性能优化特性 + +### 1. 缓存机制 +- 自动缓存字典数据到本地存储 +- 缓存有效期 30 分钟 +- 避免重复请求相同数据 + +### 2. 批量请求 +- 一次接口调用获取多个字典 +- 减少网络请求次数 +- 提升页面加载速度 + +### 3. 预加载策略 +- 页面 onLoad 时预加载数据 +- 不阻塞页面显示 +- 用户操作时数据已就绪 + +### 4. 错误处理 +- 批量获取失败时自动回退到单个获取 +- 缓存获取失败时直接请求接口 +- 保证功能的健壮性 + +## 兼容性说明 + +### 向后兼容 +工具类保持与原有 `util.getDict()` 方法的完全兼容： + +```javascript +// 原有代码无需修改，自动使用新的缓存和批量获取机制 +const sourceData = await util.getDict('source') + +// 新增的批量获取方法 +const batchData = await util.getBatchDict(['source', 'status']) +``` + +### 渐进式升级 +可以逐步将页面迁移到新的批量获取方式： + +1. 先导入 `dictUtil` +2. 在 `onLoad` 中添加预加载 +3. 将 `init` 方法中的多个 `getDict` 调用替换为一次 `getBatchDict` 调用 + +## 注意事项 + +1. **字典 Key 映射**：确保后端字典 key 与前端使用的 key 一致 +2. **缓存清理**：如果字典数据有更新，记得清理对应缓存 +3. **错误处理**：在批量获取失败时，有回退机制保证功能正常 +4. **性能限制**：单次最多获取 20 个字典，防止接口性能问题 + +## 扩展功能 + +### 自定义业务场景 + +```javascript +// 在 DictService.php 中添加新的业务场景 +public function getDictKeysByScene(string $scene): array +{ + $sceneMapping = [ + 'customer_add' => ['SourceChannel', 'source', '...'], + 'personnel_add' => ['gender', 'education', '...'], + 'your_scene' => ['key1', 'key2', '...'] // 添加自定义场景 + ]; + + return $sceneMapping[$scene] ?? []; +} +``` + +### 添加新的工具方法 + +```javascript +// 在 dictUtil.js 中扩展 +dictUtil.getYourSceneDict = async function() { + return await this.getDictByScene('your_scene') +} +``` + +通过这种方式，你可以大幅提升字典数据获取的性能和用户体验。 \ No newline at end of file