zmdms-utils 0.0.73 → 0.0.74

package/dist/es/src/locales/t-in-non-react.js

@@ -0,0 +1,54 @@
+import instance from '../../node_modules/i18next/dist/esm/i18next.js';
+import { getTFuncArgs } from './t-options.js';
+
+/**
+ * t 函数封装：
+ * - 本文件的几个 t 函数，主要用于弥补一些在 React 组件之外使用的场景
+ * - 常规情况下，在 react 组件中，更加推荐的是使用 react-i18next 包中的 t 函数，即 const { t } = useTranslate(); 形式
+ */
+/** 包裹一层 try-catch 的 t 函数 */
+var tryT = function (key, defaultValueOrOptions) {
+    var _a = getTFuncArgs(defaultValueOrOptions), defaultValue = _a.defaultValue, options = _a.options;
+    if (!key) {
+        // 情况1：键名为空，返回默认值或键名
+        console.error("tryT: \u8BF7\u4E0D\u8981\u4F20\u5165\u7A7A key \u503C\u8FDB\u884C i18n.t \u51FD\u6570\u6267\u884C\uFF0C\u8FD9\u5C06\u4F1A\u5BFC\u81F4\u76F4\u63A5\u8FD4\u56DE\u7A7A\u5B57\u7B26\u4E32\uFF01");
+        return defaultValue || key;
+    }
+    if (!instance.exists(key)) {
+        // 情况2：键名不存在，返回默认值或键名
+        console.error("tryT: i18n-key '".concat(key, "' \u4E0D\u5B58\u5728\uFF0C\u8BF7\u68C0\u67E5\u5BF9\u5E94\u7684 @/locales/resources/locales/xx.json \u4E2D\u662F\u5426\u5B58\u5728\u5BF9\u5E94\u503C"));
+        return defaultValue || key;
+    }
+    try {
+        // 情况3：尝试执行 i18n.t 函数
+        return instance.t(key, options);
+    }
+    catch (err) {
+        // 情况4：执行 i18n.t 函数异常，返回默认值或键名
+        console.error("tryT: i18n.t key=".concat(key, " \u51FD\u6570\u6267\u884C\u5F02\u5E38\uFF1Aerr="), 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', '兜底默认值');
+ */
+function safeT(key, defaultValueOrOptions) {
+    if (instance.isInitialized) {
+        return tryT(key, defaultValueOrOptions);
+    }
+    // 异常情况：没有初始化完成时，返回默认值
+    var defaultValue = getTFuncArgs(defaultValueOrOptions).defaultValue;
+    console.warn("safeT: i18n is not initialized. Returning defaultValue(".concat(defaultValue, ") or origin key (").concat(key, ")."));
+    return defaultValue || key;
+}
+
+export { safeT };

package/dist/es/src/locales/t-options.js

@@ -0,0 +1,20 @@
+/**
+ * 获取 t 函数的参数
+ * @param {string | TOpionsEx} defaultValueOrOptions 默认值或者选项
+ * @returns { {defaultValue: string, options: TOpionsEx} } 默认值和选项
+ */
+function getTFuncArgs(defaultValueOrOptions) {
+    var options = null;
+    var defaultValue = "";
+    if (typeof defaultValueOrOptions === "string") {
+        defaultValue = defaultValueOrOptions;
+        options = { defaultValue: defaultValue };
+    }
+    else {
+        options = defaultValueOrOptions;
+        defaultValue = options.defaultValue;
+    }
+    return { defaultValue: defaultValue, options: options };
+}
+
+export { getTFuncArgs };

package/dist/es/src/locales/use-translation.js

@@ -0,0 +1,60 @@
+import { getTFuncArgs } from './t-options.js';
+import { useTranslation } from '../../node_modules/react-i18next/dist/es/useTranslation.js';
+
+/**
+ * 这里只是简单代理一下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, options) {
+    var _a = useTranslation(ns, options), _tOld = _a.t, i18n = _a.i18n, ready = _a.ready;
+    // 扩展t方法，用于处理嵌套的翻译键
+    var tEnhance = function (key, defaultValueOrOptions) {
+        var _a = getTFuncArgs(defaultValueOrOptions), defaultValue = _a.defaultValue, options = _a.options;
+        if (!key) {
+            // 情况1：键名为空，返回默认值或键名
+            console.error("tEnhance: \u8BF7\u4E0D\u8981\u4F20\u5165\u7A7A key \u503C\u8FDB\u884C t \u51FD\u6570\u6267\u884C\uFF0C\u8FD9\u5C06\u4F1A\u5BFC\u81F4\u76F4\u63A5\u8FD4\u56DE\u7A7A\u5B57\u7B26\u4E32\uFF01");
+            return defaultValue || key;
+        }
+        if (!i18n.exists(key)) {
+            // 情况2：键名不存在，返回默认值或键名
+            console.error("tEnhance: i18n-key '".concat(key, "' \u4E0D\u5B58\u5728\uFF0C\u8BF7\u68C0\u67E5\u5BF9\u5E94\u7684 @/locales/resources/locales/xx.json \u4E2D\u662F\u5426\u5B58\u5728\u5BF9\u5E94\u503C"));
+            return defaultValue || key;
+        }
+        try {
+            return _tOld(key, options);
+        }
+        catch (error) {
+            console.warn("tEnhance: t \u51FD\u6570\u6267\u884C\u5F02\u5E38\uFF0C\u8BF7\u68C0\u67E5! key=".concat(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: i18n,
+        ready: ready,
+    };
+}
+
+export { useZtTranslation as useTranslation };

package/dist/index.d.ts

@@ -18,4 +18,9 @@ export { imgToPdf } from './es/pdf.js';
 export { htmlToPdf } from './es/htmlToPdf.js';
 export { htmlPrint, imgPrint, pdfPrint, windowPrint } from './es/print.js';
 export { createWater, getDefaultContent, mergeWaterConfig } from './es/water.js';
+export { initLocale } from './es/locales/i18n.js';
+export { useTranslation } from './es/locales/use-translation.js';
+export { safeT } from './es/locales/t-in-non-react.js';
 export { Base64 } from 'js-base64';
+export { default as i18n } from 'i18next';
+export { Trans } from 'react-i18next';

package/dist/index.js

@@ -18,4 +18,9 @@ export { imgToPdf } from './es/pdf.js';
 export { htmlToPdf } from './es/htmlToPdf.js';
 export { htmlPrint, imgPrint, pdfPrint, windowPrint } from './es/print.js';
 export { createWater, getDefaultContent, mergeWaterConfig } from './es/water.js';
+export { initLocale } from './es/src/locales/i18n.js';
+export { useTranslation } from './es/src/locales/use-translation.js';
+export { safeT } from './es/src/locales/t-in-non-react.js';
 export { Base64 } from './es/node_modules/js-base64/base64.js';
+export { default as i18n } from './es/node_modules/i18next/dist/esm/i18next.js';
+export { Trans } from './es/node_modules/react-i18next/dist/es/Trans.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zmdms-utils",
-  "version": "0.0.73",
+  "version": "0.0.74",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -34,12 +34,14 @@
     "@types/crypto-js": "^4.1.1",
     "axios": "^1.4.0",
     "crypto-js": "^4.1.1",
-    "js-base64": "^3.7.7",
     "dayjs": "^1.11.10",
     "html2canvas": "^1.4.1",
+    "i18next": "^25.1.2",
+    "js-base64": "^3.7.7",
     "jspdf": "^2.5.1",
     "print-js": "^1.6.0",
     "qiankun": "^2.10.8",
+    "react-i18next": "^15.5.1",
     "rimraf": "^4.4.1",
     "rollup": "^3.20.2",
     "rollup-plugin-dts": "^5.3.0",

package/src/index.ts

@@ -78,3 +78,6 @@ export { windowPrint, htmlPrint, imgPrint, pdfPrint } from "./print";
 
 // 水印相关
 export { createWater, mergeWaterConfig, getDefaultContent } from "./water";
+
+// 多语言相关
+export { initLocale, i18n, useTranslation, Trans, safeT } from "./locales";

package/src/locales/i18n.ts

@@ -0,0 +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 };

package/src/locales/index.ts

@@ -0,0 +1,8 @@
+// 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

@@ -0,0 +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;
+}

package/src/locales/t-options.ts

@@ -0,0 +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 };
+}

package/src/locales/use-translation.ts

@@ -0,0 +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 };

package/src/locales//345/244/232/350/257/255/350/250/200.md

@@ -0,0 +1 @@
+# React 项目多语言

package/src/microAppCreator.ts

@@ -16,11 +16,32 @@ export function update(props: any) {
  * @param microAppOptions 微应用的一些配置
  */
 export interface IMicroAppOptions {
+  /**
+   * @deprecated 该属性已废弃，无意义
+   */
   microAppContainerId: string; // 微应用加载的dom容器 id
   microAppKey: string; // 微应用的唯一key值 用途：1. qiankun下的路由前缀；2. 主、子通信时的标识
+  /**
+   * @deprecated 该属性已废弃，无意义
+   */
   microAppRoot: any; // 微应用根节点实例
-  microAppMountHandle?: (props: any) => void; // 微应用每次进入都会调用的方法
-  microAppUnMountHandle?: (props: any) => void; // 微应用每次切出/卸载 都会调用的方法
+  /**
+   * 只会在微应用初始化的时候调用一次，下次微应用重新进入时会直接调用 mount 钩子，不会再重复触发 bootstrap
+   * 通常我们可以在这里做一些全局变量的初始化，比如不会在 unmount 阶段被销毁的应用级别的缓存等。
+   **/
+  microAppBootstrapHandle?: () => void;
+  /**
+   * 应用每次进入都会调用 mount 方法，通常我们在这里触发应用的渲染方法
+   */
+  microAppMountHandle: (props: any) => void;
+  /**
+   * 应用每次 切出/卸载 会调用的方法，通常在这里我们会卸载微应用的应用实例
+   */
+  microAppUnMountHandle: (props: any) => void;
+  /**
+   * 可选生命周期钩子，仅使用 loadMicroApp 方式加载微应用时生效
+   */
+  microAppUpdateHandle?: (props: any) => void;
 }
 export function initMicroApp(render: any, microAppOptions: IMicroAppOptions) {
   // 初始加载应用
@@ -32,9 +53,10 @@ export function initMicroApp(render: any, microAppOptions: IMicroAppOptions) {
   // 2. 进入微前端环境的运行逻辑
   const {
     microAppKey,
-    microAppRoot,
+    microAppBootstrapHandle,
     microAppMountHandle,
     microAppUnMountHandle,
+    microAppUpdateHandle,
   } = microAppOptions;
 
   // 唯一key没传 给出开发提示
@@ -47,15 +69,20 @@ export function initMicroApp(render: any, microAppOptions: IMicroAppOptions) {
    * 通常我们可以在这里做一些全局变量的初始化，比如不会在 unmount 阶段被销毁的应用级别的缓存等。
    */
   async function bootstrap() {
-    console.log("微应用 bootstraped");
+    console.log(`微应用==${microAppKey}==bootstraped`);
+    if (microAppBootstrapHandle) {
+      microAppBootstrapHandle();
+    }
   }
 
   /**
    * 应用每次进入都会调用 mount 方法，通常我们在这里触发应用的渲染方法
    */
   async function mount(props: any) {
-    console.log("微应用 mount");
-    microAppMountHandle && microAppMountHandle(props);
+    console.log(`微应用==${microAppKey}==mount`);
+    if (microAppMountHandle) {
+      microAppMountHandle(props);
+    }
     render(props);
   }
 
@@ -63,13 +90,25 @@ export function initMicroApp(render: any, microAppOptions: IMicroAppOptions) {
    * 应用每次 切出/卸载 会调用的方法，通常在这里我们会卸载微应用的应用实例
    */
   async function unmount(props: any) {
-    console.log("微应用 unmount", props);
-    microAppUnMountHandle && microAppUnMountHandle(props);
+    console.log(`微应用==${microAppKey}==unmount`);
+    if (microAppUnMountHandle) {
+      microAppUnMountHandle(props);
+    }
+  }
+  /**
+   * 应用每次 切出/卸载 会调用的方法，通常在这里我们会卸载微应用的应用实例
+   */
+  async function update(props: any) {
+    console.log(`微应用==${microAppKey}==update`);
+    if (microAppUpdateHandle) {
+      microAppUpdateHandle(props);
+    }
   }
 
   return {
     bootstrap,
     mount,
     unmount,
+    update,
   };
 }