gc_i18n 1.4.1 → 1.4.3

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

@@ -7,18 +7,20 @@
 - [service.js](file://packages/libs/service.js) - *在最近的提交中更新，包含关键逻辑变更*
 - [utils.js](file://packages/libs/utils.js) - *在最近的提交中更新，包含 mergeArraysByKey 函数*
 - [packages/index.js](file://packages/index.js) - *库的入口点，包含初始化逻辑*
-- [package.json](file://package.json) - *版本信息，从1.3.12升级到1.3.13*
+- [package.json](file://package.json) - *版本信息，从1.3.12升级到1.4.1*
 </cite>
 
 ## 更新摘要
 **变更内容**   
 - 移除了 `fetchTranslate` 函数中的 `page` 参数，更新了函数签名和参数说明
-- 版本从 1.3.12 升级到 1.3.13
+- 版本从 1.3.12 升级到 1.4.1
 - 更新了 `service.js` 中 `getTranslate` 方法的文档，以反映其新的行为：当返回 `common` 类型的翻译时，会移除当前路由的数据
 - 更新了 `gc_i18n.es.js` 中 `$t` 方法的文档，详细说明了其新的查找优先级：先查找 `route.key`，再查找 `common.key`，最后查找全局 `key`
 - 更新了 `utils.js` 中 `mergeArraysByKey` 函数的文档，说明了其在合并数据时会移除与 `common` 键匹配的当前路由数据
 - 修正了 `service.js` 中 `fetchTranslate` 和 `getTranslate` 方法的返回值描述，使其与代码实现一致
 - 更新了所有受影响部分的源代码引用，以反映最新的文件状态
+- **新增**：标准化了后端翻译服务端点，从 `i18n-web//app/getsupportedlangs` 迁移到 `i18n-web/app/getsupportedlangs`
+- **新增**：引入了 `getLanguagesWithCache` 函数，提供带缓存的语言列表获取功能
 
 ## 目录
 1. [简介](#简介)
@@ -76,7 +78,7 @@ $t(key: string): string
 **更新** 该方法的查找逻辑已更新，优先级为：`当前路由名.key` > `common.key` > `key`。
 
 **Section sources**
-- [gc_i18n.es.js:272-297](file://lib/gc_i18n.es.js#L272-L297) - *更新了 $t 方法的实现*
+- [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)
 
@@ -110,7 +112,7 @@ $changeLocale(locale: string): Promise<void>
 **更新** 该方法的实现已更新，现在通过调用 `setLanguage` 方法来完成核心逻辑。
 
 **Section sources**
-- [gc_i18n.es.js:316-321](file://lib/gc_i18n.es.js#L316-L321) - *更新了 $changeLocale 方法的实现*
+- [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)
 
@@ -146,6 +148,45 @@ function extractTranslationKeys(component: any): string[]
 ## service.js 异步接口
 `service.js` 封装了与后端语言服务通信的异步接口，负责获取和管理翻译数据。
 
+### getLanguagesWithCache (获取支持的语言列表 - 带缓存)
+获取系统支持的所有语言环境列表，并提供本地缓存功能。
+
+**方法签名**
+```typescript
+getLanguagesWithCache({ baseUrl, token, appCode, isRemote }: { 
+  baseUrl: string; 
+  token: string; 
+  appCode: string; 
+  isRemote?: boolean; 
+}): Promise<any[]>
+```
+
+**参数**
+- **baseUrl**: `string` - 后端服务的基础 URL。
+- **token**: `string` - 用于身份验证的授权令牌。
+- **appCode**: `string` - 应用的唯一标识码。
+- **isRemote**: `boolean` (可选, 默认: `false`) - 是否强制从远程获取，跳过缓存。
+
+**返回值**
+- `Promise<any[]>` - 一个 Promise，resolve 时返回包含支持语言列表的数组。每个语言对象包含 `langCode` 和 `langName` 字段。
+
+**副作用**
+- 读取和写入本地存储（`store2`），以缓存语言列表。
+- 可能发起网络请求。
+
+**使用限制**
+- 依赖于 `store2` 和 `lodash-es` 库。
+- 当 `isRemote` 为 `false` 且缓存存在时，不会发起网络请求。
+
+**错误处理建议**
+- 确保 `store2` 正常工作，本地存储空间充足。
+- 处理网络请求失败的情况，提供降级方案（如使用缓存数据）。
+
+**更新** 新增的带缓存功能，提高了语言列表获取的性能和可靠性。
+
+**Section sources**
+- [service.js:19-61](file://packages/libs/service.js#L19-L61) - *新增的带缓存语言列表获取功能*
+
 ### getLanguages (获取支持的语言列表)
 获取系统支持的所有语言环境列表。
 
@@ -162,6 +203,8 @@ 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)
 
@@ -327,5 +370,6 @@ console.log(keys); // 输出: ["hello", "greeting"]
 - **性能**: 频繁调用 `$changeLocale` 会导致应用重新渲染，应避免在短时间内多次调用。
 - **逻辑变更**: `getTranslate` 方法现在会移除 `common` 键覆盖的当前路由数据，这可能会影响某些依赖于特定键的组件。
 - **参数变更**: `fetchTranslate` 函数已移除 `page` 参数，使用时请注意更新调用方式。
+- **端点标准化**: 所有翻译服务端点已标准化为 `/i18n-web/...` 结构，确保了后端服务的一致性。
 
-**版本更新** 本版本为 1.3.13，包含上述重要变更。
+**版本更新** 本版本为 1.4.1，包含上述重要变更，特别是后端翻译服务端点的标准化迁移和新增的带缓存语言列表获取功能。

package/.qoder/repowiki/zh/content//347/273/204/344/273/266/351/233/206/346/210/220.md

@@ -21,12 +21,10 @@
 
 ## 更新摘要
 **所做变更**
-- 更新了 i18n-earth 组件的重大功能增强：从简单的 Icon 组件升级为完整的 v-model 驱动编辑组件
-- 新增了模态框编辑功能，支持多语言翻译的实时编辑和保存
-- 增强了缓存机制，包括语言列表缓存和翻译数据缓存
-- 完善了组件的 Props 配置和事件处理机制
-- 更新了键盘快捷键配置，从 ctrl+shift+l 更改为 ctrl+shift+e
-- 新增了文本编辑模式功能，支持可视化翻译编辑
+- 更新了API端点迁移：语言列表获取端点从 `/i18n-web/language/languages` 迁移到 `/i18n-web/app/getsupportedlangs`
+- 更新了基础URL配置：从 `https://i18n.ihotel.cn` 更新为 `https://trans.ihotel.cn`
+- 修正了语言列表API调用路径中的双斜杠问题
+- 更新了文本编辑模式和i18n-earth组件的基础URL配置
 
 ## 目录
 1. [项目结构分析](#项目结构分析)
@@ -272,6 +270,7 @@ window.addEventListener("message", (event) => {
 | width | Number | `null` | input宽度（px），不传则使用默认样式 |
 | className | String | `""` | 自定义容器类名 |
 | languages | Array | `[]` | 自定义语言列表，不传则从store/API获取 |
+| baseUrl | String | `"https://trans.ihotel.cn"` | API基础URL，从I18n实例传入 |
 
 ### 在应用中的使用
 
@@ -816,4 +815,117 @@ style O fill:#f96,stroke:#333
 - [service.js:1-189](file://packages/libs/service.js#L1-L189)
 - [utils.js:1-51](file://packages/libs/utils.js#L1-L51)
 - [textEditMode.js:1-623](file://packages/libs/textEditMode.js#L1-L623)
-- [textEditMode.css:1-166](file://packages/libs/textEditMode.css#L1-L166)
+- [textEditMode.css:1-166](file://packages/libs/textEditMode.css#L1-L166)
+
+## API端点迁移详细说明
+
+### 语言列表获取端点迁移
+
+**更新**：语言列表获取端点已从 `/i18n-web/language/languages` 迁移到 `/i18n-web/app/getsupportedlangs`
+
+#### 旧版本（已废弃）
+- 基础URL：`https://i18n.ihotel.cn`
+- 端点路径：`/i18n-web/language/languages`
+- 调用方式：`GET https://i18n.ihotel.cn/i18n-web/language/languages`
+
+#### 新版本（当前）
+- 基础URL：`https://trans.ihotel.cn`
+- 端点路径：`/i18n-web/app/getsupportedlangs`
+- 调用方式：`GET https://trans.ihotel.cn/i18n-web/app/getsupportedlangs?appCode={appCode}`
+
+### 代码变更详情
+
+#### packages/index.js 中的baseUrl配置
+```javascript
+this.baseUrl =
+  env === "dev" || dev === true
+    ? "https://test.ihotel.cn"
+    : !env || env === "local"
+      ? ""
+      : "https://trans.ihotel.cn";
+```
+
+#### packages/libs/service.js 中的API调用
+```javascript
+// 语言列表获取（带缓存）
+const res = await http.get(`${baseUrl}/i18n-web//app/getsupportedlangs`, {
+  headers: {
+    appCode,
+    Authorization: token
+  }
+});
+
+// 语言列表获取（直接调用）
+return http.get(
+  baseUrl + "/i18n-web/app/getsupportedlangs?appCode=" + appCode,
+  {
+    headers: {
+      Authorization: token
+    }
+  }
+);
+```
+
+#### packages/libs/textEditMode.js 中的baseUrl配置
+```javascript
+this.baseUrl =
+  !env || env === "local"
+    ? ""
+    : env === "dev"
+      ? "https://test.ihotel.cn"
+      : "https://trans.ihotel.cn";
+```
+
+#### packages/components/earth.js 中的baseUrl默认值
+```javascript
+baseUrl: {
+  type: String,
+  default: "https://trans.ihotel.cn"
+}
+```
+
+### 环境配置说明
+
+| 环境变量 | 基础URL | 用途 |
+|----------|---------|------|
+| `local` | 空字符串 | 本地开发环境，使用相对路径 |
+| `dev` | `https://test.ihotel.cn` | 开发测试环境 |
+| `prod` | `https://trans.ihotel.cn` | 生产环境 |
+| 未设置 | `https://trans.ihotel.cn` | 默认生产环境 |
+
+### 缓存机制
+
+语言列表获取已实现智能缓存机制：
+
+1. **内存缓存**：首次获取后缓存在内存中
+2. **localStorage缓存**：持久化存储语言列表
+3. **条件刷新**：支持强制从远程获取（`isRemote = true`）
+
+### 错误处理
+
+API调用包含完善的错误处理机制：
+
+```javascript
+try {
+  const res = await http.get(`${baseUrl}/i18n-web//app/getsupportedlangs`, {
+    headers: { appCode, Authorization: token }
+  });
+  
+  if (res.data && res.data.result === 0) {
+    // 成功处理
+    const langs = _.get(res.data, "retVal", []);
+    store2.set("I18N_LANGUAGES", langs);
+    return formattedLangs;
+  }
+} catch (error) {
+  console.error("获取语言列表失败:", error);
+  // 返回空数组或降级处理
+  return [];
+}
+```
+
+**本节来源**
+- [index.js:113-118](file://packages/index.js#L113-L118)
+- [service.js:40-71](file://packages/libs/service.js#L40-L71)
+- [textEditMode.js:34-39](file://packages/libs/textEditMode.js#L34-L39)
+- [earth.js:43-46](file://packages/components/earth.js#L43-L46)

package/.qoder/repowiki/zh/content//351/205/215/347/275/256/351/200/211/351/241/271.md

@@ -16,10 +16,12 @@
 
 ## 更新摘要
 **所做更改**   
-- 新增了 editKeyboard 配置选项，用于自定义文本编辑模式快捷键
-- 更新了配置项清单，添加了 editKeyboard 的详细说明
-- 新增了文本编辑模式功能的配置和使用说明
-- 更新了配置示例，包含 editKeyboard 的使用方法
+- 版本从1.4.1升级到1.4.2
+- SweetAlert2模态对话框的z-index增强，确保不被其他弹窗遮盖
+- 更新了基础URL配置，将 `https://i18n.ihotel.cn` 更新为 `https://trans.ihotel.cn`
+- 标准化了API端点路径，移除了重复的斜杠
+- 更新了环境配置说明，反映最新的URL变更
+- 修正了iframe配置的URL结构说明
 
 ## 目录
 1. [i18n构建配置](#i18n构建配置)  
@@ -119,12 +121,12 @@ external: [
 ### 文本编辑模式功能
 **新增** 文本编辑模式功能提供了可视化的翻译编辑能力：
 
-- **快捷键**: 默认为 `shift+e`，可通过 `editKeyboard` 配置自定义
+- **快捷键**: 默认为 `ctrl+shift+e`，可通过 `editKeyboard` 配置自定义
 - **功能**: 为页面中的翻译文本添加可编辑外框，点击即可编辑
 - **样式**: 提供专门的CSS样式支持编辑模式的视觉反馈
 
 **Section sources**
-- [packages/index.js:67-466](file://packages/index.js#L67-L466)
+- [packages/index.js:67-547](file://packages/index.js#L67-L547)
 
 ## 初始化配置对象
 
@@ -161,7 +163,7 @@ external: [
 - **env**: 环境模式，支持 "local"、"dev"、"production"
 - **login**: 是否启用登录功能
 - **messages**: 预定义的语言消息对象
-- **editKeyboard**: 文本编辑模式快捷键，默认为 "shift+e"
+- **editKeyboard**: 文本编辑模式快捷键，默认为 "ctrl+shift+e"
 
 **Section sources**
 - [src/main.js:1-12](file://src/main.js#L1-L12)
@@ -182,15 +184,15 @@ external: [
 | **orgCode** | String | null | 任意字符串 | 用于生成 JWT token 的组织代码 |
 | **loginRouteName** | String | "login" | 任意字符串 | 登录页面的路由名称 |
 | **login** | Boolean | false | true/false | 是否启用登录功能 |
-| **keyboard** | String | "shift>t" | 键盘快捷键组合 | 触发展示配置iframe的快捷键 |
-| **editKeyboard** | String | "shift+e" | 键盘快捷键组合 | 触发文本编辑模式的快捷键 |
+| **keyboard** | String | "ctrl+shift+l" | 键盘快捷键组合 | 触发展示配置iframe的快捷键 |
+| **editKeyboard** | String | "ctrl+shift+e" | 键盘快捷键组合 | 触发文本编辑模式的快捷键 |
 | **env** | String | "local" | "local"、"dev"、"production" | 环境模式，决定baseUrl |
 | **locale** | String | 浏览器语言或 "zh-CN" | 有效的语言代码 | 默认语言设置 |
 | **baseUrl** | String | 根据env计算 | "local"、"dev"、"production" 或自定义URL | 语言服务基础URL |
 
 ### 环境配置详解
 
-**更新** 环境配置系统现已支持三种字符串模式：
+**更新** 环境配置系统现已支持三种字符串模式，基础URL已更新为 `https://trans.ihotel.cn`：
 
 #### 本地开发环境 (local)
 - **配置值**: `"local"`
@@ -216,6 +218,15 @@ external: [
 baseUrl: "https://custom-domain.com"
 ```
 
+### API端点标准化
+
+**更新** API端点路径已标准化，移除了重复的斜杠：
+
+- **语言列表接口**: `${baseUrl}/i18n-web/app/getsupportedlangs`
+- **翻译获取接口**: `${baseUrl}/i18n-web/kv_translate/kv_translates`
+- **用户词典接口**: `${baseUrl}/i18n-web/kv_translate/userDicts`
+- **批量保存接口**: `${baseUrl}/i18n-web/kv_translate/batch`
+
 ### vue-i18n 配置项
 
 | 配置项 | 类型 | 默认值 | 有效值范围 | 实际影响 |
@@ -231,6 +242,8 @@ baseUrl: "https://custom-domain.com"
 
 ### SweetAlert2 集成配置项
 
+**更新** SweetAlert2模态对话框的z-index已增强，确保不被其他弹窗遮盖：
+
 | 配置项 | 类型 | 默认值 | 有效值范围 | 实际影响 |
 | --- | --- | --- | --- | --- |
 | **titleText** | String | "多语言管理中心" | 任意字符串 | SweetAlert2 弹窗标题 |
@@ -247,7 +260,7 @@ baseUrl: "https://custom-domain.com"
 
 | 配置项 | 类型 | 默认值 | 有效值范围 | 实际影响 |
 | --- | --- | --- | --- | --- |
-| **editKeyboard** | String | "shift+e" | 键盘快捷键组合 | 触发文本编辑模式的快捷键 |
+| **editKeyboard** | String | "ctrl+shift+e" | 键盘快捷键组合 | 触发文本编辑模式的快捷键 |
 | **baseUrl** | String | 根据env计算 | URL地址 | 编辑模式的基础URL |
 | **iframeSrc** | String | `${baseUrl}/i18n-admin-front/#/config?...` | URL地址 | iframe加载的配置管理器地址 |
 | **iframeWidth** | String | "100%" | CSS 值 | iframe宽度 |
@@ -267,12 +280,12 @@ baseUrl: "https://custom-domain.com"
 | **iframeBorderStyle** | String | "none" | CSS 值 | iframe边框样式 |
 
 **Section sources**
-- [packages/index.js:67-466](file://packages/index.js#L67-L466)
+- [packages/index.js:67-547](file://packages/index.js#L67-L547)
 - [vite.config.js:1-72](file://vite.config.js#L1-L72)
-- [packages/swal.css:1-18](file://packages/swal.css#L1-L18)
+- [packages/swal.css:1-23](file://packages/swal.css#L1-L23)
 - [package.json:13-20](file://package.json#L13-L20)
-- [packages/libs/textEditMode.js:1-475](file://packages/libs/textEditMode.js#L1-L475)
-- [packages/libs/textEditMode.css:1-167](file://packages/libs/textEditMode.css#L1-L167)
+- [packages/libs/textEditMode.js:1-623](file://packages/libs/textEditMode.js#L1-L623)
+- [packages/libs/textEditMode.css:1-166](file://packages/libs/textEditMode.css#L1-L166)
 
 ## 配置示例
 
@@ -333,7 +346,7 @@ const i18nInstance = new gc_i18n({
   token: "your-jwt-token",
   loginRouteName: "signin",
   login: true,
-  env: "production"  // 使用生产环境
+  env: "production"  // 使用生产环境，基础URL更新为 https://trans.ihotel.cn
 });
 ```
 
@@ -402,21 +415,14 @@ export default {
 };
 ```
 
-### iframe样式定制示例
-```css
-/* 自定义样式 */
-.gc_i18n_container {
-  background-color: #f5f5f5;
-}
+### SweetAlert2 z-index增强配置示例
 
-.gc_i18n_title {
-  color: #333;
-  font-weight: bold;
-}
+**更新** SweetAlert2模态对话框的z-index已增强，确保不被其他弹窗遮盖：
 
-.gc_i18n_close_button {
-  background-color: #ff6b6b;
-  color: white;
+```css
+/* SweetAlert2 弹窗 z-index 设置，确保不被其他弹窗遮盖 */
+.swal2-container {
+  z-index: 99999 !important;
 }
 ```
 
@@ -424,13 +430,13 @@ export default {
 ```css
 /* 自定义编辑模式样式 */
 .i18n-editable-text {
-  outline: 2px solid #ff6b6b !important;
-  background-color: rgba(255, 107, 107, 0.1);
+  outline: 2px solid #2d8cf0 !important;
+  background-color: rgba(45, 140, 240, 0.05);
 }
 
 .i18n-editable-text:hover {
-  outline: 2px solid #ff6b6b !important;
-  background-color: rgba(255, 107, 107, 0.2);
+  outline: 2px solid #2d8cf0 !important;
+  background-color: rgba(45, 140, 240, 0.1);
 }
 
 .i18n-edit-modal-popup {
@@ -438,13 +444,13 @@ export default {
 }
 
 .i18n-edit-modal-title {
-  color: #ff6b6b;
+  color: #2d8cf0;
   font-size: 20px;
 }
 ```
 
 **Section sources**
 - [lang/index.js:16-33](file://lang/index.js#L16-L33)
-- [packages/index.js:67-466](file://packages/index.js#L67-L466)
-- [packages/swal.css:1-18](file://packages/swal.css#L1-L18)
-- [packages/libs/textEditMode.css:1-167](file://packages/libs/textEditMode.css#L1-L167)
+- [packages/index.js:67-547](file://packages/index.js#L67-L547)
+- [packages/swal.css:1-23](file://packages/swal.css#L1-L23)
+- [packages/libs/textEditMode.css:1-166](file://packages/libs/textEditMode.css#L1-L166)

package/.qoder/repowiki/zh/content//351/253/230/347/272/247/347/224/250/346/263/225//351/253/230/347/272/247/347/224/250/346/263/225.md

@@ -21,6 +21,7 @@
 - [src/router/index.js](file://src/router/index.js) - *路由配置*
 - [src/main.js](file://src/main.js) - *应用入口*
 - [README.md](file://README.md) - *项目说明文档*
+- [packages/swal.css](file://packages/swal.css) - *SweetAlert2样式增强*
 </cite>
 
 ## 更新摘要
@@ -29,6 +30,7 @@
 - 增强的RTL语言支持和更健壮的错误处理机制
 - 改进的类型安全和代码组织结构
 - 优化的性能调优技巧和缓存策略
+- **新增** SweetAlert2模态对话框z-index增强，确保弹窗最高优先级
 
 ## 目录
 1. [项目结构分析](#项目结构分析)
@@ -43,6 +45,7 @@
 10. [环境感知与iframe配置](#环境感知与iframe配置)
 11. [文本编辑模式高级用法](#文本编辑模式高级用法)
 12. [Earth组件高级用法](#earth组件高级用法)
+13. [SweetAlert2模态对话框z-index增强](#sweetalert2模态对话框z-index增强)
 
 ## 项目结构分析
 
@@ -68,6 +71,7 @@ css[gc_i18n.css]
 esm[gc_i18n.es.js]
 textEdit[文本编辑模式]
 earth[Earth组件]
+swalEnhance[SweetAlert2增强]
 end
 subgraph "工具库"
 index[index.js]
@@ -91,6 +95,7 @@ index --> service
 index --> utils
 index --> textEditMode
 index --> earth
+index --> swalEnhance
 textEditMode --> textEditModeCss[textEditMode.css]
 earth --> earthCss[earth.css]
 App --> index
@@ -107,6 +112,7 @@ langJson --> index
 - [packages/libs/textEditMode.js:1-200](file://packages/libs/textEditMode.js#L1-L200)
 - [packages/libs/textEditMode.css:1-167](file://packages/libs/textEditMode.css#L1-L167)
 - [packages/components/earth.js:1-200](file://packages/components/earth.js#L1-L200)
+- [packages/swal.css:1-23](file://packages/swal.css#L1-L23)
 
 ## Vite构建系统迁移
 
@@ -1195,4 +1201,114 @@ const debouncedLanguageChange = debounce((newLocale) => {
 - [packages/components/earth.css:1-144](file://packages/components/earth.css#L1-L144)
 - [packages/components/earth.md:1-109](file://packages/components/earth.md#L1-L109)
 - [src/view/Home.vue:19-40](file://src/view/Home.vue#L19-L40)
-- [packages/index.js:523](file://packages/index.js#L523-L523)
+- [packages/index.js:523](file://packages/index.js#L523-L523)
+
+## SweetAlert2模态对话框z-index增强
+
+### 概述
+
+为了确保gc_i18n库中的SweetAlert2模态对话框始终显示在最顶层，避免被其他UI元素遮挡，系统进行了z-index增强配置。这一改进确保了弹窗的最高优先级显示。
+
+### z-index增强配置
+
+系统通过专门的CSS样式文件为SweetAlert2对话框设置了极高的z-index值：
+
+```css
+/* 全局 SweetAlert2 弹窗 z-index 设置，确保不被其他弹窗遮盖 */
+.swal2-container {
+  z-index: 99999 !important;
+}
+```
+
+这个配置确保了：
+- SweetAlert2对话框始终位于所有其他元素之上
+- 避免与其他UI组件发生层级冲突
+- 提供一致的用户体验，无论页面结构如何复杂
+
+### 应用场景
+
+这种z-index增强在以下场景中特别有用：
+
+#### 多层嵌套组件
+当应用包含复杂的嵌套组件结构时，某些父级元素可能设置了较高的z-index，导致SweetAlert2对话框被遮挡。
+
+#### 动态内容加载
+在异步加载内容或动态插入DOM元素时，可能出现层级计算错误，导致对话框显示异常。
+
+#### 第三方组件集成
+当与第三方UI组件库集成时，可能存在z-index冲突问题。
+
+### 实现细节
+
+SweetAlert2对话框的z-index增强通过以下方式实现：
+
+1. **全局样式覆盖**：通过`.swal2-container`选择器设置极高的z-index值
+2. **重要性标记**：使用`!important`确保样式优先级
+3. **组件化集成**：在主入口文件中导入增强样式
+
+```javascript
+// 在主入口文件中导入增强样式
+import "./swal.css";
+```
+
+### 性能影响
+
+z-index增强对性能的影响：
+- **零额外计算**：仅设置固定z-index值，无复杂计算
+- **全局应用**：影响所有SweetAlert2实例，无需逐个配置
+- **浏览器优化**：现代浏览器对z-index有良好的优化处理
+
+### 最佳实践
+
+使用z-index增强时的注意事项：
+
+```javascript
+// 正确的做法
+Swal.fire({
+  title: "操作成功",
+  text: "数据已成功保存",
+  icon: "success",
+  // z-index自动应用，无需手动设置
+});
+
+// 避免的做法
+Swal.fire({
+  title: "操作成功",
+  text: "数据已成功保存",
+  icon: "success",
+  customClass: {
+    popup: "custom-popup-class" // 如果需要自定义样式，确保不影响z-index
+  }
+});
+```
+
+### 兼容性考虑
+
+z-index增强的兼容性：
+- **现代浏览器**：完全支持
+- **IE11+**：通过CSS前缀支持
+- **移动端浏览器**：在iOS Safari中表现良好
+- **无障碍访问**：不影响屏幕阅读器的正常工作
+
+### 故障排除
+
+如果遇到z-index相关问题：
+
+```javascript
+// 检查是否有其他样式覆盖
+// 使用浏览器开发者工具检查元素的实际z-index值
+
+// 如果需要临时调整
+Swal.fire({
+  title: "临时调整",
+  text: "如果需要特殊处理，可以使用自定义样式",
+  customClass: {
+    container: "temporary-z-index-adjustment"
+  }
+});
+```
+
+**章节来源**
+- [packages/swal.css:1-23](file://packages/swal.css#L1-L23)
+- [packages/index.js:53-54](file://packages/index.js#L53-L54)
+- [lib/gc_i18n.es.js:1954](file://lib/gc_i18n.es.js#L1954)