@lacqjs/nuxt-dict 0.0.2 → 0.0.4

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,79 @@
+<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.4",
   "configKey": "dict",
   "compatibility": {
     "nuxt": "^4.4.8"

package/dist/module.mjs

@@ -1,10 +1,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.4";
 const devDependencies = {
 	nuxt: "^4.4.8"};
 const pkg = {
@@ -15,17 +15,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({
@@ -58,11 +180,10 @@ const module$1 = defineNuxtModule().with({
       return;
     }
     const resolver = createResolver(import.meta.url);
-    const runtimeDir = fileURLToPath(new URL("./runtime", import.meta.url));
     _nuxt.options.runtimeConfig.public.dict = _options;
-    _nuxt.options.build.transpile.push(resolver.resolve(runtimeDir));
-    addPlugin({ src: resolver.resolve(runtimeDir, "plugins", "dict.ts") });
-    addImportsDir(resolver.resolve(runtimeDir, "composables"));
+    _nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
+    addPlugin(resolver.resolve("./runtime/plugins/dict"));
+    addImportsDir(resolver.resolve("./runtime/composables"));
     registerTypeTemplates(resolver, _options.stores);
     _nuxt.hook("prepare:types", ({ references }) => {
       references.push({ types: pkg.name });

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,48 @@ 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,25 +40,29 @@ 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;
     }
   }
   onMounted(load);
   watch(() => manager.locale.value, load);
-  return { tree, translate, findPath, loading, refresh };
+  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/adapter.js

@@ -20,7 +20,9 @@ async function fetchDictImpl(_storeName, config, types, locale) {
     }
     return response.json();
   } catch (e) {
-    throw new Error(`Failed to fetch dictionary: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    throw new Error(`Failed to fetch dictionary: ${e instanceof Error ? e.message : String(e)}`, {
+      cause: e
+    });
   }
 }
 async function fetchVersionImpl(_storeName, config) {
@@ -36,7 +38,9 @@ async function fetchVersionImpl(_storeName, config) {
     }
     return data.version;
   } catch (e) {
-    throw new Error(`Failed to fetch version: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    throw new Error(`Failed to fetch version: ${e instanceof Error ? e.message : String(e)}`, {
+      cause: e
+    });
   }
 }
 export function createDefaultAdapter(options) {

package/dist/runtime/core/cache/indexeddb-cache.js

@@ -27,7 +27,9 @@ export class IndexedDBCache {
         resolve();
       });
       request.addEventListener("error", () => {
-        reject(new Error("Failed to open IndexedDB: " + (request.error?.message || "unknown error")));
+        reject(
+          new Error("Failed to open IndexedDB: " + (request.error?.message || "unknown error"))
+        );
       });
       request.addEventListener("blocked", () => {
         reject(new Error("IndexedDB is blocked by another tab"));