@lacqjs/nuxt-dict 0.0.2 → 0.0.4

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;

package/dist/runtime/utils/dict-translator.js

@@ -1,30 +1,103 @@
+function translate(manager, type, code, opts) {
+  return manager.translate(type, code, opts);
+}
+function translatePath(manager, type, code, opts) {
+  return manager.translatePath(type, code, opts);
+}
+function getDictItem(manager, type, code, opts) {
+  return manager.getDictItem(type, code, opts);
+}
+function translateData(manager, data, mapping, suffix) {
+  const result = { ...data };
+  for (const [key, mapValue] of Object.entries(mapping)) {
+    const code = data[key];
+    const type = typeof mapValue === "string" ? mapValue : mapValue.type;
+    const storeName = typeof mapValue === "string" ? void 0 : mapValue.storeName;
+    const translated = code !== void 0 && code !== null ? translate(manager, type, code, storeName ? { storeName } : void 0) : "";
+    result[key + suffix] = translated;
+  }
+  return result;
+}
 export function createDictTranslator(manager) {
   return {
     /**
-     * 通过字典类型和编码获取翻译文本。
-     * 2 参：默认存储库；3 参：指定存储库（storeName 为第一个参数）
+     * 同步翻译字典编码 → 文本。
+     *
+     * @description 从全局内存缓存中查找编码对应的文本，未命中时返回 code 原样。先通过 useDict 等加载数据后调用。
+     * @param {string} type - 字典类型名，如 'gender'、'status'
+     * @param {string | number} code - 字典编码值
+     * @param {TranslateOptions} [opts] - 可选配置（storeName 指定仓库，field 指定取值字段，默认 'label'）
+     * @returns {string} 翻译后的文本，缓存未命中时返回 String(code)
+     *
+     * @example
+     * $dict.translate('gender', 'male')
+     * $dict.translate('gender', 'male', { storeName: 'dicts2' })
+     * $dict.translate('status', 1, { field: 'color' })
+     */
+    translate(type, code, opts) {
+      return translate(manager, type, code, opts);
+    },
+    /**
+     * 树形字典中查找编码的完整层级路径。
+     *
+     * @description 从内存缓存中加载的树形字典数据里，通过 DFS 查找目标编码并回溯完整路径，用分隔符拼接后返回。
+     * @param {string} type - 树形字典类型名，如 'region'
+     * @param {string | number} code - 叶子节点编码值
+     * @param {TranslatePathOptions} [opts] - 可选配置（storeName 指定仓库，field 指定节点取值字段，separator 指定分隔符，默认 ' / '）
+     * @returns {string} 用分隔符连接的完整层级路径，未命中时返回 String(code)
+     *
+     * @example
+     * $dict.translatePath('region', '440104')
+     * $dict.translatePath('region', '440104', { separator: ' → ' })
+     * $dict.translatePath('region', '440104', { storeName: 'dicts2', field: 'value' })
+     */
+    translatePath(type, code, opts) {
+      return translatePath(manager, type, code, opts);
+    },
+    /**
+     * 批量翻译数据对象中的多个编码字段。
+     *
+     * @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'`，即翻译结果追加到 `原字段名 + suffix` 字段
+     * @returns {Record<string, unknown>} 新对象，包含原数据所有字段 + 以 suffix 为后缀的翻译字段
+     *
+     * @example
+     * $dict.translateData(
+     *   { gender: 'male', status: 1, name: '张三' },
+     *   { gender: 'gender', status: 'status' }
+     * )
+     * // → { gender: 'male', gender_label: '男', status: 1, status_label: '启用', name: '张三' }
+     *
+     * // 跨仓库 + 自定义后缀
+     * $dict.translateData(
+     *   { payStatus: 1 },
+     *   { payStatus: { type: 'pay_status', storeName: 'payment' } },
+     *   '_text'
+     * )
+     * // → { payStatus: 1, payStatus_text: '已支付' }
      */
-    translate(storeOrType, codeOrType, code) {
-      if (code !== void 0) {
-        return manager.translate(codeOrType, code, storeOrType);
-      }
-      return manager.translate(storeOrType, codeOrType);
+    translateData(data, mapping, suffix = "_label") {
+      return translateData(manager, data, mapping, suffix);
     },
     /**
-     * 获取树形字典中某个编码的完整层级路径。
-     * 2 参：默认存储库 + 默认分隔符
-     * 3 参：指定存储库 + 默认分隔符（storeName 为第一个参数）
-     * 4 参：指定存储库 + 自定义分隔符
-     * 默认存储库 + 自定义分隔符需显式传 'dicts' 作为 storeName
+     * 从内存缓存中查找编码对应的完整字典项对象。
+     *
+     * @description 与 translate 参数一致，但返回整个 DictItem 而非提取单个字段。缓存未命中时返回 undefined。
+     * @param {string} type - 字典类型名，如 'gender'、'status'
+     * @param {string | number} code - 字典编码值
+     * @param {GetDictItemOptions} [opts] - 可选配置（storeName 指定仓库）
+     * @returns {DictItem | undefined} 完整的字典项对象，缓存未命中时返回 undefined
+     *
+     * @example
+     * $dict.getDictItem('gender', 'male')
+     * // → { value: 'male', label: '男' }
+     * $dict.getDictItem('gender', 'male', { storeName: 'dicts2' })
+     * // → { value: 'male', label: '男（源2）' }
      */
-    translatePath(storeOrType, codeOrType, separatorOrCode, separator) {
-      if (separator !== void 0) {
-        return manager.translatePath(codeOrType, separatorOrCode, separator, storeOrType);
-      }
-      if (separatorOrCode !== void 0) {
-        return manager.translatePath(codeOrType, separatorOrCode, void 0, storeOrType);
-      }
-      return manager.translatePath(storeOrType, codeOrType);
+    getDictItem(type, code, opts) {
+      return getDictItem(manager, type, code, opts);
     }
   };
 }

package/dist/types.d.mts

@@ -1,3 +1,7 @@
-export { type ModuleOptions } from '../dist/runtime/types/index.js'
+export { type DictItem, type DictTranslator, type GetDictItemOptions, type ModuleOptions, type TranslateOptions, type TranslatePathOptions, type TreeNode } from '../dist/runtime/types/index.js'
+
+export { type DictManager } from '../dist/runtime/core/dict-manager.js'
+
+export { type createDictTranslator } from '../dist/runtime/utils/dict-translator.js'
 
 export { default } from './module.mjs'

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@lacqjs/nuxt-dict",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Nuxt 数据字典模块，提供扁平/树形字典翻译、多语言国际化、三级缓存与 SSR 预取。",
   "keywords": [
     "@lacqjs/nuxt-dict",
+    "dict",
     "nuxt",
-    "nuxt-dict",
-    "dict"
+    "nuxt-dict"
   ],
+  "homepage": "https://miaozhongfei.github.io/nuxt-dict/",
   "license": "MIT",
   "author": {
-    "name": "miaozf",
-    "email": "miaozf@example.com"
+    "name": "miaozhongfei",
+    "email": "miaozhongfei@example.com"
   },
   "contributors": [],
+  "repository": "miaozhongfei/nuxt-dict",
   "files": [
     "dist"
   ],
@@ -64,6 +66,7 @@
     "pnpm": ">=10.22.0",
     "yarn": ">=1.22.22"
   },
+  "documentation": "https://miaozhongfei.github.io/nuxt-dict/",
   "scripts": {
     "cleanup": "pnpx nuxt cleanup || npx nuxt cleanup",
     "clean:install": "pnpm run cleanup && pnpm run docs:cleanup && pnpm run playground:cleanup && pnpm install",
@@ -72,12 +75,14 @@
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
     "docs:dev": "nuxi dev docs",
     "docs:build": "nuxi build docs",
-    "docs:cleanup": "pnpx rimraf docs/.nuxt docs/.output docs/dist docs/node_modules",
+    "docs:generate": "nuxi generate docs",
+    "docs:cleanup": "pnpx rimraf docs/.nuxt docs/.output docs/dist docs/node_modules docs/.data",
     "playground:cleanup": "pnpx rimraf playground/.nuxt playground/.output playground/dist playground/node_modules",
-    "release": "pnpm lint && pnpm typecheck && pnpm prepack && changelogen --release && pnpm publish && git push --follow-tags",
-    "release:major": "pnpm lint && pnpm typecheck && pnpm prepack && changelogen --release --major && pnpm publish && git push --follow-tags",
-    "release:e2e": "pnpm lint && pnpm e2e && pnpm typecheck && pnpm prepack && changelogen --release && pnpm publish && git push --follow-tags",
-    "release:e2e:major": "pnpm lint && pnpm e2e && pnpm typecheck && pnpm prepack && changelogen --release --major && pnpm publish && git push --follow-tags",
+    "demo:base-api:dev": "nuxi dev examples/demo-base-api",
+    "release": "pnpm lint && pnpm typecheck && pnpm prepack && changelogen --release && pnpm publish && git push origin dev --follow-tags",
+    "release:major": "pnpm lint && pnpm typecheck && pnpm prepack && changelogen --release --major && pnpm publish && git push origin dev --follow-tags",
+    "release:e2e": "pnpm lint && pnpm e2e && pnpm typecheck && pnpm prepack && changelogen --release && pnpm publish && git push origin dev --follow-tags",
+    "release:e2e:major": "pnpm lint && pnpm e2e && pnpm typecheck && pnpm prepack && changelogen --release --major && pnpm publish && git push origin dev --follow-tags",
     "lint": "oxlint . && oxlint docs --no-error-on-unmatched-pattern",
     "lint:fix": "oxlint --fix . && oxlint --fix docs --no-error-on-unmatched-pattern",
     "fmt": "oxfmt",

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

@@ -1,13 +0,0 @@
-import type { UseDictOptionsReturn, StoreKey } from '../types/index.js';
-/**
- * 以 { label, value } 格式使用字典数据，
- * 直接适配 UI 库的 options 属性。
- *
- * @example
- * // 默认存储库 'dicts'
- * const { options } = useDictOptions('industry')
- * // 指定存储库 'dicts2'
- * const { options } = useDictOptions('dicts2', 'industry')
- */
-export declare function useDictOptions(type: string): UseDictOptionsReturn;
-export declare function useDictOptions(storeName: StoreKey, type: string): UseDictOptionsReturn;

package/dist/runtime/composables/useDictOptions.js

@@ -1,17 +0,0 @@
-import { computed } from "vue";
-import { useDict } from "./useDict.js";
-export function useDictOptions(storeOrType, maybeType) {
-  const { data, loading, refresh } = maybeType === void 0 ? useDict(storeOrType) : useDict(storeOrType, maybeType);
-  const options = computed(() => {
-    if (!data.value) return [];
-    return data.value.map((item) => ({
-      label: item.label,
-      value: item.code
-    }));
-  });
-  return {
-    options,
-    loading,
-    refresh
-  };
-}