项目字典使用指南

本项目封装了一套完善的字典管理机制，支持自动缓存、批量获取和组件化展示。本文档将详细介绍如何在项目中使用字典。

1. 核心机制

• useDict: 组合式函数（Composable），用于在组件中获取字典数据。会自动检查 Store 中是否有缓存，如果没有则请求后端 API。
• dictStore: Pinia Store，用于全局缓存字典数据，避免重复请求。
• DictTag: Vue 组件，用于根据字典值（Value）自动展示对应的标签（Label）。

2. 使用步骤

2.1 引入 useDict

在 Vue 组件的 <script setup> 中引入 useDict。

import { useDict } from '@/utils/dict'

2.2 获取字典数据

调用 useDict 函数，传入你需要获取的字典类型（Type）。支持同时获取多个字典。

const { order_status, order_item_status } = useDict('order_status', 'order_item_status')

• 参数: 字典类型的字符串（例如 'order_status'）。
• 返回值: 一个包含响应式 Ref 对象的对象。解构后的变量（如 order_status）是一个 Ref，其值为字典项数组：[{ label: '待付款', value: '0' }, ...]。

2.3 在模板中展示

使用 <dict-tag> 组件来展示字典值对应的文本。

<!-- 单个值 -->
<dict-tag :options="order_status" :value="order.status" />

<!-- 多个值（数组） -->
<dict-tag :options="order_status" :value="['0', '1']" />

• options: 字典数据（通过 useDict 获取的变量）。
• value: 当前的数据值（可以是字符串、数字或数组）。

2.4 在逻辑中使用（JS/TS）

既然 order_status 是一个 Ref，你可以在 JS 代码中直接访问它来进行查找或过滤。

// 打印字典数据
console.log(order_status.value)

// 查找特定 label
const target = order_status.value.find(item => item.value === '1')
console.log(target?.label) // 输出: 待发货

3. 完整示例

<script setup lang="ts">
import { ref } from 'vue'
import { useDict } from '@/utils/dict'

// 1. 获取字典数据
// 假设 'sys_user_sex' 是性别字典：0=男, 1=女, 2=未知
const { sys_user_sex } = useDict('sys_user_sex')

// 模拟数据
const user = ref({
  name: '张三',
  sex: '0' // 对应 "男"
})
</script>

<template>
  <view>
    <view>姓名：{{ user.name }}</view>
    
    <!-- 2. 使用组件展示 -->
    <view>
      性别：<dict-tag :options="sys_user_sex" :value="user.sex" />
    </view>
    
    <!-- 也可以直接使用 v-for 渲染下拉框等 -->
    <view>
      性别列表：
      <view v-for="item in sys_user_sex" :key="item.value">
        {{ item.label }} ({{ item.value }})
      </view>
    </view>
  </view>
</template>

4. 后端接口说明

• 接口地址: /upms/dictvalue/type/{type}
• 请求方式: GET
• 返回格式:

  [
    {
      "dictLabel": "显示文本",
      "dictValue": "实际值",
      ...
    }
  ]

• 前端 useDict 会自动将其转换为 { label, value } 格式存储。

5. 注意事项

1. 缓存: 字典数据加载一次后会存储在 Pinia (dictStore) 中，后续调用会直接使用缓存，无需再次请求网络。
2. 异步: useDict 是异步获取数据的，但在模板中使用 <dict-tag> 时无需担心，因为它是响应式的，数据加载完成后会自动更新视图。