gc_i18n 1.5.0 → 1.5.2

package/.qoder/repowiki/zh/content//346/225/205/351/232/234/346/216/222/351/231/244.md

@@ -10,14 +10,15 @@
 - [gc_i18n.js](file://lib/gc_i18n.js)
 - [config.vue](file://packages/components/config.vue)
 - [App.vue](file://src/App.vue)
-- [utils.js](file://packages/libs/utils.js) - *更新了数据合并逻辑*
+- [utils.js](file://packages/libs/utils.js)
+- [package.json](file://package.json)
 </cite>
 
 ## 更新摘要
 **变更内容**   
-- 更新了“加载失败问题”部分，新增了关于 `common` 键处理逻辑的说明
-- 在“根本原因分析”和“具体解决方案”中增加了对 `mergeArraysByKey` 函数行为的详细解释
-- 更新了相关源码引用，添加了 `utils.js` 文件的引用
+- 新增了"消息事件处理错误"章节，专门针对1.5.1版本改进的消息事件处理错误处理机制
+- 更新了"调试模式与日志查看"部分，增加了跨域安全检查相关的日志输出
+- 在"配置有效性验证"中添加了消息事件处理的安全性验证要点
 - 保持了原有文档结构和未受影响部分的完整性
 
 ## 目录
@@ -25,9 +26,10 @@
 2. [语言不切换问题](#语言不切换问题)
 3. [翻译文本显示为键名](#翻译文本显示为键名)
 4. [加载失败问题](#加载失败问题)
-5. [调试模式与日志查看](#调试模式与日志查看)
-6. [配置有效性验证](#配置有效性验证)
-7. [测试策略建议](#测试策略建议)
+5. [消息事件处理错误](#消息事件处理错误)
+6. [调试模式与日志查看](#调试模式与日志查看)
+7. [配置有效性验证](#配置有效性验证)
+8. [测试策略建议](#测试策略建议)
 
 ## 常见问题汇总
 
@@ -37,8 +39,9 @@
 - **加载失败**：语言包无法正确加载，导致翻译功能失效
 - **异步组件问题**：动态加载的组件中翻译键未被正确收集
 - **缓存问题**：旧的语言数据未被清除，影响新语言的加载
+- **消息事件处理错误**：跨域消息通信时出现安全错误或异常
 
-这些问题通常源于配置错误、异步处理不当或依赖关系未正确处理。以下将针对每个问题提供详细的根因分析和解决方案。
+这些问题通常源于配置错误、异步处理不当或依赖关系未正确处理。1.5.1版本特别加强了消息事件处理的安全性和稳定性。以下将针对每个问题提供详细的根因分析和解决方案。
 
 ## 语言不切换问题
 
@@ -91,8 +94,8 @@ this.router.beforeEach(async (to, from, next) => {
 ```
 
 **Section sources**
-- [packages/index.js](file://packages/index.js#L231-L277)
-- [packages/index.js](file://packages/index.js#L160-L194)
+- [packages/index.js:231-277](file://packages/index.js#L231-L277)
+- [packages/index.js:160-194](file://packages/index.js#L160-L194)
 
 ## 翻译文本显示为键名
 
@@ -167,7 +170,7 @@ globalThis.$clearI18n();
 store2.namespace(`I18N_${appCode.toUpperCase()}`).clearAll();
 ```
 
-``mermaid
+```mermaid
 flowchart TD
 A[开始] --> B{翻译键存在?}
 B --> |是| C[返回翻译文本]
@@ -185,12 +188,12 @@ D --> |否| M[返回原始键名]
 ```
 
 **Diagram sources**
-- [packages/index.js](file://packages/index.js#L200-L230)
+- [packages/index.js:200-230](file://packages/index.js#L200-L230)
 
 **Section sources**
-- [packages/index.js](file://packages/index.js#L200-L230)
-- [packages/libs/i18nUtils.ts](file://packages/libs/i18nUtils.ts#L0-L52)
-- [packages/libs/service.js](file://packages/libs/service.js#L65-L123)
+- [packages/index.js:200-230](file://packages/index.js#L200-L230)
+- [packages/libs/i18nUtils.ts:0-52](file://packages/libs/i18nUtils.ts#L0-L52)
+- [packages/libs/service.js:65-123](file://packages/libs/service.js#L65-L123)
 
 ## 加载失败问题
 
@@ -305,9 +308,119 @@ async setLanguage(language) {
 ```
 
 **Section sources**
-- [packages/index.js](file://packages/index.js#L250-L277)
-- [packages/libs/service.js](file://packages/libs/service.js#L65-L123)
-- [packages/libs/utils.js](file://packages/libs/utils.js#L9-L28) - *更新了数据合并逻辑*
+- [packages/index.js:250-277](file://packages/index.js#L250-L277)
+- [packages/libs/service.js:65-123](file://packages/libs/service.js#L65-L123)
+- [packages/libs/utils.js:9-28](file://packages/libs/utils.js#L9-L28)
+
+## 消息事件处理错误
+
+**更新** 新增此章节，反映1.5.1版本中改进的消息事件处理错误处理机制
+
+### 根本原因分析
+
+消息事件处理错误主要出现在跨域通信场景中，1.5.1版本之前可能存在以下问题：
+1. **跨域安全错误**：直接访问 `event.origin` 导致 SecurityError
+2. **未捕获的异常**：try-catch 机制不完善，导致错误传播到控制台
+3. **调试困难**：跨域错误与业务逻辑错误混合，难以区分
+4. **性能影响**：频繁的跨域错误导致不必要的日志输出
+
+### 具体解决方案
+
+1. **启用跨域安全检查**
+```javascript
+// 1.5.1版本中改进的消息事件处理
+window.top.addEventListener("message", (event) => {
+  try {
+    // 跨域检查：如果源不匹配，跳过处理以避免安全错误
+    if (!event.origin || event.origin === "null") {
+      return;
+    }
+    console.log("打印接收到的数据message:", event.data);
+    if (event.data && event.data.type === "updateLanguage") {
+      location.reload();
+    } else if (event.data && event.data.type === "closeModal") {
+      if (this.swalInstance) {
+        this.swalInstance.close();
+      }
+    }
+  } catch (error) {
+    // 静默处理跨域错误，不在控制台显示
+    if (error.name !== "SecurityError") {
+      console.warn("Message event handler error:", error);
+    }
+  }
+});
+```
+
+2. **验证跨域配置**
+```javascript
+// 确保正确的跨域配置
+const allowedOrigins = [
+  "https://trusted-domain.com",
+  "https://*.ihotel.cn",
+  window.location.origin
+];
+
+// 在发送消息时指定正确的目标源
+iframe.contentWindow.postMessage(data, targetOrigin);
+```
+
+3. **检查消息事件监听器**
+```javascript
+// 验证消息事件监听器的正确性
+if (window.top && window.top !== window) {
+  window.top.addEventListener("message", messageHandler);
+} else {
+  console.warn("无法设置跨域消息监听器");
+}
+```
+
+4. **实现优雅降级**
+```javascript
+// 如果跨域检查失败，使用替代方案
+function handleMessage(event) {
+  try {
+    // 1.5.1版本的改进检查
+    if (!event.origin || event.origin === "null") {
+      // 静默忽略，不输出错误日志
+      return;
+    }
+    
+    // 处理消息事件
+    processMessage(event.data);
+  } catch (error) {
+    // 只记录非跨域相关的错误
+    if (error.name !== "SecurityError") {
+      console.warn("消息处理错误:", error);
+    }
+  }
+}
+```
+
+5. **监控消息事件状态**
+```javascript
+// 添加消息事件处理的状态监控
+let messageHandlerStatus = {
+  initialized: false,
+  lastError: null,
+  errorCount: 0
+};
+
+function setupMessageHandler() {
+  try {
+    window.top.addEventListener("message", handleMessage);
+    messageHandlerStatus.initialized = true;
+    console.log("消息事件处理器已初始化");
+  } catch (error) {
+    messageHandlerStatus.lastError = error;
+    messageHandlerStatus.errorCount++;
+    console.warn("消息事件处理器初始化失败:", error);
+  }
+}
+```
+
+**Section sources**
+- [packages/index.js:661-681](file://packages/index.js#L661-L681)
 
 ## 调试模式与日志查看
 
@@ -329,11 +442,13 @@ const { i18n } = new gc_i18n({
 - 语言切换时的 token 更新
 - 翻译键的收集过程
 - 网络请求的详细信息
+- **新增** 消息事件处理的日志输出
 
 ```javascript
 // 示例日志输出
 console.log("  this.token", this.token);
 console.log("  this.token2", this.token);
+console.log("打印接收到的数据message:", event.data); // 1.5.1版本新增
 ```
 
 3. **监控关键事件**
@@ -350,6 +465,17 @@ setupLanguageChangeListener() {
     });
   }
 }
+
+// 监控消息事件处理状态
+setupMessageHandlerMonitoring() {
+  const originalAddEventListener = window.addEventListener;
+  window.addEventListener = function(type, listener, options) {
+    if (type === "message") {
+      console.log("设置消息事件监听器");
+    }
+    return originalAddEventListener.apply(this, arguments);
+  };
+}
 ```
 
 ### 关键日志位置
@@ -358,8 +484,9 @@ setupLanguageChangeListener() {
 2. **翻译键收集日志**：路由守卫中的 `extractTranslationKeys` 调用
 3. **网络请求日志**：`service.js` 中的 `getTranslate` 和 `fetchTranslate` 方法
 4. **错误日志**：异步组件加载失败时的 `console.error`
+5. ****消息事件日志**：**1.5.1版本新增** `packages/index.js` 中的消息事件处理日志
 
-``mermaid
+```mermaid
 sequenceDiagram
 participant User as 用户
 participant App as 应用
@@ -374,12 +501,12 @@ App-->>User : 界面语言更新
 ```
 
 **Diagram sources**
-- [packages/index.js](file://packages/index.js#L250-L277)
-- [packages/libs/service.js](file://packages/libs/service.js#L65-L123)
+- [packages/index.js:250-277](file://packages/index.js#L250-L277)
+- [packages/libs/service.js:65-123](file://packages/libs/service.js#L65-L123)
 
 **Section sources**
-- [packages/index.js](file://packages/index.js#L250-L277)
-- [packages/libs/service.js](file://packages/libs/service.js#L65-L123)
+- [packages/index.js:250-277](file://packages/index.js#L250-L277)
+- [packages/libs/service.js:65-123](file://packages/libs/service.js#L65-L123)
 
 ## 配置有效性验证
 
@@ -442,10 +569,21 @@ console.log("I18N_TOKEN:", store2.get("I18N_TOKEN"));
 console.log("I18N_LANGUAGES:", store2.get("I18N_LANGUAGES"));
 ```
 
+3. ****验证消息事件处理配置**：**1.5.1版本新增**
+```javascript
+// 检查消息事件处理状态
+console.log("消息事件处理器状态:", messageHandlerStatus);
+
+// 验证跨域配置
+console.log("允许的来源:", allowedOrigins);
+console.log("当前窗口来源:", window.location.origin);
+```
+
 **Section sources**
-- [main.js](file://src/main.js#L0-L9)
-- [lang/index.js](file://lang/index.js#L0-L42)
-- [packages/index.js](file://packages/index.js#L0-L325)
+- [main.js:0-9](file://src/main.js#L0-L9)
+- [lang/index.js:0-42](file://lang/index.js#L0-L42)
+- [packages/index.js:0-325](file://packages/index.js#L0-L325)
+- [package.json:1-48](file://package.json#L1-L48)
 
 ## 测试策略建议
 
@@ -504,6 +642,46 @@ test('should handle async components in route guards', async () => {
 });
 ```
 
+3. ****测试消息事件处理**：**1.5.1版本新增**
+```javascript
+// 测试跨域消息事件处理
+test('should handle cross-domain messages safely', () => {
+  const messageHandler = jest.fn();
+  const originalAddEventListener = window.addEventListener;
+  window.addEventListener = messageHandler;
+  
+  setupMessageHandler();
+  
+  // 测试 null origin 的情况
+  const nullOriginEvent = { origin: null, data: { type: 'updateLanguage' } };
+  window.dispatchEvent(new MessageEvent('message', nullOriginEvent));
+  
+  expect(messageHandler).toHaveBeenCalled();
+  expect(console.warn).not.toHaveBeenCalledWith("Message event handler error:");
+});
+
+// 测试 SecurityError 的静默处理
+test('should silently handle SecurityError', () => {
+  const originalConsoleWarn = console.warn;
+  console.warn = jest.fn();
+  
+  // 模拟 SecurityError
+  const securityError = new Error('SecurityError');
+  securityError.name = 'SecurityError';
+  
+  try {
+    throw securityError;
+  } catch (error) {
+    if (error.name !== "SecurityError") {
+      console.warn("Message event handler error:", error);
+    }
+  }
+  
+  expect(console.warn).not.toHaveBeenCalled();
+  console.warn = originalConsoleWarn;
+});
+```
+
 ### 端到端测试
 
 1. **模拟真实用户场景**
@@ -511,15 +689,18 @@ test('should handle async components in route guards', async () => {
 - 测试语言切换后的界面更新
 - 验证登录页面的特殊处理
 - 检查浏览器语言变化的自动响应
+- **新增** 验证跨域消息通信的稳定性
 
 2. **性能测试**
 - 测量语言包加载时间
 - 验证缓存机制的有效性
 - 测试大量翻译键的处理性能
+- **新增** 测试消息事件处理的性能开销
 
-通过实施这些测试策略，可以有效预防常见错误，确保国际化功能的稳定性和可靠性。
+通过实施这些测试策略，可以有效预防常见错误，确保国际化功能的稳定性和可靠性，特别是1.5.1版本中改进的消息事件处理安全性。
 
 **Section sources**
-- [packages/index.js](file://packages/index.js#L0-L325)
-- [packages/libs/i18nUtils.ts](file://packages/libs/i18nUtils.ts#L0-L52)
-- [packages/libs/service.js](file://packages/libs/service.js#L0-L123)
+- [packages/index.js:0-325](file://packages/index.js#L0-L325)
+- [packages/libs/i18nUtils.ts:0-52](file://packages/libs/i18nUtils.ts#L0-L52)
+- [packages/libs/service.js:0-123](file://packages/libs/service.js#L0-L123)
+- [package.json:1-48](file://package.json#L1-L48)

package/.qoder/repowiki/zh/content//346/240/270/345/277/203/345/272/223/345/256/236/347/216/260.md

@@ -2324,11 +2324,6 @@ export const getLanguagesWithCache = async ({
     }));
   }
 
-  // 从 API 获取
-  if (!appCode) {
-    return [];
-  }
-
   try {
     const res = await http.get(`${baseUrl}/i18n-web//app/getsupportedlangs`, {
       headers: {

package/.qoder/repowiki/zh/content//350/257/255/350/250/200/350/265/204/346/272/220/347/256/241/347/220/206.md

@@ -2,9 +2,9 @@
 
 <cite>
 **本文档中引用的文件**   
-- [index.js](file://lang/index.js) - *简化了国际化实现，移除了复杂的 vue-i18n 集成*
+- [index.js](file://lang/index.js) - *改进了安装和初始化过程，新增了中文语言支持的消息配置对象*
 - [index.json](file://lang/index.json) - *包含138个翻译键，新增阿拉伯语支持*
-- [packages/index.js](file://packages/index.js) - *自包含的翻译系统实现，API更加简洁*
+- [packages/index.js](file://packages/index.js) - *自包含的翻译系统实现，API更加简洁，增强了全局组件注册*
 - [utils.js](file://packages/libs/utils.js) - *RTL语言支持和工具函数*
 - [service.js](file://packages/libs/service.js) - *语言数据获取和缓存机制*
 - [textEditMode.js](file://packages/libs/textEditMode.js) - *文本编辑模式功能*
@@ -15,13 +15,12 @@
 
 ## 更新摘要
 **已做更改**   
-- 更新了[语言资源组织与加载机制](#语言资源组织与加载机制)以反映简化的自包含翻译系统
-- 更新了[多语言数据导出机制](#多语言数据导出机制)以反映移除的复杂vue-i18n集成
-- 新增了[自包含翻译系统架构](#自包含翻译系统架构)章节，说明简化的API设计
-- 更新了[动态加载策略](#动态加载策略)以反映简化的实现方式
-- 新增了[简化的API设计](#简化的api设计)章节，介绍新的使用方式
-- 更新了[RTL语言支持机制](#rtl语言支持机制)以反映增强的RTL检测功能
-- 更新了[文本编辑模式功能](#文本编辑模式功能)以反映简化的实现
+- 更新了[语言资源组织与加载机制](#语言资源组织与加载机制)以反映改进的安装和初始化过程
+- 更新了[多语言数据导出机制](#多语言数据导出机制)以反映新增的中文语言支持配置
+- 更新了[全局组件注册机制](#全局组件注册机制)以反映增强的组件挂载功能
+- 更新了[简化的API设计](#简化的api设计)以反映改进的 `$t` 函数挂载逻辑
+- 新增了[中文语言支持配置](#中文语言支持配置)章节，说明新增的消息配置对象
+- 更新了[动态加载策略](#动态加载策略)以反映改进的初始化流程
 
 ## 目录
 1. [项目结构](#项目结构)
@@ -43,6 +42,8 @@
 17. [文本编辑模式功能](#文本编辑模式功能)
 18. [快捷键绑定机制](#快捷键绑定机制)
 19. [文本编辑模式样式系统](#文本编辑模式样式系统)
+20. [中文语言支持配置](#中文语言支持配置)
+21. [全局组件注册机制](#全局组件注册机制)
 
 ## 项目结构
 
@@ -197,20 +198,31 @@ const english = $t('welcome', 'Welcome'); // "欢迎"（fallback）
 import gc_i18n from "../packages/index.js";
 
 const i18n = new gc_i18n({
-  appCode: "TEST",
+  appCode: "TEST-SRC",
   orgCode: import.meta.env.MODE === "unit" ? "DD" : "GREENCLOUD",
   env: "dev",
+  messages: {
+    "zh-CN": {
+      test: "测试"
+    }
+  },
   login: false
 });
 
 export default {
   install(app, router) {
-    i18n.setRouter(router);
+    // Vue 2 下 app 为 Vue 构造函数，需传入以正确注册 VueI18n
+    // 调用实例的 install 方法来注册全局组件和挂载 $t
+    i18n.install(app);
+    // 设置 router（如果传入）
+    if (router) {
+      i18n.setRouter(router);
+    }
   }
 };
 ```
 
-**更新** 简化后的实现移除了复杂的Vue插件注册过程，采用更直接的实例化方式。
+**更新** 简化后的实现移除了复杂的Vue插件注册过程，采用更直接的实例化方式，并新增了中文语言支持的消息配置对象。
 
 **节来源**
 - [index.js](file://lang/index.js)
@@ -704,4 +716,100 @@ ModalContent --> EditForm
 - [packages/libs/textEditMode.js](file://packages/libs/textEditMode.js)
 
 **节来源**
-- [packages/libs/textEditMode.js](file://packages/libs/textEditMode.js)
+- [packages/libs/textEditMode.js](file://packages/libs/textEditMode.js)
+
+## 中文语言支持配置
+
+### 配置对象结构
+
+系统现在支持在`lang/index.js`中直接配置中文语言支持的消息对象：
+
+```javascript
+const i18n = new gc_i18n({
+  appCode: "TEST-SRC",
+  orgCode: import.meta.env.MODE === "unit" ? "DD" : "GREENCLOUD",
+  env: "dev",
+  messages: {
+    "zh-CN": {
+      test: "测试"
+    }
+  },
+  login: false
+});
+```
+
+### 配置特点
+
+1. **直接配置**：通过`messages`选项直接提供语言配置
+2. **多语言支持**：支持同时配置多种语言的消息
+3. **灵活扩展**：可以根据需要添加更多语言配置
+4. **环境适配**：支持基于环境变量的配置切换
+
+### 使用场景
+
+这种配置方式特别适用于：
+- 需要在应用启动时就提供本地翻译的场景
+- 团队内部开发阶段的快速测试
+- 需要离线运行的应用环境
+- 对翻译数据进行本地化定制的场景
+
+**节来源**
+- [index.js](file://lang/index.js)
+
+## 全局组件注册机制
+
+### 增强的组件注册
+
+系统在`packages/index.js`中增强了全局组件注册功能，通过`install`方法自动注册全局组件：
+
+```javascript
+install(app, opts = {}) {
+  // 兼容 Vue 2 和 Vue 3
+  if (isVue2) {
+    // Vue 2: 直接在 Vue 原型上挂载 $t 和 $i18n
+    const Vue = VueDemi;
+    Vue.prototype.$t = this.t || globalThis.$t;
+    Vue.prototype.$i18n = this.i18n;
+  } else {
+    // Vue 3: 通过 globalProperties 挂载 $t 和 $i18n
+    app.config.globalProperties.$t = this.t || globalThis.$t;
+    app.config.globalProperties.$i18n = this.i18n;
+  }
+
+  // 自动注册全局组件，传入 baseUrl
+  app.component("i18n-earth", {
+    ...earthVue,
+    props: {
+      ...earthVue.props,
+      baseUrl: {
+        type: String,
+        default: this.baseUrl
+      }
+    }
+  });
+
+  window.top.addEventListener("message", (event) => {
+    // 处理消息事件
+  });
+}
+```
+
+### 组件注册特点
+
+1. **自动注册**：通过`install`方法自动注册全局组件
+2. **Vue版本兼容**：同时支持Vue 2和Vue 3的组件注册方式
+3. **属性传递**：向注册的组件传递必要的属性（如baseUrl）
+4. **事件监听**：自动监听来自父窗口的消息事件
+
+### 使用方式
+
+```javascript
+// 在应用中使用
+app.use(i18n);
+
+// 在组件中使用
+<i18n-earth />
+```
+
+**节来源**
+- [packages/index.js](file://packages/index.js)