@lacqjs/nuxt-dict 0.0.2 → 0.0.3

package/dist/runtime/core/dict-manager.js

@@ -34,7 +34,12 @@ export class DictManager {
   getAdapter(storeName) {
     return this.adapters.get(storeName) ?? this.adapters.get(DEFAULT_STORE_NAME);
   }
-  /** 切换语言，清空内存缓存和待处理请求 */
+  /**
+   * 切换语言，清空内存缓存和待处理请求。
+   * 语言变更后所有 useDict / useDictTree 组件通过 watch 自动重取数据。
+   *
+   * @param {string} locale - 目标语言代码，如 'zh-CN'、'en-US'
+   */
   setLocale(locale) {
     if (this.locale.value !== locale) {
       this.locale.value = locale;
@@ -42,6 +47,11 @@ export class DictManager {
       this.pendingRequests.clear();
     }
   }
+  /**
+   * 获取当前语言。
+   *
+   * @returns {string} 当前语言代码，如 'zh-CN'
+   */
   getLocale() {
     return this.locale.value;
   }
@@ -79,6 +89,10 @@ export class DictManager {
   /**
    * 获取字典数据。
    * 优先级：内存缓存 → 合并中的请求 → IndexedDB → 网络请求
+   *
+   * @param {string} type - 字典类型名，如 'gender'
+   * @param {string} storeName - 仓库名，默认 'dicts'
+   * @returns {Promise<DictEntry>} 包含 items 和可选 tree 的字典条目
    */
   async getDict(type, storeName = DEFAULT_STORE_NAME) {
     await this.ensureVersionChecked(storeName);
@@ -134,6 +148,10 @@ export class DictManager {
   /**
    * 强制刷新指定字典：跳过缓存，直接从网络获取最新数据。
    * 适用于用户手动刷新、数据变更通知等场景。
+   *
+   * @param {string} type - 字典类型名，如 'gender'
+   * @param {string} storeName - 仓库名，默认 'dicts'
+   * @returns {Promise<DictEntry>} 最新的字典条目
    */
   async refresh(type, storeName = DEFAULT_STORE_NAME) {
     const key = this.buildKey(type, storeName);
@@ -160,32 +178,68 @@ export class DictManager {
     }
     return entry;
   }
-  /** 翻译 code → label，未命中时回退原样 */
-  translate(type, code, storeName = DEFAULT_STORE_NAME) {
+  /**
+   * 同步翻译 value → label，未命中缓存时回退原样返回。
+   *
+   * @param {string} type - 字典类型名，如 'gender'
+   * @param {string | number} value - 字典编码值
+   * @param {TranslateOptions} opts - 可选配置（storeName 指定仓库，field 指定取值字段，默认 'label'）
+   * @returns {string} 翻译后的文本，缓存未命中时返回 value 的字符串形式
+   */
+  translate(type, value, opts) {
+    const storeName = opts?.storeName ?? DEFAULT_STORE_NAME;
+    const field = opts?.field ?? "label";
     const key = this.buildKey(type, storeName);
     const entry = this.memoryCache.get(key);
-    if (!entry) return String(code);
-    const item = entry.data.items.find((i) => this.codeMatch(i.code, code));
-    return item?.label ?? String(code);
+    if (!entry) return String(value);
+    const item = entry.data.items.find((i) => this.codeMatch(i.value, value));
+    if (!item) return String(value);
+    return item[field] ?? item.label;
   }
-  /** 树形字典中查找 code 的完整层级路径 */
-  translatePath(type, code, separator = " / ", storeName = DEFAULT_STORE_NAME) {
+  /**
+   * 从内存缓存中查找编码对应的完整字典项对象。
+   * 参数与 translate 一致，但返回整个 DictItem 而非提取字段。
+   *
+   * @param {string} type - 字典类型名，如 'gender'
+   * @param {string | number} value - 字典编码值
+   * @param {GetDictItemOptions} opts - 可选配置（storeName 指定仓库）
+   * @returns {DictItem | undefined} 完整的字典项对象，缓存未命中时返回 undefined
+   */
+  getDictItem(type, value, opts) {
+    const storeName = opts?.storeName ?? DEFAULT_STORE_NAME;
     const key = this.buildKey(type, storeName);
     const entry = this.memoryCache.get(key);
-    if (!entry || !entry.data.tree) return String(code);
-    const path = this.findPathInTree(entry.data.tree, code);
-    return path.length > 0 ? path.join(separator) : String(code);
+    if (!entry) return void 0;
+    return entry.data.items.find((i) => this.codeMatch(i.value, value));
   }
-  /** DFS 在树形字典中查找目标编码的路径 */
-  findPathInTree(nodes, targetCode) {
+  /**
+   * 树形字典中查找 value 的完整层级路径。
+   *
+   * @param {string} type - 字典类型名，如 'region'
+   * @param {string | number} value - 叶子节点编码值
+   * @param {TranslatePathOptions} opts - 可选配置（storeName 指定仓库，field 指定取值字段，separator 指定分隔符，默认 ' / '）
+   * @returns {string} 用分隔符连接的完整层级路径，未命中时返回 value 字符串
+   */
+  translatePath(type, value, opts) {
+    const storeName = opts?.storeName ?? DEFAULT_STORE_NAME;
+    const field = opts?.field ?? "label";
+    const separator = opts?.separator ?? " / ";
+    const key = this.buildKey(type, storeName);
+    const entry = this.memoryCache.get(key);
+    if (!entry || !entry.data.tree) return String(value);
+    const path = this.findPathInTree(entry.data.tree, value, field);
+    return path.length > 0 ? path.join(separator) : String(value);
+  }
+  /** DFS 在树形字典中查找目标编码的路径，每节点取指定字段 */
+  findPathInTree(nodes, targetCode, field) {
     for (const node of nodes) {
-      if (this.codeMatch(node.code, targetCode)) {
-        return [node.label];
+      if (this.codeMatch(node.value, targetCode)) {
+        return [node[field] ?? node.label];
       }
       if (node.children && node.children.length > 0) {
-        const childPath = this.findPathInTree(node.children, targetCode);
+        const childPath = this.findPathInTree(node.children, targetCode, field);
         if (childPath.length > 0) {
-          return [node.label, ...childPath];
+          return [node[field] ?? node.label, ...childPath];
         }
       }
     }
@@ -198,12 +252,19 @@ export class DictManager {
   codeMatch(a, b) {
     return String(a) === String(b);
   }
-  /** 初始化：版本检查已改为惰性执行，在首次访问仓库时触发 */
+  /**
+   * 初始化管理器。
+   * 版本检查已改为惰性执行，在首次 getDict() 调用时触发，避免全量串行请求。
+   *
+   * @returns {Promise<void>}
+   */
   async initialize() {
   }
   /**
    * 失效缓存数据。
-   * @param storeName 指定要失效的存储库，不传则清空所有存储库及内存缓存
+   *
+   * @param {string} storeName - 指定要失效的仓库，不传则清空所有仓库及内存缓存
+   * @returns {Promise<void>}
    */
   async invalidateAll(storeName) {
     if (storeName) {

package/dist/runtime/types/index.d.ts

@@ -1,11 +1,34 @@
-import type { ShallowRef, Ref, ComputedRef } from 'vue';
+import type { ShallowRef, Ref, DeepReadonly } from 'vue';
 /** 仓库名字面量联合类型，由 addTypeTemplate 根据 stores 配置动态生成 */
 import type { StoreKey } from '#build/types/nuxt-dict-store-names';
 export type { StoreKey };
-/** 字典项 */
+/**
+ * 字典项，表示字典中单个编码与其显示文本的映射关系。
+ *
+ * @description 扁平字典的最小数据单元。每个 DictItem 包含一个编码值（value）
+ * 和对应的显示文本（label），并可携带任意扩展字段（如 color、icon 等）。
+ * 用于 useDict 返回的 data、$dict.getDictItem 的返回值等场景。
+ *
+ * @property {string | number} value - 字典编码值，支持字符串和数字类型，用于匹配业务数据中的 code
+ * @property {string} label - 编码对应的显示文本（翻译后的文字）
+ *
+ * @example
+ * // 基础条目
+ * { value: 'male', label: '男' }
+ * { value: 1, label: '启用', color: '#67C23A' }
+ *
+ * @example
+ * // 通过 $dict.getDictItem 获取完整对象
+ * import type { DictItem } from '@lacqjs/nuxt-dict'
+ * const item:DictItem = $dict.getDictItem('gender', 'male')
+ * // item.value → 'male', item.label → '男'
+ */
 export interface DictItem {
-    code: string | number;
+    /** 字典编码值，支持字符串和数字类型 */
+    value: string | number;
+    /** 编码对应的显示文本 */
     label: string;
+    /** 允许携带任意扩展字段（如 color、icon 等） */
     [key: string]: unknown;
 }
 /** 树形字典节点，用于级联选择器 */
@@ -29,7 +52,23 @@ export interface CacheEntry<T = DictEntry> {
     timestamp: number;
     version: string;
 }
-/** 字典适配器接口，允许用户自定义数据源（REST / GraphQL / 本地文件等） */
+/**
+ * 字典适配器接口，允许用户自定义数据源（REST / GraphQL / 本地文件等）。
+ *
+ * @example
+ * // 自定义适配器示例
+ * const customAdapter: DictAdapter = {
+ *   fetchDict: async (storeName, { types, locale }) => {
+ *     const res = await fetch(`/api/${storeName}/dict?types=${types.join(',')}&lang=${locale}`)
+ *     return res.json()
+ *   },
+ *   fetchVersion: async (storeName) => {
+ *     const res = await fetch(`/api/${storeName}/dict/version`)
+ *     const data = await res.json()
+ *     return data.version
+ *   },
+ * }
+ */
 export interface DictAdapter {
     fetchDict(storeName: string, options: {
         types: string[];
@@ -144,28 +183,272 @@ export interface ResolvedModuleOptions {
         storageKey: string;
     };
 }
-/** useDict 返回类型 */
+/**
+ * translate / translatePath 使用的选项。
+ *
+ * @example
+ * // 默认仓库，取 label
+ * translate('gender', 'male')
+ * // 指定仓库
+ * translate('gender', 'male', { storeName: 'dicts2' })
+ * // 取自定义字段
+ * translate('status', 1, { field: 'color' })
+ */
+export interface TranslateOptions {
+    /** 仓库名，默认 'dicts' */
+    storeName?: StoreKey;
+    /** 取值字段名，默认 'label' */
+    field?: string;
+}
+/**
+ * translatePath 使用的选项，在 TranslateOptions 基础上增加 separator。
+ *
+ * @example
+ * // 默认仓库，默认分隔符 ' / '
+ * translatePath('region', '440104')
+ * // 自定义分隔符
+ * translatePath('region', '440104', { separator: ' → ' })
+ * // 指定仓库 + 自定义字段 + 自定义分隔符
+ * translatePath('region', '440104', { storeName: 'dicts2', field: 'value', separator: ' → ' })
+ */
+export interface TranslatePathOptions extends TranslateOptions {
+    /** 层级路径分隔符，默认 ' / ' */
+    separator?: string;
+}
+/**
+ * getDictItem 使用的选项。与 translate 参数一致，但不含 field（返回整个对象）。
+ *
+ * @example
+ * // 默认仓库
+ * getDictItem('gender', 'male')
+ * // 指定仓库
+ * getDictItem('gender', 'male', { storeName: 'dicts2' })
+ */
+export interface GetDictItemOptions {
+    /** 仓库名，默认 'dicts' */
+    storeName?: StoreKey;
+}
+/**
+ * useDict 返回类型。
+ *
+ * @description useDict 调用后返回的对象，包含字典数据、翻译函数、状态管理和刷新能力。
+ * 组件挂载时自动加载数据，卸载时自动清理。支持语言切换后自动重取。
+ *
+ * @property {Readonly<ShallowRef<DeepReadonly<DictItem[] | null>>>} data - 字典原始数据数组（只读）。初始为 null，加载完成后为 [{ value, label, ... }]
+ * @property {(value: string | number, opts?: TranslateOptions) => string} translate - 同步翻译函数，默认从 data ref 查找 code → label（响应式），未命中返回 code 原文
+ * @property {(value: string | number, opts?: GetDictItemOptions) => DictItem | undefined} getDictItem - 同步获取完整字典项对象，缓存未命中返回 undefined
+ * @property {Ref<boolean>} loading - 是否正在加载字典数据
+ * @property {Ref<string | null>} error - 加载失败时的错误信息，正常时为 null
+ * @property {() => Promise<void>} refresh - 强制刷新，跳过缓存直接从网络获取最新数据
+ *
+ * @example
+ * const { data, translate, loading, refresh } = useDict('gender')
+ * const { data, translate } = useDict('dicts2', 'gender')
+ */
 export interface UseDictReturn {
-    data: ShallowRef<DictItem[] | null>;
-    translate: (code: string | number) => string;
+    /** 字典原始数据数组（只读）。初始为 null，加载完成后为 [{ value, label, ... }] */
+    data: Readonly<ShallowRef<DeepReadonly<DictItem[] | null>>>;
+    /**
+     * 同步翻译编码 → 文本，默认从 data ref（shallowRef）查找，Vue 响应式系统可追踪。
+     *
+     * @description 从当前 useDict 的 data ref 中查找编码对应的翻译文本。
+     * 同步执行，不发起网络请求。可放在 computed 中使用。
+     * @param {string | number} value - 字典编码值
+     * @param {TranslateOptions} [opts] - 可选配置
+     * @param {StoreKey} [opts.storeName] - 仓库名。同仓库从 data ref 读取（响应式），跨仓库回退 manager 内存缓存
+     * @param {string} [opts.field] - 取值字段名，默认 'label'
+     * @returns {string} 翻译后的文本，缓存未命中时返回 value 的字符串形式
+     *
+     * @example
+     * const { translate } = useDict('gender')
+     * translate('male')              // → '男'
+     * translate(1, { field: 'color' }) // 取自定义字段
+     */
+    translate: (value: string | number, opts?: TranslateOptions) => string;
+    /**
+     * 同步获取完整字典项对象，默认从 data ref（shallowRef）中查找，Vue 响应式系统可追踪。
+     *
+     * @description 与 translate 参数一致，但返回整个 DictItem 对象而非提取字符串字段。
+     * 可获取 value、label、以及 color 等扩展属性。可放在 computed 中使用。
+     * @param {string | number} value - 字典编码值
+     * @param {GetDictItemOptions} [opts] - 可选配置
+     * @param {StoreKey} [opts.storeName] - 目标仓库名。同仓库从 data ref 读取（响应式），跨仓库回退 manager 内存缓存
+     * @returns {DictItem | undefined} 完整的字典项对象，缓存未命中时返回 undefined
+     *
+     * @example
+     * const { getDictItem } = useDict('status')
+     * const item = computed(() => getDictItem(1))  // 响应式 ✅
+     * // → { value: 1, label: '启用', color: '#67C23A' }
+     */
+    getDictItem: (value: string | number, opts?: GetDictItemOptions) => DictItem | undefined;
+    /** 是否正在加载字典数据 */
     loading: Ref<boolean>;
+    /** 加载失败时的错误信息，正常时为 null */
     error: Ref<string | null>;
+    /**
+     * 强制刷新字典数据。
+     *
+     * @description 跳过内存缓存和 IndexedDB，直接从网络获取最新数据并更新缓存。
+     * 适用于后端通知字典更新后手动触发。
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const { refresh } = useDict('gender')
+     * await refresh()  // 强制重新拉取最新数据
+     */
     refresh: () => Promise<void>;
 }
-/** useDictOptions 返回类型 */
-export interface UseDictOptionsReturn {
-    options: ComputedRef<{
-        label: string;
-        value: string | number;
-    }[]>;
-    loading: Ref<boolean>;
-    refresh: () => Promise<void>;
+/**
+ * $dict 翻译器对象类型，暴露同步翻译和批量翻译方法。
+ *
+ * @description 注入到 NuxtApp 和 Vue 组件的全局翻译器，从内存缓存中查找已加载的字典数据。
+ * 仓库名统一通过 opts.storeName 或 mapping 中指定，不接受首参为 storeName 的旧式写法。
+ *
+ * @property {(type: string, code: string | number, opts?: TranslateOptions) => string} translate - 同步翻译编码 → 文本，未命中返回 code 原文
+ * @property {(type: string, code: string | number, opts?: TranslatePathOptions) => string} translatePath - 树形字典编码 → 层级路径，用分隔符拼接
+ * @property {(data, mapping, suffix?) => Record<string, unknown>} translateData - 批量翻译对象中的多个编码字段，返回追加了翻译字段的新对象
+ * @property {(type: string, code: string | number, opts?: GetDictItemOptions) => DictItem | undefined} getDictItem - 获取完整字典项对象，缓存未命中返回 undefined
+ *
+ * @example
+ * $dict.translate('gender', 'male')
+ * $dict.translate('gender', 'male', { storeName: 'dicts2' })
+ * $dict.translatePath('region', '440104', { separator: ' → ' })
+ * $dict.translateData({ gender: 'male', status: 1 }, { gender: 'gender', status: 'status' })
+ * $dict.getDictItem('gender', 'male')
+ */
+export interface DictTranslator {
+    /**
+     * 同步翻译编码 → 文本，从内存缓存查找。
+     *
+     * @description 从全局内存缓存中查找编码对应的翻译文本。需先通过 useDict 加载数据后调用。
+     * @param {string} type - 字典类型名，如 'gender'、'status'
+     * @param {string | number} code - 字典编码值
+     * @param {TranslateOptions} [opts] - 可选配置
+     * @param {StoreKey} [opts.storeName] - 仓库名，默认 'dicts'
+     * @param {string} [opts.field] - 取值字段名，默认 'label'
+     * @returns {string} 翻译后的文本，缓存未命中时返回 code 的字符串形式
+     *
+     * @example
+     * $dict.translate('gender', 'male')
+     * $dict.translate('gender', 'male', { storeName: 'dicts2' })
+     * $dict.translate('status', 1, { field: 'color' })
+     */
+    translate(type: string, code: string | number, opts?: TranslateOptions): string;
+    /**
+     * 树形字典编码 → 层级路径，从内存缓存查找。
+     *
+     * @description 从已加载的树形字典数据中通过 DFS 查找目标编码并回溯完整路径，用分隔符拼接。
+     * @param {string} type - 树形字典类型名，如 'region'
+     * @param {string | number} code - 叶子节点编码值
+     * @param {TranslatePathOptions} [opts] - 可选配置
+     * @param {StoreKey} [opts.storeName] - 仓库名，默认 'dicts'
+     * @param {string} [opts.field] - 节点取值字段名，默认 'label'
+     * @param {string} [opts.separator] - 层级分隔符，默认 ' / '
+     * @returns {string} 用分隔符连接的完整层级路径，缓存未命中时返回 code 的字符串形式
+     *
+     * @example
+     * $dict.translatePath('region', '440104')
+     * $dict.translatePath('region', '440104', { separator: ' → ' })
+     */
+    translatePath(type: string, code: string | number, opts?: TranslatePathOptions): string;
+    /**
+     * 批量翻译数据对象中的多个编码字段。
+     *
+     * @description 传入一个数据对象和字段 → 字典类型映射表，返回追加了翻译字段的新对象（不修改原对象）。
+     * @param {Record<string, unknown>} data - 需要翻译的数据对象，如 { gender: 'male', status: 1 }
+     * @param {Record<string, string | { type: string; storeName?: StoreKey }>} mapping - 字段映射表。key 为原字段名，value 为字典类型 string（默认仓库）或 { type, storeName? } 对象（指定仓库）
+     * @param {string} [suffix='_label'] - 翻译字段的后缀，如 '_label' → gender_label
+     * @returns {Record<string, unknown>} 新对象，包含原数据所有字段 + 追加的翻译字段
+     *
+     * @example
+     * $dict.translateData(
+     *   { gender: 'male', status: 1 },
+     *   { gender: 'gender', status: 'status' }
+     * )
+     * // → { gender: 'male', gender_label: '男', status: 1, status_label: '启用' }
+     */
+    translateData(data: Record<string, unknown>, mapping: Record<string, string | {
+        type: string;
+        storeName?: StoreKey;
+    }>, suffix?: string): Record<string, unknown>;
+    /**
+     * 同步获取完整字典项对象，从内存缓存查找。
+     *
+     * @description 与 translate 参数一致，但返回整个 DictItem 对象而非提取字符串字段。
+     * 可获取 value、label、以及 color 等扩展属性。
+     * @param {string} type - 字典类型名，如 'gender'、'status'
+     * @param {string | number} code - 字典编码值
+     * @param {GetDictItemOptions} [opts] - 可选配置
+     * @param {StoreKey} [opts.storeName] - 仓库名，默认 'dicts'
+     * @returns {DictItem | undefined} 完整的字典项对象，缓存未命中时返回 undefined
+     *
+     * @example
+     * $dict.getDictItem('gender', 'male')
+     * // → { value: 'male', label: '男' }
+     * $dict.getDictItem('status', 1, { storeName: 'dicts2' })
+     * // → { value: 1, label: '启用', color: '#67C23A' }
+     */
+    getDictItem(type: string, code: string | number, opts?: GetDictItemOptions): DictItem | undefined;
 }
-/** useDictTree 返回类型 */
+/**
+ * useDictTree 返回类型。
+ *
+ * @description useDictTree 调用后返回的对象，包含树形字典数据、翻译函数、路径回溯和刷新能力。
+ * 适用于级联选择器等需要层级数据的场景。支持语言切换后自动重取。
+ *
+ * @property {Readonly<ShallowRef<DeepReadonly<TreeNode[] | null>>>} tree - 树形字典节点数组（只读）。初始为 null，加载完成后为完整树结构
+ * @property {(value: string | number, opts?: TranslateOptions) => string} translate - 同步翻译树中任意节点的 value → label，默认从 tree ref 查找（响应式）
+ * @property {(value: string | number) => string[]} findPath - 查找叶子节点的完整层级路径，从 tree ref 查找（响应式），如 code=440104 → ['广东', '广州', '越秀区']
+ * @property {Ref<boolean>} loading - 是否正在加载树形字典数据
+ * @property {() => Promise<void>} refresh - 强制刷新，跳过缓存直接从网络获取最新数据
+ *
+ * @example
+ * const { tree, translate, findPath, loading, refresh } = useDictTree('region')
+ * const { tree, translate } = useDictTree('dicts2', 'region')
+ */
 export interface UseDictTreeReturn {
-    tree: ShallowRef<TreeNode[] | null>;
-    translate: (code: string | number) => string;
-    findPath: (code: string | number) => string[];
+    /** 树形字典节点数组（只读）。初始为 null，加载完成后为完整树结构 */
+    tree: Readonly<ShallowRef<DeepReadonly<TreeNode[] | null>>>;
+    /**
+     * 同步翻译树中任意节点的 value → label，默认从 tree ref（shallowRef）递归查找。
+     *
+     * @description 从当前 useDictTree 的 tree ref 中递归查找节点编码对应的翻译文本，
+     * Vue 响应式系统可追踪，可直接放在 computed 中使用。跨仓库时回退 manager 内存缓存。
+     * @param {string | number} value - 节点编码值
+     * @param {TranslateOptions} [opts] - 可选配置
+     * @param {StoreKey} [opts.storeName] - 仓库名。同仓库从 tree ref 读取（响应式），跨仓库回退 manager
+     * @param {string} [opts.field] - 取值字段名，默认 'label'
+     * @returns {string} 翻译后的文本，缓存未命中时返回 value 的字符串形式
+     *
+     * @example
+     * const { translate } = useDictTree('region')
+     * translate('440104')  // → '越秀区'
+     */
+    translate: (value: string | number, opts?: TranslateOptions) => string;
+    /**
+     * 查找叶子节点的完整层级路径，从 tree ref（shallowRef）查找，已为响应式。
+     *
+     * @description 在已加载的树形字典数据（tree ref）中递归查找目标编码，回溯从根到叶的完整路径。
+     * Vue 响应式系统可追踪，可直接放在 computed 中使用。
+     * @param {string | number} value - 叶子节点编码值
+     * @returns {string[]} 从根到叶的 label 数组，如 ['广东', '广州', '越秀区']，未找到返回空数组
+     *
+     * @example
+     * const { findPath } = useDictTree('region')
+     * findPath('440104')  // → ['广东', '广州', '越秀区']
+     */
+    findPath: (value: string | number) => string[];
+    /** 是否正在加载树形字典数据 */
     loading: Ref<boolean>;
+    /**
+     * 强制刷新树形字典数据。
+     *
+     * @description 跳过内存缓存和 IndexedDB，直接从网络获取最新树形数据并更新缓存。
+     * @returns {Promise<void>}
+     *
+     * @example
+     * const { refresh } = useDictTree('region')
+     * await refresh()  // 强制重新拉取最新数据
+     */
     refresh: () => Promise<void>;
 }

package/dist/runtime/utils/dict-translator.d.ts

@@ -1,34 +1,32 @@
 import type { DictManager } from '../core/dict-manager.js';
+import type { DictTranslator } from '../types/index.js';
 /**
- * 创建字典翻译器，封装 translate / translatePath 方法。
+ * 创建字典翻译器，封装 translate / translatePath / translateData 方法。
  * 作为 $dict 注入到 NuxtApp，供组件直接调用翻译。
  * 使用包装层而非直接暴露 DictManager，以控制公开 API 范围。
  *
+ * 仓库名统一通过 opts.storeName 指定，不再接受首参为 storeName 的旧式写法。
+ *
+ * @param {DictManager} manager - 字典管理器实例，提供底层 translate 能力
+ * @returns {DictTranslator} 翻译器对象，含 translate / translatePath / translateData 方法
+ *
  * @example
  * // 默认存储库 'dicts'
- * $dict.translate('gender', code)
- * $dict.translatePath('region', code)
+ * $dict.translate('gender', value)
+ * $dict.translatePath('region', value)
+ *
+ * // 指定存储库 + 自定义字段
+ * $dict.translate('gender', value, { storeName: 'dicts2', field: 'name' })
+ * $dict.translatePath('region', value, { storeName: 'dicts2', field: 'value', separator: ' -> ' })
  *
- * // 指定存储库，storeName 作为第一个参数
- * $dict.translate('dicts2', 'gender', code)
- * $dict.translatePath('dicts2', 'region', code)
- * $dict.translatePath('dicts2', 'region', code, ' -> ')
+ * // 默认存储库 + 自定义字段
+ * $dict.translate('gender', value, { field: 'name' })
  *
- * // 注意：默认存储库 + 自定义分隔符需显式传 storeName
- * $dict.translatePath('dicts', 'region', code, ' -> ')
+ * // 批量翻译数据对象中的字段
+ * $dict.translateData(
+ *   { gender: 'male', status: 1 },
+ *   { gender: 'gender', status: 'status' }
+ * )
+ * // → { gender: 'male', gender_label: '男', status: 1, status_label: '启用' }
  */
-export declare function createDictTranslator(manager: DictManager): {
-    /**
-     * 通过字典类型和编码获取翻译文本。
-     * 2 参：默认存储库；3 参：指定存储库（storeName 为第一个参数）
-     */
-    translate(storeOrType: string, codeOrType: string | number, code?: string | number): string;
-    /**
-     * 获取树形字典中某个编码的完整层级路径。
-     * 2 参：默认存储库 + 默认分隔符
-     * 3 参：指定存储库 + 默认分隔符（storeName 为第一个参数）
-     * 4 参：指定存储库 + 自定义分隔符
-     * 默认存储库 + 自定义分隔符需显式传 'dicts' 作为 storeName
-     */
-    translatePath(storeOrType: string, codeOrType: string | number, separatorOrCode?: string | number, separator?: string): string;
-};
+export declare function createDictTranslator(manager: DictManager): DictTranslator;