gc_i18n 1.4.7 → 1.4.8

package/.qoder/repowiki/zh/content/API /345/217/202/350/200/203.md"

@@ -3,16 +3,20 @@
 <cite>
 **本文档中引用的文件**   
 - [package.json](file://package.json) - *版本信息，从1.4.3升级到1.4.4*
-- [gc_i18n.es.js](file://lib/gc_i18n.es.js) - *在最近的提交中更新*
+- [packages/index.js](file://packages/index.js) - *库的入口点，包含初始化逻辑和setRouter方法*
+- [lib/gc_i18n.es.js](file://lib/gc_i18n.es.js) - *在最近的提交中更新，包含setRouter方法*
 - [i18nUtils.ts](file://packages/libs/i18nUtils.ts) - *在最近的提交中更新*
 - [service.js](file://packages/libs/service.js) - *在最近的提交中更新，包含关键逻辑变更*
 - [utils.js](file://packages/libs/utils.js) - *在最近的提交中更新，包含 mergeArraysByKey 函数*
-- [packages/index.js](file://packages/index.js) - *库的入口点，包含初始化逻辑*
+- [src/main.js](file://src/main.js) - *应用入口，展示如何集成gc_i18n*
+- [src/router/index.js](file://src/router/index.js) - *路由配置示例*
 </cite>
 
 ## 更新摘要
 **变更内容**   
 - 版本从 1.4.3 升级到 1.4.4
+- 新增 `setRouter` 方法，支持延迟设置Vue Router实例
+- 增强的路由守卫功能，自动集成模态框关闭和翻译键收集
 - 更新了 `packages/index.js` 中路由守卫的 `closeModal` 功能集成
 - 更新了 `gc_i18n.es.js` 中 `$t` 方法的文档，详细说明了其新的查找优先级
 - 更新了 `utils.js` 中 `mergeArraysByKey` 函数的文档
@@ -22,41 +26,171 @@
 ## 目录
 1. [简介](#简介)
 2. [核心 API 概述](#核心-api-概述)
-3. [gc_i18n.es.js 公共方法](#gc_i18nesjs-公共方法)
-4. [i18nUtils.ts 工具函数](#i18nutilsts-工具函数)
-5. [service.js 异步接口](#servicesjs-异步接口)
-6. [使用示例与最佳实践](#使用示例与最佳实践)
-7. [错误处理与限制](#错误处理与限制)
+3. [packages/index.js 公共方法](#packagesindexjs-公共方法)
+4. [lib/gc_i18n.es.js 公共方法](#libgc_i18nesjs-公共方法)
+5. [i18nUtils.ts 工具函数](#i18nutilsts-工具函数)
+6. [service.js 异步接口](#servicesjs-异步接口)
+7. [使用示例与最佳实践](#使用示例与最佳实践)
+8. [错误处理与限制](#错误处理与限制)
 
 ## 简介
-本 API 参考文档详细描述了 `gc_i18n` 国际化库的核心功能与接口。文档涵盖 `gc_i18n.es.js` 暴露的公共方法、`i18nUtils.ts` 中的工具函数以及 `service.js` 提供的异步服务接口。目标是为开发者提供一份全面、准确且易于理解的参考，以支持国际化功能的集成与开发。
+本 API 参考文档详细描述了 `gc_i18n` 国际化库的核心功能与接口。文档涵盖 `packages/index.js` 和 `lib/gc_i18n.es.js` 暴露的公共方法、`i18nUtils.ts` 中的工具函数以及 `service.js` 提供的异步服务接口。目标是为开发者提供一份全面、准确且易于理解的参考，以支持国际化功能的集成与开发。
 
 ## 核心 API 概述
 `gc_i18n` 库通过 Vue 3 的插件机制提供国际化支持。其核心功能包括：
 - **翻译功能**：通过 `$t` 方法在模板或代码中获取翻译文本。
 - **语言切换**：通过 `$changeLocale` 方法动态切换当前语言环境。
+- **路由器集成**：通过 `setRouter` 方法设置Vue Router实例，自动初始化路由守卫。
 - **语言包管理**：通过 `service.js` 提供的接口从后端获取和更新翻译资源。
 - **工具支持**：提供静态分析工具函数，用于提取项目中的翻译键。
 - **模态框关闭**：通过 `closeModal` 方法统一管理 SweetAlert2 模态框的关闭。
 
 **Section sources**
-- [gc_i18n.es.js](file://lib/gc_i18n.es.js)
+- [packages/index.js](file://packages/index.js)
+- [lib/gc_i18n.es.js](file://lib/gc_i18n.es.js)
 - [service.js](file://packages/libs/service.js)
 - [i18nUtils.ts](file://packages/libs/i18nUtils.ts)
 
-## gc_i18n.es.js 公共方法
-`gc_i18n.es.js` 作为库的核心，通过向 Vue 应用实例的 `config.globalProperties` 挂载方法来暴露其公共 API。这些方法在 Vue 组件的模板和 `setup` 函数中均可直接使用。
+## packages/index.js 公共方法
+`packages/index.js` 作为库的主要入口点，提供了完整的国际化功能实现。该类通过构造函数接收配置选项，并提供多种公共方法供开发者使用。
+
+### 构造函数 (I18n)
+构造函数初始化国际化实例，支持多种配置选项。
+
+**方法签名**
+```typescript
+constructor(options?: {
+  router?: any;
+  appCode?: string;
+  messages?: Record<string, any>;
+  token?: string;
+  orgCode?: string;
+  loginRouteName?: string;
+  login?: boolean;
+  keyboard?: string;
+  locale?: string;
+  env?: string;
+  dev?: boolean;
+})
+```
+
+**参数**
+- **router**: `any` (可选) - Vue Router 实例，允许延迟设置
+- **appCode**: `string` (可选) - 应用唯一标识码
+- **messages**: `Record<string, any>` (可选) - 本地消息覆盖
+- **token**: `string` (可选) - 认证令牌
+- **orgCode**: `string` (可选) - 组织代码，用于生成JWT
+- **loginRouteName**: `string` (可选, 默认: `"login"`) - 登录路由名称
+- **login**: `boolean` (可选) - 是否启用登录功能
+- **keyboard**: `string` (可选, 默认: `"ctrl+shift+l"`) - 快捷键配置
+- **locale**: `string` (可选) - 默认语言环境
+- **env**: `string` (可选) - 环境配置 (`"dev"|"local"|其他"`)
+- **dev**: `boolean` (可选) - 开发模式开关
+
+**返回值**
+- `I18n` - 初始化后的国际化实例
+
+**使用示例**
+```javascript
+import I18n from 'gc_i18n';
+
+const i18n = new I18n({
+  appCode: 'YOUR_APP_CODE',
+  router: vueRouter,
+  locale: 'zh-CN'
+});
+```
+
+**Section sources**
+- [packages/index.js:81-139](file://packages/index.js#L81-L139)
+
+### setRouter (设置路由器)
+设置Vue Router实例，支持延迟设置。该方法会自动初始化路由守卫。
+
+**方法签名**
+```typescript
+setRouter(router: any): I18n
+```
+
+**参数**
+- **router**: `any` - Vue Router 实例
+
+**返回值**
+- `I18n` - 返回当前实例，支持链式调用
+
+**副作用**
+- 设置 `this.router` 属性
+- 调用 `initRouterGuards()` 初始化路由守卫
+- 支持链式调用返回当前实例
+
+**使用限制**
+- 该方法支持延迟设置，即可以在实例创建后任意时间设置router
+- 如果router已经存在，会直接初始化路由守卫
+- 返回当前实例，便于链式调用
+
+**错误处理建议**
+- 确保传入的router是有效的Vue Router实例
+- 在调用前检查router实例的状态
+- 如需重新初始化，可再次调用此方法
+
+**Section sources**
+- [packages/index.js:221-230](file://packages/index.js#L221-L230)
+
+### initRouterGuards (初始化路由守卫)
+初始化路由守卫，自动处理模态框关闭、翻译键收集和语言切换。
+
+**方法签名**
+```typescript
+initRouterGuards(): void
+```
+
+**参数**
+- 无参数
+
+**返回值**
+- `void` - 无返回值
+
+**副作用**
+- 注册 `beforeEach` 和 `afterEach` 路由守卫
+- 自动关闭 SweetAlert2 弹窗
+- 收集翻译键并更新 `translationKeys`
+- 设置当前路由名称
+- 更新 `I18N_CONFIG` 中的 `routerName`
+
+**增强功能**
+- **自动模态框管理**：在路由切换时自动调用 `closeModal()`
+- **翻译键收集**：自动收集当前页面使用的翻译键
+- **异步组件支持**：支持动态导入的异步组件
+- **登录路由检测**：自动识别登录路由并收集特殊翻译键
+- **路由名称跟踪**：维护当前路由名称以便 `$t` 方法使用
+
+**使用限制**
+- 仅在 `router` 存在时执行
+- 防止重复注册路由守卫
+- 处理异步组件加载错误
+
+**错误处理建议**
+- 捕获异步组件加载异常
+- 处理路由守卫注册冲突
+- 确保 `configInstance` 存在时才调用 `closeModal()`
+
+**Section sources**
+- [packages/index.js:232-335](file://packages/index.js#L232-L335)
+
+## lib/gc_i18n.es.js 公共方法
+`lib/gc_i18n.es.js` 作为库的核心，通过向 Vue 应用实例的 `config.globalProperties` 挂载方法来暴露其公共 API。这些方法在 Vue 组件的模板和 `setup` 函数中均可直接使用。
 
 ### $t (翻译方法)
 此方法用于根据给定的键（key）查找并返回对应的翻译文本。
 
 **方法签名**
 ```typescript
-$t(key: string): string
+$t(key: string, defaultValue?: string): string
 ```
 
 **参数**
-- **key**: `string` - 翻译资源的唯一标识符。例如 `"welcome_message"` 或 `"description"`。
+- **key**: `string` - 翻译资源的唯一标识符
+- **defaultValue**: `string` (可选) - 当翻译不存在时的默认值
 
 **返回值**
 - `string` - 与 `key` 对应的翻译文本。如果未找到匹配的翻译，则返回原始 `key`。
@@ -65,6 +199,12 @@ $t(key: string): string
 - 无直接副作用。其行为依赖于当前激活的语言环境和已加载的翻译资源。
 - 在内部，它会将 `key` 记录到 `translationKeySet` 中，用于后续的翻译键收集。
 
+**查找优先级**
+该方法的查找逻辑已更新，优先级为：
+1. `当前路由名.key` - 首选，针对特定路由的翻译
+2. `common.key` - 次选，通用翻译
+3. `key` - 最后选择，基础翻译
+
 **使用限制**
 - `key` 必须是字符串类型。
 - 该方法依赖于 `init` 过程中加载的语言包，若语言包未正确加载，可能返回不准确的翻译。
@@ -73,12 +213,8 @@ $t(key: string): string
 - 在调用 `$t` 前，确保 `init` 过程已完成。
 - 在开发环境中，检查控制台日志以确认是否存在未找到的翻译键。
 
-**更新** 该方法的查找逻辑已更新，优先级为：`当前路由名.key` > `common.key` > `key`。
-
 **Section sources**
-- [gc_i18n.es.js:315-364](file://lib/gc_i18n.es.js#L315-L364) - *更新了 $t 方法的实现*
-- [src/view/Home.vue](file://src/view/Home.vue#L19)
-- [src/view/login.vue](file://src/view/login.vue#L10)
+- [lib/gc_i18n.es.js:2954-2971](file://lib/gc_i18n.es.js#L2954-L2971)
 
 ### $changeLocale (切换语言方法)
 此方法用于动态更改当前应用的语言环境。
@@ -107,12 +243,8 @@ $changeLocale(locale: string): Promise<void>
 - 使用 `try-catch` 包裹异步调用，以捕获可能的网络错误。
 - 提供用户友好的错误提示，例如"切换语言失败，请稍后重试"。
 
-**更新** 该方法的实现已更新，现在通过调用 `setLanguage` 方法来完成核心逻辑。
-
 **Section sources**
-- [gc_i18n.es.js:383-392](file://lib/gc_i18n.es.js#L383-L392) - *更新了 $changeLocale 方法的实现*
-- [src/view/Home.vue](file://src/view/Home.vue#L2)
-- [src/view/login.vue](file://src/view/login.vue#L2)
+- [lib/gc_i18n.es.js:2979-2981](file://lib/gc_i18n.es.js#L2979-L2981)
 
 ### closeModal (关闭模态框方法)
 此方法用于统一关闭 SweetAlert2 弹窗，确保模态框的正确销毁和资源清理。
@@ -143,11 +275,8 @@ closeModal(): void
 - 监听 `willClose` 和 `didClose` 事件以处理关闭后的逻辑
 - 在路由切换时自动调用此方法，避免弹窗残留
 
-**新增** 该方法作为 SweetAlert2 的别名方法，提供统一的模态框关闭接口。
-
 **Section sources**
-- [gc_i18n.es.js:1340-1350](file://lib/gc_i18n.es.js#L1340-L1350) - *新增 closeModal 方法实现*
-- [gc_i18n.es.js:1930-1932](file://lib/gc_i18n.es.js#L1930-L1932) - *closeModal 方法别名注册*
+- [lib/gc_i18n.es.js:1340-1350](file://lib/gc_i18n.es.js#L1340-L1350)
 
 ## i18nUtils.ts 工具函数
 `i18nUtils.ts` 文件提供了一个用于静态分析的工具函数，帮助开发者管理和审计翻译资源。
@@ -176,7 +305,7 @@ function extractTranslationKeys(component: any): string[]
 - 开发者手动检查组件，以确保所有翻译键都已定义。
 
 **Section sources**
-- [i18nUtils.ts:1-54](file://packages/libs/i18nUtils.ts#L1-L54) - *文件内容未变，但其提取的键会影响 $t 的行为*
+- [i18nUtils.ts:1-54](file://packages/libs/i18nUtils.ts#L1-L54)
 
 ## service.js 异步接口
 `service.js` 封装了与后端语言服务通信的异步接口，负责获取和管理翻译数据。
@@ -215,10 +344,8 @@ getLanguagesWithCache({ baseUrl, token, appCode, isRemote }: {
 - 确保 `store2` 正常工作，本地存储空间充足。
 - 处理网络请求失败的情况，提供降级方案（如使用缓存数据）。
 
-**更新** 新增的带缓存功能，提高了语言列表获取的性能和可靠性。
-
 **Section sources**
-- [service.js:19-61](file://packages/libs/service.js#L19-L61) - *新增的带缓存语言列表获取功能*
+- [service.js:19-61](file://packages/libs/service.js#L19-L61)
 
 ### getLanguages (获取支持的语言列表)
 获取系统支持的所有语言环境列表。
@@ -236,8 +363,6 @@ getLanguages({ baseUrl, token, appCode }: { baseUrl: string; token: string; appC
 **返回值**
 - `Promise<any>` - 一个 Promise，resolve 时返回包含支持语言列表的响应对象。
 
-**更新** 端点已标准化为 `/i18n-web/app/getsupportedlangs`，移除了重复的斜杠。
-
 **Section sources**
 - [service.js:63-72](file://packages/libs/service.js#L63-L72)
 
@@ -265,8 +390,6 @@ fetchTranslate({ appCode, language, lastPullDate, baseUrl, token }: {
 **返回值**
 - `Promise<any>` - 一个 Promise，resolve 时返回包含翻译数据的对象。如果请求成功，`res.data.result` 为 0，则返回 `res.data.retVal`；否则返回整个 `res` 对象。
 
-**更新** 移除了 `page` 参数，更新了函数签名和参数说明。
-
 **Section sources**
 - [service.js:74-101](file://packages/libs/service.js#L74-L101)
 
@@ -307,7 +430,7 @@ getTranslate({ baseUrl, appCode, language, token, routerName }: {
 **更新** 该方法的行为已更新，当从后端获取到 `common` 类型的翻译时，会移除当前路由中同名的翻译数据。
 
 **Section sources**
-- [service.js:133-186](file://packages/libs/service.js#L133-L186) - *更新了 getTranslate 方法的实现*
+- [service.js:133-186](file://packages/libs/service.js#L133-L186)
 
 ### userDicts (用户词典)
 提交用户自定义的翻译词典。
@@ -349,6 +472,46 @@ saveTranslate({ data, token, baseUrl }: { data: any; token: string; baseUrl: str
 
 ## 使用示例与最佳实践
 
+### 基本初始化
+```javascript
+import { createApp } from 'vue';
+import I18n from 'gc_i18n';
+import router from './router';
+
+const app = createApp(App);
+
+// 创建国际化实例
+const i18n = new I18n({
+  appCode: 'YOUR_APP_CODE',
+  router: router,
+  locale: 'zh-CN'
+});
+
+// 安装插件
+app.use(i18n);
+```
+
+### 延迟设置路由器
+```javascript
+import { createApp } from 'vue';
+import I18n from 'gc_i18n';
+import router from './router';
+
+const app = createApp(App);
+
+// 先创建国际化实例，稍后再设置router
+const i18n = new I18n({
+  appCode: 'YOUR_APP_CODE',
+  locale: 'zh-CN'
+});
+
+// 稍后设置router
+i18n.setRouter(router);
+
+// 安装插件
+app.use(i18n);
+```
+
 ### 在 Vue 模板中使用 $t
 ```vue
 <template>
@@ -415,6 +578,8 @@ this.router.beforeEach(async (to, from, next) => {
 - **参数变更**: `fetchTranslate` 函数已移除 `page` 参数，使用时请注意更新调用方式。
 - **端点标准化**: 所有翻译服务端点已标准化为 `/i18n-web/...` 结构，确保了后端服务的一致性。
 - **模态框管理**: 新增的 `closeModal` 方法提供了统一的 SweetAlert2 弹窗管理，避免了弹窗残留问题。
+- **路由守卫增强**: `setRouter` 方法和增强的路由守卫功能提供了更完善的路由集成体验。
+- **延迟设置支持**: `setRouter` 方法支持延迟设置，提高了库的灵活性。
 - **版本更新** 本版本为 1.4.4，包含上述重要变更，特别是路由守卫中自动调用 `closeModal` 的功能集成。
 
 **版本更新** 本版本为 1.4.4，包含上述重要变更，特别是路由守卫中自动调用 `closeModal` 的功能集成。