@lacqjs/nuxt-dict 0.0.2 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-PRESENT miaozhongfei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+
+<p align="center">
+  <h1 align="center">@lacqjs/nuxt-dict</h1>
+</p>
+
+<p align="center">
+  <a href="https://npmjs.com/package/@lacqjs/nuxt-dict"><img src="https://img.shields.io/npm/v/@lacqjs/nuxt-dict?style=flat-square&colorA=202128&colorB=36936A" alt="Version"></a>
+  <a href="https://npmjs.com/package/@lacqjs/nuxt-dict"><img src="https://img.shields.io/npm/dm/@lacqjs/nuxt-dict?style=flat-square&colorA=202128&colorB=36936A" alt="Downloads"></a>
+  <a href="https://github.com/miaozhongfei/nuxt-dict/blob/main/LICENSE"><img src="https://img.shields.io/github/license/miaozhongfei/nuxt-dict?style=flat-square&colorA=202128&colorB=36936A" alt="License"></a>
+  <a href="https://miaozhongfei.github.io/nuxt-dict/"><img src="https://img.shields.io/badge/Docs-202128?style=flat-square&logo=gitbook&logoColor=DDDDD4" alt="Docs"></a>
+</p>
+
+> Nuxt 数据字典模块，提供扁平 / 树形字典翻译、多语言国际化、三级缓存与 SSR 预取。
+
+## 快速开始
+
+### 安装
+
+```bash
+pnpm add @lacqjs/nuxt-dict
+```
+
+### 注册模块
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@lacqjs/nuxt-dict'],
+})
+```
+
+```vue
+<template>
+  <el-select v-model="value" placeholder="请选择">
+    <el-option v-for="o in options" :key="o.value" :label="o.label" :value="o.value" />
+  </el-select>
+</template>
+
+<script setup lang="ts">
+const { data: options } = useDict('gender')
+const value = ref('')
+</script>
+```
+
+## 特性
+
+- **扁平字典** — `useDict(type)` 自动加载，返回 `[{ value, label }]`，直接绑定 UI 组件
+- **树形字典** — `useDictTree(type)` 支持任意深度树形结构 + `findPath()` 路径回溯
+- **多语言** — `useLocale()` 切换语言，所有活跃字典实例自动重新请求
+- **多仓库** — 通过 `stores` 配置从不同 API 端点加载，实现数据隔离
+- **三级缓存** — 内存 LRU → IndexedDB → 网络（版本校验），最大化减少请求
+- **SSR 预取** — `ssr.prefetch` 配置服务端预加载，加速首屏渲染
+- **自定义适配器** — 实现 `DictAdapter` 接口即可对接任意数据源
+- **同步翻译** — `$dict.translate()` / `$dict.translatePath()` / `$dict.translateData()` 全场景覆盖
+
+完整用法与配置请查看 → [文档](https://miaozhongfei.github.io/nuxt-dict/)
+
+## 开发
+
+```bash
+pnpm dev            # 启动开发服务器
+pnpm prepack        # 构建产物
+pnpm lint           # 代码检查
+pnpm typecheck      # 类型检查
+pnpm e2e            # E2E 测试
+```
+
+## 感谢 / 致谢
+
+本项目受益于以下优秀开源项目：
+
+- [Nuxt](https://nuxt.com/) — Vue 全栈框架
+- [@nuxt/kit](https://github.com/nuxt/nuxt) — Nuxt 模块开发工具包
+- [defu](https://github.com/unjs/defu) — 深度合并配置
+- [consola](https://github.com/unjs/consola) — 日志工具
+- [compare-versions](https://github.com/omichelsen/compare-versions) — 版本比较
+
+## 许可证
+
+[MIT](./LICENSE) License © 2026-PRESENT [miaozhongfei](https://github.com/miaozhongfei)

package/dist/module.d.mts

@@ -1,7 +1,9 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import * as __runtime_types from '../dist/runtime/types/index.js';
 import { ModuleOptions } from '../dist/runtime/types/index.js';
-export { ModuleOptions } from '../dist/runtime/types/index.js';
+export { DictItem, DictTranslator, GetDictItemOptions, ModuleOptions, TranslateOptions, TranslatePathOptions, TreeNode } from '../dist/runtime/types/index.js';
+export { DictManager } from '../dist/runtime/core/dict-manager.js';
+export { createDictTranslator } from '../dist/runtime/utils/dict-translator.js';
 
 /**
  * Nuxt Dict 模块入口。

package/dist/module.d.ts

@@ -1,7 +1,9 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import * as __runtime_types from '../dist/runtime/types/index.js';
 import { ModuleOptions } from '../dist/runtime/types/index.js';
-export { ModuleOptions } from '../dist/runtime/types/index.js';
+export { DictItem, DictTranslator, GetDictItemOptions, ModuleOptions, TranslateOptions, TranslatePathOptions, TreeNode } from '../dist/runtime/types/index.js';
+export { DictManager } from '../dist/runtime/core/dict-manager.js';
+export { createDictTranslator } from '../dist/runtime/utils/dict-translator.js';
 
 /**
  * Nuxt Dict 模块入口。

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@lacqjs/nuxt-dict",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "configKey": "dict",
   "compatibility": {
     "nuxt": "^4.4.8"

package/dist/module.mjs

@@ -2,9 +2,10 @@ import { fileURLToPath } from 'url';
 import { defineNuxtModule, useLogger, createResolver, addPlugin, addImportsDir, addTypeTemplate } from '@nuxt/kit';
 import { defaultOptions } from '../dist/runtime/options.js';
 import { createLogger } from '../dist/runtime/utils/logger.js';
+export { createDictTranslator } from '../dist/runtime/utils/dict-translator.js';
 
 const name = "@lacqjs/nuxt-dict";
-const version = "0.0.2";
+const version = "0.0.3";
 const devDependencies = {
 	nuxt: "^4.4.8"};
 const pkg = {
@@ -15,17 +16,139 @@ const pkg = {
 function registerTypeTemplates(resolver, stores) {
   addTypeTemplate({
     filename: "types/nuxt-dict.d.ts",
+    // eslint-disable max-lines-per-function
     getContents: () => `
-import type { DictManager } from '${pkg.name}'
+import type { StoreKey } from '#build/types/nuxt-dict-store-names'
 
 declare module '#app' {
   interface NuxtApp {
-    $dict: ReturnType<typeof import('${pkg.name}').createDictTranslator>
-    $dictManager: DictManager
-  }
-}
+    $dict: {
+      /**
+       * \u540C\u6B65\u7FFB\u8BD1\u5B57\u5178\u7F16\u7801 \u2192 \u6587\u672C\u3002
+       * @description \u540C\u6B65\u7FFB\u8BD1\u5B57\u5178\u7F16\u7801 \u2192 \u6587\u672C\u3002\u4ECE\u5168\u5C40\u5185\u5B58\u7F13\u5B58\u4E2D\u67E5\u627E\u7F16\u7801\u5BF9\u5E94\u7684\u6587\u672C\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE code \u539F\u6837\u3002\u5148\u901A\u8FC7 useDict \u7B49\u52A0\u8F7D\u6570\u636E\u540E\u8C03\u7528\u3002
+       * @param type - \u5B57\u5178\u7C7B\u578B\u540D\uFF0C\u5982 'gender'
+       * @param code - \u7F16\u7801\u503C
+       * @param opts - \u53EF\u9009\u914D\u7F6E\u5BF9\u8C61
+       * @param {StoreKey} [opts.storeName] - \u6307\u5B9A\u4ED3\u5E93\u540D
+       * @param {string} [opts.field] - \u6307\u5B9A\u53D6\u503C\u5B57\u6BB5\uFF0C\u9ED8\u8BA4 'label'
+       * @returns {string} \u7FFB\u8BD1\u6587\u672C\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE code \u539F\u6837
+       * @example
+       * $dict.translate('gender', 'male')
+       * $dict.translate('gender', 'male', { storeName: 'dicts2' })
+       */
+      translate(type: string, code: string | number, opts?: { storeName?: StoreKey; field?: string }): string
+      /**
+       * \u6811\u5F62\u5B57\u5178\u4E2D\u67E5\u627E\u7F16\u7801\u7684\u5B8C\u6574\u5C42\u7EA7\u8DEF\u5F84\u3002
+       * @description \u6811\u5F62\u5B57\u5178\u4E2D\u67E5\u627E\u7F16\u7801\u7684\u5B8C\u6574\u5C42\u7EA7\u8DEF\u5F84\u3002\u4ECE\u5185\u5B58\u7F13\u5B58\u4E2D\u52A0\u8F7D\u7684\u6811\u5F62\u5B57\u5178\u6570\u636E\u91CC\uFF0C\u901A\u8FC7 DFS \u67E5\u627E\u76EE\u6807\u7F16\u7801\u5E76\u56DE\u6EAF\u5B8C\u6574\u8DEF\u5F84\uFF0C\u7528\u5206\u9694\u7B26\u62FC\u63A5\u540E\u8FD4\u56DE\u3002
+       * @param type - \u6811\u5F62\u5B57\u5178\u7C7B\u578B\u540D\uFF0C\u5982 'region'
+       * @param code - \u53F6\u5B50\u8282\u70B9\u7F16\u7801\u503C
+       * @param opts - \u53EF\u9009\u914D\u7F6E\u5BF9\u8C61
+       * @param {StoreKey} [opts.storeName] - \u6307\u5B9A\u4ED3\u5E93\u540D
+       * @param {string} [opts.field] - \u6307\u5B9A\u8282\u70B9\u53D6\u503C\u5B57\u6BB5\uFF0C\u9ED8\u8BA4 'label'
+       * @param {string} [opts.separator] - \u5C42\u7EA7\u8DEF\u5F84\u5206\u9694\u7B26\uFF0C\u9ED8\u8BA4 ' / '
+       * @returns {string} \u7528\u5206\u9694\u7B26\u8FDE\u63A5\u7684\u5B8C\u6574\u5C42\u7EA7\u8DEF\u5F84\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE code \u539F\u6837
+       * @example
+       * $dict.translatePath('region', '440104')
+       * $dict.translatePath('region', '440104', { separator: ' \u2192 ' })
+       */
+      translatePath(type: string, code: string | number, opts?: { storeName?: StoreKey; field?: string; separator?: string }): string
+      /**
+       * \u6279\u91CF\u7FFB\u8BD1\u6570\u636E\u5BF9\u8C61\u4E2D\u7684\u591A\u4E2A\u7F16\u7801\u5B57\u6BB5\u3002
+       * @description \u6279\u91CF\u7FFB\u8BD1\u6570\u636E\u5BF9\u8C61\u4E2D\u7684\u591A\u4E2A\u7F16\u7801\u5B57\u6BB5\u3002\u4F20\u5165\u4E00\u4E2A\u6570\u636E\u5BF9\u8C61\u548C\u5B57\u6BB5\u2192\u5B57\u5178\u7C7B\u578B\u6620\u5C04\u8868\uFF0C\u8FD4\u56DE\u8FFD\u52A0\u4E86\u7FFB\u8BD1\u5B57\u6BB5\u7684\u65B0\u5BF9\u8C61\uFF08\u4E0D\u4FEE\u6539\u539F\u5BF9\u8C61\uFF09\u3002
+       * @param data - \u9700\u8981\u7FFB\u8BD1\u7684\u6570\u636E\u5BF9\u8C61\uFF0C\u5982 { gender: 'male', status: 1 }
+       * @param mapping - \u5B57\u6BB5\u2192\u5B57\u5178\u7C7B\u578B\u6620\u5C04\u8868\uFF0C\u503C\u4E3A string\uFF08\u9ED8\u8BA4\u4ED3\u5E93\uFF09\u6216 { type, storeName? }\uFF08\u6307\u5B9A\u4ED3\u5E93\uFF09
+       * @param suffix - \u7FFB\u8BD1\u5B57\u6BB5\u540E\u7F00\uFF0C\u9ED8\u8BA4 '_label'\uFF0C\u7ED3\u679C\u5199\u5165 \u539F\u5B57\u6BB5\u540D + suffix
+       * @returns {Record<string, unknown>} \u65B0\u5BF9\u8C61\uFF0C\u5305\u542B\u539F\u6570\u636E\u6240\u6709\u5B57\u6BB5 + \u4EE5 suffix \u4E3A\u540E\u7F00\u7684\u7FFB\u8BD1\u5B57\u6BB5
+       * @example
+       * $dict.translateData(
+       *   { gender: 'male', status: 1, name: '\u5F20\u4E09' },
+       *   { gender: 'gender', status: 'status' }
+       * )
+       * // \u2192 { ..., gender_label: '\u7537', status_label: '\u7981\u7528', ... }
+       */
+       translateData(data: Record<string, unknown>, mapping: Record<string, string | { type: string; storeName?: StoreKey }>, suffix?: string): Record<string, unknown>
+       /**
+        * \u4ECE\u5185\u5B58\u7F13\u5B58\u4E2D\u67E5\u627E\u7F16\u7801\u5BF9\u5E94\u7684\u5B8C\u6574\u5B57\u5178\u9879\u5BF9\u8C61\u3002
+        * @description \u4ECE\u5DF2\u52A0\u8F7D\u7684\u7F13\u5B58\u4E2D\u67E5\u627E\u7F16\u7801\u5BF9\u5E94\u7684\u5B8C\u6574 DictItem \u5BF9\u8C61\uFF08\u975E\u5B57\u7B26\u4E32\u7FFB\u8BD1\uFF09\u3002\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE undefined\u3002
+        * @param type - \u5B57\u5178\u7C7B\u578B\u540D\uFF0C\u5982 'gender'
+        * @param code - \u7F16\u7801\u503C
+        * @param opts - \u53EF\u9009\u914D\u7F6E\u5BF9\u8C61
+        * @param {StoreKey} [opts.storeName] - \u6307\u5B9A\u4ED3\u5E93\u540D
+        * @returns {DictItem | undefined} \u5B8C\u6574\u7684\u5B57\u5178\u9879\u5BF9\u8C61\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE undefined
+        * @example
+        * $dict.getDictItem('gender', 'male')
+        * $dict.getDictItem('gender', 'male', { storeName: 'dicts2' })
+        */
+       getDictItem(type: string, code: string | number, opts?: { storeName?: StoreKey }): DictItem | undefined
+     }
+   }
+ }
+
+ declare module '@vue/runtime-core' {
+  interface ComponentCustomProperties {
+    $dict: {
+      /**
+       * \u540C\u6B65\u7FFB\u8BD1\u5B57\u5178\u7F16\u7801 \u2192 \u6587\u672C\u3002
+       * @description \u540C\u6B65\u7FFB\u8BD1\u5B57\u5178\u7F16\u7801 \u2192 \u6587\u672C\u3002\u4ECE\u5168\u5C40\u5185\u5B58\u7F13\u5B58\u4E2D\u67E5\u627E\u7F16\u7801\u5BF9\u5E94\u7684\u6587\u672C\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE code \u539F\u6837\u3002
+       * @param type - \u5B57\u5178\u7C7B\u578B\u540D\uFF0C\u5982 'gender'
+       * @param code - \u7F16\u7801\u503C
+       * @param opts - \u53EF\u9009\u914D\u7F6E\u5BF9\u8C61
+       * @param {StoreKey} [opts.storeName] - \u6307\u5B9A\u4ED3\u5E93\u540D
+       * @param {string} [opts.field] - \u6307\u5B9A\u53D6\u503C\u5B57\u6BB5\uFF0C\u9ED8\u8BA4 'label'
+       * @returns {string} \u7FFB\u8BD1\u6587\u672C\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE code \u539F\u6837
+       * @example
+       * $dict.translate('gender', 'male')
+       * $dict.translate('gender', 'male', { storeName: 'dicts2' })
+       */
+      translate(type: string, code: string | number, opts?: { storeName?: StoreKey; field?: string }): string
+      /**
+       * \u6811\u5F62\u5B57\u5178\u4E2D\u67E5\u627E\u7F16\u7801\u7684\u5B8C\u6574\u5C42\u7EA7\u8DEF\u5F84\u3002
+       * @description \u6811\u5F62\u5B57\u5178\u4E2D\u67E5\u627E\u7F16\u7801\u7684\u5B8C\u6574\u5C42\u7EA7\u8DEF\u5F84\u3002\u901A\u8FC7 DFS \u67E5\u627E\u76EE\u6807\u7F16\u7801\u5E76\u56DE\u6EAF\u5B8C\u6574\u8DEF\u5F84\uFF0C\u7528\u5206\u9694\u7B26\u62FC\u63A5\u540E\u8FD4\u56DE\u3002
+       * @param type - \u6811\u5F62\u5B57\u5178\u7C7B\u578B\u540D\uFF0C\u5982 'region'
+       * @param code - \u53F6\u5B50\u8282\u70B9\u7F16\u7801\u503C
+       * @param opts - \u53EF\u9009\u914D\u7F6E\u5BF9\u8C61
+       * @param {StoreKey} [opts.storeName] - \u6307\u5B9A\u4ED3\u5E93\u540D
+       * @param {string} [opts.field] - \u6307\u5B9A\u8282\u70B9\u53D6\u503C\u5B57\u6BB5\uFF0C\u9ED8\u8BA4 'label'
+       * @param {string} [opts.separator] - \u5C42\u7EA7\u8DEF\u5F84\u5206\u9694\u7B26\uFF0C\u9ED8\u8BA4 ' / '
+       * @returns {string} \u7528\u5206\u9694\u7B26\u8FDE\u63A5\u7684\u5B8C\u6574\u5C42\u7EA7\u8DEF\u5F84\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE code \u539F\u6837
+       * @example
+       * $dict.translatePath('region', '440104')
+       * $dict.translatePath('region', '440104', { separator: ' \u2192 ' })
+       */
+      translatePath(type: string, code: string | number, opts?: { storeName?: StoreKey; field?: string; separator?: string }): string
+      /**
+       * \u6279\u91CF\u7FFB\u8BD1\u6570\u636E\u5BF9\u8C61\u4E2D\u7684\u591A\u4E2A\u7F16\u7801\u5B57\u6BB5\u3002
+       * @description \u6279\u91CF\u7FFB\u8BD1\u6570\u636E\u5BF9\u8C61\u4E2D\u7684\u591A\u4E2A\u7F16\u7801\u5B57\u6BB5\u3002\u4F20\u5165\u5B57\u6BB5\u2192\u5B57\u5178\u7C7B\u578B\u6620\u5C04\u8868\uFF0C\u8FD4\u56DE\u542B\u7FFB\u8BD1\u5B57\u6BB5\u7684\u65B0\u5BF9\u8C61\uFF08\u4E0D\u4FEE\u6539\u539F\u5BF9\u8C61\uFF09\u3002
+       * @param data - \u9700\u8981\u7FFB\u8BD1\u7684\u6570\u636E\u5BF9\u8C61\uFF0C\u5982 { gender: 'male', status: 1 }
+       * @param mapping - \u5B57\u6BB5\u2192\u5B57\u5178\u7C7B\u578B\u6620\u5C04\u8868\uFF0C\u503C\u4E3A string\uFF08\u9ED8\u8BA4\u4ED3\u5E93\uFF09\u6216 { type, storeName? }\uFF08\u6307\u5B9A\u4ED3\u5E93\uFF09
+       * @param suffix - \u7FFB\u8BD1\u5B57\u6BB5\u540E\u7F00\uFF0C\u9ED8\u8BA4 '_label'
+       * @returns {Record<string, unknown>} \u65B0\u5BF9\u8C61\uFF0C\u5305\u542B\u539F\u6570\u636E\u6240\u6709\u5B57\u6BB5 + \u4EE5 suffix \u4E3A\u540E\u7F00\u7684\u7FFB\u8BD1\u5B57\u6BB5
+       * @example
+       * $dict.translateData(
+       *   { gender: 'male', status: 1, name: '\u5F20\u4E09' },
+       *   { gender: 'gender', status: 'status' }
+       * )
+       * // \u2192 { ..., gender_label: '\u7537', status_label: '\u7981\u7528', ... }
+       */
+       translateData(data: Record<string, unknown>, mapping: Record<string, string | { type: string; storeName?: StoreKey }>, suffix?: string): Record<string, unknown>
+       /**
+        * \u4ECE\u5185\u5B58\u7F13\u5B58\u4E2D\u67E5\u627E\u7F16\u7801\u5BF9\u5E94\u7684\u5B8C\u6574\u5B57\u5178\u9879\u5BF9\u8C61\u3002
+        * @description \u4ECE\u5DF2\u52A0\u8F7D\u7684\u7F13\u5B58\u4E2D\u67E5\u627E\u7F16\u7801\u5BF9\u5E94\u7684\u5B8C\u6574 DictItem \u5BF9\u8C61\uFF08\u975E\u5B57\u7B26\u4E32\u7FFB\u8BD1\uFF09\u3002\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE undefined\u3002
+        * @param type - \u5B57\u5178\u7C7B\u578B\u540D\uFF0C\u5982 'gender'
+        * @param code - \u7F16\u7801\u503C
+        * @param opts - \u53EF\u9009\u914D\u7F6E\u5BF9\u8C61
+        * @param {StoreKey} [opts.storeName] - \u6307\u5B9A\u4ED3\u5E93\u540D
+        * @returns {DictItem | undefined} \u5B8C\u6574\u7684\u5B57\u5178\u9879\u5BF9\u8C61\uFF0C\u7F13\u5B58\u672A\u547D\u4E2D\u65F6\u8FD4\u56DE undefined
+        * @example
+        * $dict.getDictItem('gender', 'male')
+        * $dict.getDictItem('gender', 'male', { storeName: 'dicts2' })
+        */
+       getDictItem(type: string, code: string | number, opts?: { storeName?: StoreKey }): DictItem | undefined
+     }
+   }
+ }
 
-export {}
+ export {}
 `
   });
   addTypeTemplate({

package/dist/runtime/composables/useDict.d.ts

@@ -4,6 +4,12 @@ import type { UseDictReturn, StoreKey } from '../types/index.js';
  * 组件挂载时自动加载，卸载时自动清理引用。
  * 返回翻译函数、加载状态和手动刷新方法。
  *
+ * @description 从字典管理器获取扁平字典数据，挂载后自动触发网络请求（或缓存）。
+ * @param {string} type - 字典类型名（如 'gender'），一参形式：useDict(type)，使用默认仓库 'dicts'
+ * @param {StoreKey} storeName - 仓库名（如 'dicts2'），二参形式：useDict(storeName, type)
+ * @param {string} type - 字典类型名，二参形式时作为第二参数传入
+ * @returns {UseDictReturn} 包含 data（字典项数组）、translate（翻译函数）、loading、error、refresh
+ *
  * @example
  * // 默认存储库 'dicts'
  * const { data, translate } = useDict('gender')

package/dist/runtime/composables/useDict.js

@@ -2,12 +2,18 @@ import { shallowRef, ref, watch, onMounted, onBeforeUnmount } from "vue";
 import { useNuxtApp } from "#imports";
 import { DEFAULT_STORE_NAME } from "../core/cache/indexeddb-cache.js";
 const activeInstances = /* @__PURE__ */ new Map();
-async function fetchDictData(manager, dictType, storeName, data, loading, error, mode = "load") {
+async function fetchDictData(manager, dictType, storeName, data, loading, error, mode = "load", itemMap) {
   loading.value = true;
   error.value = null;
   try {
     const entry = await (mode === "refresh" ? manager.refresh(dictType, storeName) : manager.getDict(dictType, storeName));
     data.value = entry.items;
+    if (itemMap) {
+      itemMap.clear();
+      for (const item of entry.items) {
+        itemMap.set(String(item.value), item);
+      }
+    }
   } catch (e) {
     error.value = e instanceof Error ? e.message : String(e);
   } finally {
@@ -35,25 +41,41 @@ export function useDict(storeOrType, maybeType) {
   const storeName = maybeType === void 0 ? DEFAULT_STORE_NAME : storeOrType;
   const dictType = maybeType ?? storeOrType;
   const data = shallowRef(null);
+  const itemMap = /* @__PURE__ */ new Map();
   const loading = ref(false);
   const error = ref(null);
   const instanceId = Symbol(dictType);
   const trackKey = `${storeName}:${dictType}`;
   trackInstance(trackKey, instanceId);
-  function translate(code) {
-    return manager.translate(dictType, code, storeName);
+  function translate(value, opts) {
+    const targetStore = opts?.storeName ?? storeName;
+    const field = opts?.field ?? "label";
+    if (targetStore !== storeName) {
+      return manager.translate(dictType, value, { storeName: targetStore, field });
+    }
+    if (!data.value) return String(value);
+    const item = itemMap.get(String(value));
+    if (!item) return String(value);
+    return item[field] ?? item.label;
+  }
+  function getDictItem(value, opts) {
+    if (opts?.storeName && opts.storeName !== storeName) {
+      return manager.getDictItem(dictType, value, opts);
+    }
+    if (!data.value) return void 0;
+    return itemMap.get(String(value));
   }
   async function refresh() {
-    await fetchDictData(manager, dictType, storeName, data, loading, error, "refresh");
+    await fetchDictData(manager, dictType, storeName, data, loading, error, "refresh", itemMap);
   }
   onMounted(() => {
-    fetchDictData(manager, dictType, storeName, data, loading, error, "load");
+    fetchDictData(manager, dictType, storeName, data, loading, error, "load", itemMap);
   });
   watch(
     () => manager.locale.value,
     () => {
-      fetchDictData(manager, dictType, storeName, data, loading, error, "load");
+      fetchDictData(manager, dictType, storeName, data, loading, error, "load", itemMap);
     }
   );
-  return { data, translate, loading, error, refresh };
+  return { data, translate, getDictItem, loading, error, refresh };
 }

package/dist/runtime/composables/useDictTree.d.ts

@@ -3,6 +3,12 @@ import type { UseDictTreeReturn, StoreKey } from '../types/index.js';
  * 使用树形字典数据，支持翻译和路径查找。
  * 组件挂载时自动加载，适用于区域选择器等级联场景。
  *
+ * @description 从字典管理器获取树形字典数据，挂载后自动触发网络请求（或缓存）。
+ * @param {string} type - 字典类型名（如 'region'），一参形式：useDictTree(type)，使用默认仓库 'dicts'
+ * @param {StoreKey} storeName - 仓库名（如 'dicts2'），二参形式：useDictTree(storeName, type)
+ * @param {string} type - 字典类型名，二参形式时作为第二参数传入
+ * @returns {UseDictTreeReturn} 包含 tree（树节点数组）、translate（翻译函数）、findPath（路径回溯）、loading、refresh
+ *
  * @example
  * // 默认存储库 'dicts'
  * const { tree, translate } = useDictTree('region')

package/dist/runtime/composables/useDictTree.js

@@ -7,19 +7,30 @@ export function useDictTree(storeOrType, maybeType) {
   const storeName = maybeType === void 0 ? DEFAULT_STORE_NAME : storeOrType;
   const dictType = maybeType ?? storeOrType;
   const tree = shallowRef(null);
+  const nodeMap = /* @__PURE__ */ new Map();
+  const pathMap = /* @__PURE__ */ new Map();
   const loading = ref(false);
-  function translate(code) {
-    return manager.translate(dictType, code, storeName);
+  function translate(value, opts) {
+    const targetStore = opts?.storeName ?? storeName;
+    const field = opts?.field ?? "label";
+    if (targetStore !== storeName) {
+      return manager.translate(dictType, value, { storeName: targetStore, field });
+    }
+    if (!tree.value) return String(value);
+    const node = nodeMap.get(String(value));
+    if (!node) return String(value);
+    return node[field] ?? node.label;
   }
-  function findPath(code) {
+  function findPath(value) {
     if (!tree.value) return [];
-    return findPathInTree(tree.value, code);
+    return pathMap.get(String(value)) ?? [];
   }
   async function load() {
     loading.value = true;
     try {
       const entry = await manager.getDict(dictType, storeName);
       tree.value = entry.tree ?? null;
+      if (entry.tree) buildMaps(entry.tree, nodeMap, pathMap);
     } finally {
       loading.value = false;
     }
@@ -29,6 +40,7 @@ export function useDictTree(storeOrType, maybeType) {
     try {
       const entry = await manager.refresh(dictType, storeName);
       tree.value = entry.tree ?? null;
+      if (entry.tree) buildMaps(entry.tree, nodeMap, pathMap);
     } finally {
       loading.value = false;
     }
@@ -37,17 +49,14 @@ export function useDictTree(storeOrType, maybeType) {
   watch(() => manager.locale.value, load);
   return { tree, translate, findPath, loading, refresh };
 }
-function findPathInTree(nodes, targetCode) {
+function buildMaps(nodes, nodeMap, pathMap, ancestors = []) {
   for (const node of nodes) {
-    if (node.code === targetCode) {
-      return [node.label];
-    }
+    const code = String(node.value);
+    const path = [...ancestors, node.label];
+    nodeMap.set(code, node);
+    pathMap.set(code, path);
     if (node.children && node.children.length > 0) {
-      const childPath = findPathInTree(node.children, targetCode);
-      if (childPath.length > 0) {
-        return [node.label, ...childPath];
-      }
+      buildMaps(node.children, nodeMap, pathMap, path);
     }
   }
-  return [];
 }

package/dist/runtime/composables/useLocale.d.ts

@@ -2,6 +2,20 @@
  * 获取/切换当前语言。
  * 切换语言时会同步更新 cookie（客户端）并通知 DictManager 刷新缓存。
  * locale 为 DictManager 上的响应式 ref，语言切换后所有 useDict / useDictTree 组件自动重取。
+ *
+ * @description 从 DictManager 获取当前语言信息，提供切换语言并持久化到 cookie 的能力。
+ * @returns {{ locale: Ref<string>, setLocale: (newLocale: string) => void, locales: string[] }} 当前语言 ref、语言切换函数、支持的语言列表
+ *
+ * @example
+ * const { locale, setLocale } = useLocale()
+ *
+ * // 切换语言
+ * setLocale('en-US')                // 切换到英文
+ * console.log(locale.value)         // 'en-US'
+ *
+ * // 模板中直接使用
+ * // <p>当前语言：{{ locale }}</p>
+ * // <button @click="setLocale('zh-CN')">中文</button>
  */
 export declare function useLocale(): {
     locale: import("vue").ShallowRef<string, string>;

package/dist/runtime/core/adapter.d.ts

@@ -1,5 +1,16 @@
 import type { DictAdapter } from '../types/index.js';
-/** 创建默认适配器所需的配置参数 */
+/**
+ * 创建默认适配器所需的配置参数。
+ *
+ * @example
+ * const adapter = createDefaultAdapter({
+ *   baseURL: '/api',
+ *   dictEndpoint: '/dict/list',
+ *   versionEndpoint: '/dict/version',
+ *   paramKey: 'lang',
+ *   apiHeaderKey: 'X-Locale',
+ * })
+ */
 export interface DefaultAdapterOptions {
     baseURL: string;
     dictEndpoint: string;
@@ -13,5 +24,20 @@ export interface DefaultAdapterOptions {
  * 创建默认的 REST 字典适配器。
  * 底层使用原生 fetch，兼容浏览器和 Node.js 18+（Nuxt 4 要求）。
  * SSR 侧由 resolveBaseURL() 保证 baseURL 为绝对 origin，客户端相对路径由浏览器处理。
+ *
+ * @param {DefaultAdapterOptions} options - 适配器配置参数（baseURL、dictEndpoint、versionEndpoint、paramKey、apiHeaderKey）
+ * @returns {DictAdapter} 实现了 fetchDict / fetchVersion 方法的 DictAdapter 实例
+ *
+ * @example
+ * const adapter = createDefaultAdapter({
+ *   baseURL: 'https://api.example.com',
+ *   dictEndpoint: '/v1/dict/list',
+ *   versionEndpoint: '/v1/dict/version',
+ *   paramKey: 'lang',
+ *   apiHeaderKey: 'X-Locale',
+ * })
+ *
+ * // 用于 ModuleOptions.api.adapter
+ * // 或 stores.<storeName>.adapter
  */
 export declare function createDefaultAdapter(options: DefaultAdapterOptions): DictAdapter;

package/dist/runtime/core/dict-manager.d.ts

@@ -1,5 +1,17 @@
 import { IndexedDBCache } from './cache/indexeddb-cache.js';
-import type { DictAdapter, DictEntry } from '../types/index.js';
+import type { DictAdapter, DictEntry, DictItem, TranslateOptions, TranslatePathOptions, GetDictItemOptions } from '../types/index.js';
+/**
+ * DictManager 构造参数。
+ *
+ * @example
+ * const manager = new DictManager({
+ *   adapters: new Map([['dicts', createDefaultAdapter({ ... })]),
+ *   indexedDB: new IndexedDBCache('nuxt-dict'),
+ *   memoryMax: 200,
+ *   ttl: 0,
+ *   versionStorageKey: '__NUXT_DICT_VERSION__',
+ * })
+ */
 export interface DictManagerOptions {
     /** 仓库名 → DictAdapter 映射表。至少包含默认仓库 'dicts' 的 adapter */
     adapters: Map<string, DictAdapter>;
@@ -14,6 +26,13 @@ export interface DictManagerOptions {
  *
  * 缓存策略：内存缓存 → IndexedDB 持久缓存 → 网络请求
  * 请求去重：对同一 key 的并发请求合并为单次网络调用（pendingRequests）
+ *
+ * @example
+ * // 通常由插件自动创建，无需手动实例化
+ * // 在组件中通过 useNuxtApp().$dictManager 访问
+ * const { $dictManager: manager } = useNuxtApp()
+ * const entry = await manager.getDict('gender')
+ * const label = manager.translate('gender', 'male')
  */
 export declare class DictManager {
     private memoryCache;
@@ -33,8 +52,18 @@ export declare class DictManager {
     private buildKey;
     /** 根据 storeName 获取对应的 adapter。找不到时回退到默认仓库 'dicts' 的 adapter */
     private getAdapter;
-    /** 切换语言，清空内存缓存和待处理请求 */
+    /**
+     * 切换语言，清空内存缓存和待处理请求。
+     * 语言变更后所有 useDict / useDictTree 组件通过 watch 自动重取数据。
+     *
+     * @param {string} locale - 目标语言代码，如 'zh-CN'、'en-US'
+     */
     setLocale(locale: string): void;
+    /**
+     * 获取当前语言。
+     *
+     * @returns {string} 当前语言代码，如 'zh-CN'
+     */
     getLocale(): string;
     /**
      * 惰性版本检查：首次访问该仓库时检查版本变更，按需清理缓存。
@@ -44,6 +73,10 @@ export declare class DictManager {
     /**
      * 获取字典数据。
      * 优先级：内存缓存 → 合并中的请求 → IndexedDB → 网络请求
+     *
+     * @param {string} type - 字典类型名，如 'gender'
+     * @param {string} storeName - 仓库名，默认 'dicts'
+     * @returns {Promise<DictEntry>} 包含 items 和可选 tree 的字典条目
      */
     getDict(type: string, storeName?: string): Promise<DictEntry>;
     /** 执行实际的数据获取与缓存写入 */
@@ -51,24 +84,59 @@ export declare class DictManager {
     /**
      * 强制刷新指定字典：跳过缓存，直接从网络获取最新数据。
      * 适用于用户手动刷新、数据变更通知等场景。
+     *
+     * @param {string} type - 字典类型名，如 'gender'
+     * @param {string} storeName - 仓库名，默认 'dicts'
+     * @returns {Promise<DictEntry>} 最新的字典条目
      */
     refresh(type: string, storeName?: string): Promise<DictEntry>;
-    /** 翻译 code → label，未命中时回退原样 */
-    translate(type: string, code: string | number, storeName?: string): string;
-    /** 树形字典中查找 code 的完整层级路径 */
-    translatePath(type: string, code: string | number, separator?: string, storeName?: string): string;
-    /** DFS 在树形字典中查找目标编码的路径 */
+    /**
+     * 同步翻译 value → label，未命中缓存时回退原样返回。
+     *
+     * @param {string} type - 字典类型名，如 'gender'
+     * @param {string | number} value - 字典编码值
+     * @param {TranslateOptions} opts - 可选配置（storeName 指定仓库，field 指定取值字段，默认 'label'）
+     * @returns {string} 翻译后的文本，缓存未命中时返回 value 的字符串形式
+     */
+    translate(type: string, value: string | number, opts?: TranslateOptions): string;
+    /**
+     * 从内存缓存中查找编码对应的完整字典项对象。
+     * 参数与 translate 一致，但返回整个 DictItem 而非提取字段。
+     *
+     * @param {string} type - 字典类型名，如 'gender'
+     * @param {string | number} value - 字典编码值
+     * @param {GetDictItemOptions} opts - 可选配置（storeName 指定仓库）
+     * @returns {DictItem | undefined} 完整的字典项对象，缓存未命中时返回 undefined
+     */
+    getDictItem(type: string, value: string | number, opts?: GetDictItemOptions): DictItem | undefined;
+    /**
+     * 树形字典中查找 value 的完整层级路径。
+     *
+     * @param {string} type - 字典类型名，如 'region'
+     * @param {string | number} value - 叶子节点编码值
+     * @param {TranslatePathOptions} opts - 可选配置（storeName 指定仓库，field 指定取值字段，separator 指定分隔符，默认 ' / '）
+     * @returns {string} 用分隔符连接的完整层级路径，未命中时返回 value 字符串
+     */
+    translatePath(type: string, value: string | number, opts?: TranslatePathOptions): string;
+    /** DFS 在树形字典中查找目标编码的路径，每节点取指定字段 */
     private findPathInTree;
     /**
      * code 比对 —— 统一转字符串比较。
      * 避免字典配置中数字/字符串编码不一致导致的匹配失败。
      */
     private codeMatch;
-    /** 初始化：版本检查已改为惰性执行，在首次访问仓库时触发 */
+    /**
+     * 初始化管理器。
+     * 版本检查已改为惰性执行，在首次 getDict() 调用时触发，避免全量串行请求。
+     *
+     * @returns {Promise<void>}
+     */
     initialize(): Promise<void>;
     /**
      * 失效缓存数据。
-     * @param storeName 指定要失效的存储库，不传则清空所有存储库及内存缓存
+     *
+     * @param {string} storeName - 指定要失效的仓库，不传则清空所有仓库及内存缓存
+     * @returns {Promise<void>}
      */
     invalidateAll(storeName?: string): Promise<void>;
 }