zmdms-utils 0.0.85 → 0.0.87

package/dist/es/file.d.ts

@@ -99,11 +99,15 @@ interface IDownloadOptions extends IOptions {
     waterMark?: boolean | string;
     /** 是否开发不需要登录信息 */
     open?: boolean;
+    /** 是否解析异常blob结果 */
+    parseErrorBlob?: boolean;
 }
 interface IBatchDownloadOptions extends IOptions {
     zipName: string;
     /** 是否添加水印 */
     waterMark?: boolean | string;
+    /** 是否解析异常blob结果 */
+    parseErrorBlob?: boolean;
 }
 interface IDownloadLinkOptions extends Partial<IOptions> {
     /** 不需要登录信息的附件下载链接 */
@@ -124,5 +128,14 @@ interface IThumbnailLinkOptions extends Partial<IOptions> {
     /** 缩放比例 */
     scale?: number;
 }
+/**
+ * 加密附件ID
+ * @param fileId 附件ID
+ * @description 加密方式
+ * 1. 都会通过encrypt加密一次
+ * 2. 如果参数是通过地址栏传输的，附件预览：encode一次；附件下载：encode两次；
+ * 3. 如果参数是通过body传输的，只需要encode一次
+ */
+declare function encodeFileId(fileId: string, encodeNum?: number): string;
 
-export { batchDownloadFiles, createDeleteFileLink, createDownloadLink, createOriginalLink, createThumbnailLink, createUploadFileLink, downloadFile, exportBolb, previewFile };
+export { batchDownloadFiles, createDeleteFileLink, createDownloadLink, createOriginalLink, createThumbnailLink, createUploadFileLink, downloadFile, encodeFileId, exportBolb, previewFile };

package/dist/es/file.js

@@ -19,7 +19,7 @@ var isZmdmsFileService = FILE_SERVICE === "zmdms";
  * @param options.open boolean 是否不需要登录信息
  */
 function downloadFile(fileId, fileName, options) {
-    var API_BASEURL = options.API_BASEURL, authToken = options.authToken, _a = options.waterMark, waterMark = _a === void 0 ? true : _a, open = options.open;
+    var API_BASEURL = options.API_BASEURL, authToken = options.authToken, _a = options.waterMark, waterMark = _a === void 0 ? true : _a, open = options.open, _b = options.parseErrorBlob, parseErrorBlob = _b === void 0 ? false : _b;
     if (isZmdmsFileService) {
         fileId = encodeFileId(fileId, 2);
     }
@@ -49,7 +49,32 @@ function downloadFile(fileId, fileName, options) {
                 resolve({ msg: "文件下载成功!" });
             }
             else {
-                reject(xhr.response);
+                if (!parseErrorBlob) {
+                    reject(xhr.response);
+                    return;
+                }
+                try {
+                    if (Object.prototype.toString.call(xhr.response) === "[object Blob]") {
+                        var blob = xhr.response;
+                        blob
+                            .text()
+                            .then(function (text) {
+                            var json = JSON.parse(text);
+                            reject(json);
+                        })
+                            .catch(function (err) {
+                            reject({
+                                msg: (err === null || err === void 0 ? void 0 : err.message) || (err === null || err === void 0 ? void 0 : err.msg) || "下载失败!",
+                                code: xhr.status,
+                            });
+                        });
+                    }
+                }
+                catch (err) {
+                    reject({
+                        msg: "下载失败!",
+                    });
+                }
             }
         };
         xhr.onerror = function (err) {
@@ -68,7 +93,7 @@ function downloadFile(fileId, fileName, options) {
  * @returns
  */
 function batchDownloadFiles(fileList, options) {
-    var API_BASEURL = options.API_BASEURL, authToken = options.authToken, zipName = options.zipName, _a = options.waterMark, waterMark = _a === void 0 ? true : _a;
+    var API_BASEURL = options.API_BASEURL, authToken = options.authToken, zipName = options.zipName, _a = options.waterMark, waterMark = _a === void 0 ? true : _a, _b = options.parseErrorBlob, parseErrorBlob = _b === void 0 ? false : _b;
     return new Promise(function (resolve, reject) {
         var _a, _b, _c, _d, _e, _f;
         var xhr = new XMLHttpRequest();
@@ -91,7 +116,32 @@ function batchDownloadFiles(fileList, options) {
                 resolve({ msg: "文件下载成功!" });
             }
             else {
-                reject(xhr.response);
+                if (!parseErrorBlob) {
+                    reject(xhr.response);
+                    return;
+                }
+                try {
+                    if (Object.prototype.toString.call(xhr.response) === "[object Blob]") {
+                        var blob = xhr.response;
+                        blob
+                            .text()
+                            .then(function (text) {
+                            var json = JSON.parse(text);
+                            reject(json);
+                        })
+                            .catch(function (err) {
+                            reject({
+                                msg: (err === null || err === void 0 ? void 0 : err.message) || (err === null || err === void 0 ? void 0 : err.msg) || "批量下载失败!",
+                                code: xhr.status,
+                            });
+                        });
+                    }
+                }
+                catch (err) {
+                    reject({
+                        msg: "批量下载失败!",
+                    });
+                }
             }
         };
         xhr.onerror = function (err) {

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { addThousedSeparator, appendQueryParamsToUrl, copyToClipboard, dangerous
 export { divide, exactRound, formatUnit, minus, plus, times } from './es/math.js';
 export { validatePassword } from './es/passwordValidate.js';
 export { emailValidate, idCardValidate, isChineseValidate, morePhoneValidate, phoneValidate, strLenValidate } from './es/validate.js';
-export { batchDownloadFiles, createDeleteFileLink, createDownloadLink, createOriginalLink, createThumbnailLink, createUploadFileLink, downloadFile, exportBolb, previewFile } from './es/file.js';
+export { batchDownloadFiles, createDeleteFileLink, createDownloadLink, createOriginalLink, createThumbnailLink, createUploadFileLink, downloadFile, encodeFileId, exportBolb, previewFile } from './es/file.js';
 export { calculateAge, parseTime } from './es/parseTime.js';
 export { BASIC_KEY, CLIENT_TYPE, EMITTER_CCP_KEY, EMITTER_PCC_KEY, EMITTER_TYPE, TOKEN_KEY } from './es/constants.js';
 export { convert, html, match, pinyin } from 'pinyin-pro';

package/dist/index.js

@@ -9,7 +9,7 @@ export { addThousedSeparator, appendQueryParamsToUrl, copyToClipboard, dangerous
 export { divide, exactRound, formatUnit, minus, plus, times } from './es/math.js';
 export { validatePassword } from './es/passwordValidate.js';
 export { emailValidate, idCardValidate, isChineseValidate, morePhoneValidate, phoneValidate, strLenValidate } from './es/validate.js';
-export { batchDownloadFiles, createDeleteFileLink, createDownloadLink, createOriginalLink, createThumbnailLink, createUploadFileLink, downloadFile, exportBolb, previewFile } from './es/file.js';
+export { batchDownloadFiles, createDeleteFileLink, createDownloadLink, createOriginalLink, createThumbnailLink, createUploadFileLink, downloadFile, encodeFileId, exportBolb, previewFile } from './es/file.js';
 export { calculateAge, parseTime } from './es/parseTime.js';
 export { BASIC_KEY, CLIENT_TYPE, EMITTER_CCP_KEY, EMITTER_PCC_KEY, EMITTER_TYPE, TOKEN_KEY } from './es/constants.js';
 export { convert, html, match, pinyin } from './es/node_modules/pinyin-pro/dist/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zmdms-utils",
-  "version": "0.0.85",
+  "version": "0.0.87",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/file.ts

@@ -35,7 +35,13 @@ export function downloadFile(
   fileName: string,
   options: IDownloadOptions
 ) {
-  const { API_BASEURL, authToken, waterMark = true, open } = options;
+  const {
+    API_BASEURL,
+    authToken,
+    waterMark = true,
+    open,
+    parseErrorBlob = false,
+  } = options;
   if (isZmdmsFileService) {
     fileId = encodeFileId(fileId, 2);
   }
@@ -76,7 +82,33 @@ export function downloadFile(
 
         resolve({ msg: "文件下载成功!" });
       } else {
-        reject(xhr.response);
+        if (!parseErrorBlob) {
+          reject(xhr.response);
+          return;
+        }
+        try {
+          if (
+            Object.prototype.toString.call(xhr.response) === "[object Blob]"
+          ) {
+            const blob = xhr.response;
+            blob
+              .text()
+              .then((text: any) => {
+                const json = JSON.parse(text);
+                reject(json);
+              })
+              .catch((err: any) => {
+                reject({
+                  msg: err?.message || err?.msg || "下载失败!",
+                  code: xhr.status,
+                });
+              });
+          }
+        } catch (err) {
+          reject({
+            msg: "下载失败!",
+          });
+        }
       }
     };
     xhr.onerror = function (err) {
@@ -103,7 +135,13 @@ export function batchDownloadFiles(
   }[],
   options: IBatchDownloadOptions
 ) {
-  const { API_BASEURL, authToken, zipName, waterMark = true } = options;
+  const {
+    API_BASEURL,
+    authToken,
+    zipName,
+    waterMark = true,
+    parseErrorBlob = false,
+  } = options;
   return new Promise((resolve, reject) => {
     const xhr = new XMLHttpRequest();
     // 获取请求基础数据
@@ -133,7 +171,33 @@ export function batchDownloadFiles(
 
         resolve({ msg: "文件下载成功!" });
       } else {
-        reject(xhr.response);
+        if (!parseErrorBlob) {
+          reject(xhr.response);
+          return;
+        }
+        try {
+          if (
+            Object.prototype.toString.call(xhr.response) === "[object Blob]"
+          ) {
+            const blob = xhr.response;
+            blob
+              .text()
+              .then((text: any) => {
+                const json = JSON.parse(text);
+                reject(json);
+              })
+              .catch((err: any) => {
+                reject({
+                  msg: err?.message || err?.msg || "批量下载失败!",
+                  code: xhr.status,
+                });
+              });
+          }
+        } catch (err) {
+          reject({
+            msg: "批量下载失败!",
+          });
+        }
       }
     };
     xhr.onerror = function (err) {
@@ -438,11 +502,15 @@ interface IDownloadOptions extends IOptions {
   waterMark?: boolean | string;
   /** 是否开发不需要登录信息 */
   open?: boolean;
+  /** 是否解析异常blob结果 */
+  parseErrorBlob?: boolean;
 }
 interface IBatchDownloadOptions extends IOptions {
   zipName: string;
   /** 是否添加水印 */
   waterMark?: boolean | string;
+  /** 是否解析异常blob结果 */
+  parseErrorBlob?: boolean;
 }
 interface IDownloadLinkOptions extends Partial<IOptions> {
   /** 不需要登录信息的附件下载链接 */

package/src/index.ts

@@ -42,6 +42,7 @@ export {
   createThumbnailLink,
   createUploadFileLink,
   createDeleteFileLink,
+  encodeFileId,
 } from "./file";
 /**
  * 时间处理函数

package/src/locales/i18n.ts

@@ -1,18 +1,18 @@
-import i18next from "i18next";
-import { initReactI18next } from "react-i18next";
-
-type InitOptions = Parameters<typeof i18next.init>;
-
-/**
- * 初始化逻辑
- * - 本函数主要用于初始化 i18next 实例，同时使用 react-i18next 插件进行 react 组件的支持
- * - 本函数的调用时机，一般是在项目的入口文件中进行调用，如 src/main.tsx 中
- * @param options 参数 同i18next.init 第一个参数
- * @param callback 参数 同i18next.init 第二个参数
- * @returns
- */
-function initLocale(options: InitOptions[0], callback?: InitOptions[1]) {
-  return i18next.use(initReactI18next).init(options, callback);
-}
-
-export { initLocale, i18next as i18n };
+import i18next from "i18next";
+import { initReactI18next } from "react-i18next";
+
+type InitOptions = Parameters<typeof i18next.init>;
+
+/**
+ * 初始化逻辑
+ * - 本函数主要用于初始化 i18next 实例，同时使用 react-i18next 插件进行 react 组件的支持
+ * - 本函数的调用时机，一般是在项目的入口文件中进行调用，如 src/main.tsx 中
+ * @param options 参数 同i18next.init 第一个参数
+ * @param callback 参数 同i18next.init 第二个参数
+ * @returns
+ */
+function initLocale(options: InitOptions[0], callback?: InitOptions[1]) {
+  return i18next.use(initReactI18next).init(options, callback);
+}
+
+export { initLocale, i18next as i18n };

package/src/locales/index.ts

@@ -1,8 +1,8 @@
-// i18n实例 及 初始化方法
-export { i18n, initLocale } from "./i18n";
-
-// 代理的 useTranslation 函数
-export { useTranslation, Trans } from "./use-translation";
-
-// 导出 t 函数（应对在非 react 组件环境下进行使用的场景）
-export { safeT } from "./t-in-non-react";
+// i18n实例 及 初始化方法
+export { i18n, initLocale } from "./i18n";
+
+// 代理的 useTranslation 函数
+export { useTranslation, Trans } from "./use-translation";
+
+// 导出 t 函数（应对在非 react 组件环境下进行使用的场景）
+export { safeT } from "./t-in-non-react";

package/src/locales/t-in-non-react.ts

@@ -1,65 +1,65 @@
-/**
- * t 函数封装：
- * - 本文件的几个 t 函数，主要用于弥补一些在 React 组件之外使用的场景
- * - 常规情况下，在 react 组件中，更加推荐的是使用 react-i18next 包中的 t 函数，即 const { t } = useTranslate(); 形式
- */
-import { i18n } from "./i18n";
-import type { TOpionsEx } from "./t-options";
-import { getTFuncArgs } from "./t-options";
-
-/** 包裹一层 try-catch 的 t 函数 */
-const tryT = (
-  key: string,
-  defaultValueOrOptions: string | TOpionsEx
-): string => {
-  const { defaultValue, options } = getTFuncArgs(defaultValueOrOptions);
-  if (!key) {
-    // 情况1：键名为空，返回默认值或键名
-    console.error(
-      `tryT: 请不要传入空 key 值进行 i18n.t 函数执行，这将会导致直接返回空字符串！`
-    );
-    return defaultValue || key;
-  }
-  if (!i18n.exists(key)) {
-    // 情况2：键名不存在，返回默认值或键名
-    console.error(
-      `tryT: i18n-key '${key}' 不存在，请检查对应的 @/locales/resources/locales/xx.json 中是否存在对应值`
-    );
-    return defaultValue || key;
-  }
-  try {
-    // 情况3：尝试执行 i18n.t 函数
-    return i18n.t(key, options);
-  } catch (err) {
-    // 情况4：执行 i18n.t 函数异常，返回默认值或键名
-    console.error(`tryT: i18n.t key=${key} 函数执行异常：err=`, err);
-    return defaultValue || key;
-  }
-};
-
-/**
- * 同步版本的 i18n.t 函数（应对在 react 组件外使用的翻译函数）
- * - 如果 i18n 未初始化，则返回默认值或键名
- * - 如果 i18n 初始化后，键名不存在，则返回默认值或键名
- * - 其他正常情况（已经初始化+键名存在），则返回翻译值
- * @description 本函数为在非 react 组件中使用的翻译函数；（在react中请求使用 useTranslate() 返回的 t 函数）
- * @param {string} key
- * @param {TOpionsEx|string} defaultValue 必填值
- * @returns {string}
- * @example
- *   const txt = t('someLocaleKey', '兜底默认值');
- */
-export function safeT(
-  key: string,
-  defaultValueOrOptions: string | TOpionsEx
-): string {
-  if (i18n.isInitialized) {
-    return tryT(key, defaultValueOrOptions);
-  }
-  // 异常情况：没有初始化完成时，返回默认值
-  const { defaultValue } = getTFuncArgs(defaultValueOrOptions);
-  console.warn(
-    `safeT: i18n is not initialized. Returning defaultValue(${defaultValue}) or origin key (${key}).`
-  );
-  return defaultValue || key;
-}
+/**
+ * t 函数封装：
+ * - 本文件的几个 t 函数，主要用于弥补一些在 React 组件之外使用的场景
+ * - 常规情况下，在 react 组件中，更加推荐的是使用 react-i18next 包中的 t 函数，即 const { t } = useTranslate(); 形式
+ */
+import { i18n } from "./i18n";
+import type { TOpionsEx } from "./t-options";
+import { getTFuncArgs } from "./t-options";
+
+/** 包裹一层 try-catch 的 t 函数 */
+const tryT = (
+  key: string,
+  defaultValueOrOptions: string | TOpionsEx
+): string => {
+  const { defaultValue, options } = getTFuncArgs(defaultValueOrOptions);
+  if (!key) {
+    // 情况1：键名为空，返回默认值或键名
+    console.error(
+      `tryT: 请不要传入空 key 值进行 i18n.t 函数执行，这将会导致直接返回空字符串！`
+    );
+    return defaultValue || key;
+  }
+  if (!i18n.exists(key)) {
+    // 情况2：键名不存在，返回默认值或键名
+    console.error(
+      `tryT: i18n-key '${key}' 不存在，请检查对应的 @/locales/resources/locales/xx.json 中是否存在对应值`
+    );
+    return defaultValue || key;
+  }
+  try {
+    // 情况3：尝试执行 i18n.t 函数
+    return i18n.t(key, options);
+  } catch (err) {
+    // 情况4：执行 i18n.t 函数异常，返回默认值或键名
+    console.error(`tryT: i18n.t key=${key} 函数执行异常：err=`, err);
+    return defaultValue || key;
+  }
+};
+
+/**
+ * 同步版本的 i18n.t 函数（应对在 react 组件外使用的翻译函数）
+ * - 如果 i18n 未初始化，则返回默认值或键名
+ * - 如果 i18n 初始化后，键名不存在，则返回默认值或键名
+ * - 其他正常情况（已经初始化+键名存在），则返回翻译值
+ * @description 本函数为在非 react 组件中使用的翻译函数；（在react中请求使用 useTranslate() 返回的 t 函数）
+ * @param {string} key
+ * @param {TOpionsEx|string} defaultValue 必填值
+ * @returns {string}
+ * @example
+ *   const txt = t('someLocaleKey', '兜底默认值');
+ */
+export function safeT(
+  key: string,
+  defaultValueOrOptions: string | TOpionsEx
+): string {
+  if (i18n.isInitialized) {
+    return tryT(key, defaultValueOrOptions);
+  }
+  // 异常情况：没有初始化完成时，返回默认值
+  const { defaultValue } = getTFuncArgs(defaultValueOrOptions);
+  console.warn(
+    `safeT: i18n is not initialized. Returning defaultValue(${defaultValue}) or origin key (${key}).`
+  );
+  return defaultValue || key;
+}

package/src/locales/t-options.ts

@@ -1,24 +1,24 @@
-"use strict";
-import type { TOptions } from "i18next";
-
-export interface TOpionsEx extends TOptions {
-  defaultValue: string; // 必须填值
-}
-
-/**
- * 获取 t 函数的参数
- * @param {string | TOpionsEx} defaultValueOrOptions 默认值或者选项
- * @returns { {defaultValue: string, options: TOpionsEx} } 默认值和选项
- */
-export function getTFuncArgs(defaultValueOrOptions: string | TOpionsEx) {
-  let options: TOpionsEx | null = null;
-  let defaultValue = "";
-  if (typeof defaultValueOrOptions === "string") {
-    defaultValue = defaultValueOrOptions;
-    options = { defaultValue };
-  } else {
-    options = defaultValueOrOptions;
-    defaultValue = options.defaultValue;
-  }
-  return { defaultValue, options };
-}
+"use strict";
+import type { TOptions } from "i18next";
+
+export interface TOpionsEx extends TOptions {
+  defaultValue: string; // 必须填值
+}
+
+/**
+ * 获取 t 函数的参数
+ * @param {string | TOpionsEx} defaultValueOrOptions 默认值或者选项
+ * @returns { {defaultValue: string, options: TOpionsEx} } 默认值和选项
+ */
+export function getTFuncArgs(defaultValueOrOptions: string | TOpionsEx) {
+  let options: TOpionsEx | null = null;
+  let defaultValue = "";
+  if (typeof defaultValueOrOptions === "string") {
+    defaultValue = defaultValueOrOptions;
+    options = { defaultValue };
+  } else {
+    options = defaultValueOrOptions;
+    defaultValue = options.defaultValue;
+  }
+  return { defaultValue, options };
+}

package/src/locales/use-translation.ts

@@ -1,76 +1,76 @@
-import { useTranslation, Trans } from "react-i18next";
-import type { TOpionsEx } from "./t-options";
-import { getTFuncArgs } from "./t-options";
-
-type Prams = Parameters<typeof useTranslation>;
-type NS = Prams[0];
-type Options = Prams[1];
-
-type EnhanceTFunc = (
-  key: string,
-  defaultValueOrOptions: string | TOpionsEx
-) => string;
-
-/**
- * 这里只是简单代理一下useTranslation，方便后续扩展或添加其他逻辑
- * @param ns 命名空间 大多数情况下都不需要传入这个参数，除非你用到了命名空间。
- * @param options 其他参数 大多数情况下，都不需要关注这个参数。
- * options.keyPrefix 为所有翻译键添加前缀
- *  // JSON 文件：{ "greeting": { "welcome": "Welcome" } }
- *  const { t } = useTranslation('common', { keyPrefix: 'greeting' });
- *  // 使用时省略前缀
- *  t('welcome'); // 等价于 t('greeting:welcome')
- * @returns { t, i18n, ready }
- * t: 翻译方法
- * i18n: i18next实例 访问 i18next 的完整 API（如切换语言、加载命名空间）
- * i18n.changeLanguage('zh-CN'); 使用它切换语言，可以触发组件渲染。但是当前项目中是使用全局刷新的模式，来更新语言的。
- * ready: 是否加载完成
- */
-function useZtTranslation(ns?: NS, options?: Options) {
-  const { t: _tOld, i18n, ready } = useTranslation(ns, options);
-
-  // 扩展t方法，用于处理嵌套的翻译键
-  const tEnhance: EnhanceTFunc = (key, defaultValueOrOptions) => {
-    const { defaultValue, options } = getTFuncArgs(defaultValueOrOptions);
-
-    if (!key) {
-      // 情况1：键名为空，返回默认值或键名
-      console.error(
-        `tEnhance: 请不要传入空 key 值进行 t 函数执行，这将会导致直接返回空字符串！`
-      );
-      return defaultValue || key;
-    }
-    if (!i18n.exists(key)) {
-      // 情况2：键名不存在，返回默认值或键名
-      console.error(
-        `tEnhance: i18n-key '${key}' 不存在，请检查对应的 @/locales/resources/locales/xx.json 中是否存在对应值`
-      );
-      return defaultValue || key;
-    }
-    try {
-      return _tOld(key, options);
-    } catch (error) {
-      console.warn(`tEnhance: t 函数执行异常，请检查! key=${key}, err=`, error);
-      return defaultValue || key || "unknown";
-    }
-  };
-
-  return {
-    /**
-     * t函数的使用方式：基本上使用1、2两种方式就可以了。
-     * 1、t('key') // 基础用法
-     * 2、t('greeting', { name: 'John' }); // 对应 JSON: "greeting": "Hello {{name}}"
-     * 3、t('auth:login'); // 显式指定命名空间
-     *
-     * 关于t函数的第二个参数的说明。
-     * 为了防止一些异常情况，翻译失败。可以传入一个默认值。这个默认值就是原本的中文就行。
-     * 1、t('key', '默认值');
-     * 2、t('key', { defaultValue: '默认值', ...otherOptions });
-     */
-    t: tEnhance,
-    i18n,
-    ready,
-  };
-}
-
-export { useZtTranslation as useTranslation, Trans };
+import { useTranslation, Trans } from "react-i18next";
+import type { TOpionsEx } from "./t-options";
+import { getTFuncArgs } from "./t-options";
+
+type Prams = Parameters<typeof useTranslation>;
+type NS = Prams[0];
+type Options = Prams[1];
+
+type EnhanceTFunc = (
+  key: string,
+  defaultValueOrOptions: string | TOpionsEx
+) => string;
+
+/**
+ * 这里只是简单代理一下useTranslation，方便后续扩展或添加其他逻辑
+ * @param ns 命名空间 大多数情况下都不需要传入这个参数，除非你用到了命名空间。
+ * @param options 其他参数 大多数情况下，都不需要关注这个参数。
+ * options.keyPrefix 为所有翻译键添加前缀
+ *  // JSON 文件：{ "greeting": { "welcome": "Welcome" } }
+ *  const { t } = useTranslation('common', { keyPrefix: 'greeting' });
+ *  // 使用时省略前缀
+ *  t('welcome'); // 等价于 t('greeting:welcome')
+ * @returns { t, i18n, ready }
+ * t: 翻译方法
+ * i18n: i18next实例 访问 i18next 的完整 API（如切换语言、加载命名空间）
+ * i18n.changeLanguage('zh-CN'); 使用它切换语言，可以触发组件渲染。但是当前项目中是使用全局刷新的模式，来更新语言的。
+ * ready: 是否加载完成
+ */
+function useZtTranslation(ns?: NS, options?: Options) {
+  const { t: _tOld, i18n, ready } = useTranslation(ns, options);
+
+  // 扩展t方法，用于处理嵌套的翻译键
+  const tEnhance: EnhanceTFunc = (key, defaultValueOrOptions) => {
+    const { defaultValue, options } = getTFuncArgs(defaultValueOrOptions);
+
+    if (!key) {
+      // 情况1：键名为空，返回默认值或键名
+      console.error(
+        `tEnhance: 请不要传入空 key 值进行 t 函数执行，这将会导致直接返回空字符串！`
+      );
+      return defaultValue || key;
+    }
+    if (!i18n.exists(key)) {
+      // 情况2：键名不存在，返回默认值或键名
+      console.error(
+        `tEnhance: i18n-key '${key}' 不存在，请检查对应的 @/locales/resources/locales/xx.json 中是否存在对应值`
+      );
+      return defaultValue || key;
+    }
+    try {
+      return _tOld(key, options);
+    } catch (error) {
+      console.warn(`tEnhance: t 函数执行异常，请检查! key=${key}, err=`, error);
+      return defaultValue || key || "unknown";
+    }
+  };
+
+  return {
+    /**
+     * t函数的使用方式：基本上使用1、2两种方式就可以了。
+     * 1、t('key') // 基础用法
+     * 2、t('greeting', { name: 'John' }); // 对应 JSON: "greeting": "Hello {{name}}"
+     * 3、t('auth:login'); // 显式指定命名空间
+     *
+     * 关于t函数的第二个参数的说明。
+     * 为了防止一些异常情况，翻译失败。可以传入一个默认值。这个默认值就是原本的中文就行。
+     * 1、t('key', '默认值');
+     * 2、t('key', { defaultValue: '默认值', ...otherOptions });
+     */
+    t: tEnhance,
+    i18n,
+    ready,
+  };
+}
+
+export { useZtTranslation as useTranslation, Trans };