pan/heros

Files

panw 4235e3b776 refactor(game): 移除已弃用的事件常量

- 删除 UpdateHero 和 UpdateFightHero 事件
- 移除 MISSION_UPDATE 事件常量
- 优化游戏事件枚举定义

2025-10-28 16:15:47 +08:00

14 KiB

Raw Blame History

多语言支持系统文档

**本文档中引用的文件** - [config.json](file://assets/resources/config.json) - [en.json](file://assets/resources/language/json/en.json) - [zh.json](file://assets/resources/language/json/zh.json) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts) - [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts) - [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts) - [SIconComp.ts](file://assets/script/game/map/SIconComp.ts) - [ViewModelScript.md](file://doc/mvvm/ViewModelScript.md) - [VMCustom.md](file://doc/mvvm/VMCustom.md)

概述

本多语言支持系统基于Cocos Creator游戏引擎开发，采用模块化架构设计，支持动态语言切换和实时文本更新。系统通过JSON语言包文件、配置管理系统和MVVM框架的深度集成，实现了高效的语言资源管理和用户体验优化。

核心特性

动态语言切换：支持运行时无缝切换语言类型
JSON结构化存储：标准化的语言键值对管理
MVVM数据绑定：自动化的UI文本更新机制
性能优化：智能缓存和预加载策略
扩展性强：易于添加新语言类型

项目结构

多语言系统的核心文件组织结构如下：

graph TB
subgraph "资源配置"
Config[config.json]
LangConfig[语言配置]
end
subgraph "语言包文件"
EnJSON[en.json<br/>英文语言包]
ZhJSON[zh.json<br/>中文语言包]
end
subgraph "初始化模块"
Init[Initialize.ts<br/>游戏初始化]
LoadView[LoadingViewComp.ts<br/>加载界面]
end
subgraph "UI组件"
HInfo[HInfoComp.ts<br/>英雄信息组件]
SIcon[SIconComp.ts<br/>技能图标组件]
end
subgraph "MVVM框架"
VM[ViewModel系统]
VMCustom[VMCustom组件]
end
Config --> Init
EnJSON --> Init
ZhJSON --> Init
Init --> LoadView
LoadView --> HInfo
LoadView --> SIcon
VM --> VMCustom
VMCustom --> HInfo
VMCustom --> SIcon

图表来源

章节来源

JSON结构设计原则

键值命名规范

语言包采用层次化命名结构，确保键值的可读性和维护性：

命名规则	示例	说明
功能模块前缀	`common_prompt_ok`	明确功能归属
功能类型标识	`btn_`	按钮类文本
功能用途标识	`loading_`	加载相关文本
文本内容描述	`_title_sys`	具体用途说明

结构层次设计

graph LR
subgraph "语言包结构"
Root[根对象]
Common[通用提示<br/>common_prompt_*]
Button[按钮文本<br/>btn_*]
Loading[加载文本<br/>loading_*]
Role[角色属性<br/>role_*]
end
Root --> Common
Root --> Button
Root --> Loading
Root --> Role

图表来源

文本键值示例

键名	英文值	中文值	用途说明
`common_prompt_ok`	ok	确定	确认按钮文本
`btn_demo_lang`	English	中文	语言切换按钮
`loading_load_json`	Load Json	加载游戏本地数据	加载进度提示
`role_name`	Name	名字	角色属性显示

章节来源

配置系统

配置文件结构

系统配置通过config.json文件管理，包含语言相关的完整配置：

graph TB
subgraph "配置结构"
Config[config对象]
Language[language对象]
subgraph "语言配置"
Type[type数组<br/>支持的语言类型]
Path[path对象<br/>资源路径配置]
end
subgraph "路径配置"
JsonPath[json: language/json<br/>JSON文件路径]
TexturePath[texture: language/texture<br/>纹理资源路径]
end
end
Config --> Language
Language --> Type
Language --> Path
Path --> JsonPath
Path --> TexturePath

图表来源

config.json

配置参数说明

参数名	类型	默认值	说明
`type`	Array	`["zh", "en"]`	支持的语言类型列表
`json`	String	`"language/json"`	JSON语言包存放路径
`texture`	String	`"language/texture"`	图形资源存放路径

章节来源

config.json

语言包加载机制

初始化加载流程

系统在游戏启动时自动加载语言包，采用异步队列管理模式：

sequenceDiagram
participant Game as 游戏启动
participant Init as Initialize
participant Storage as 存储系统
participant Language as 语言模块
participant Resource as 资源加载器
Game->>Init : 启动初始化
Init->>Storage : 获取语言设置
Storage-->>Init : 返回语言类型
Init->>Language : setLanguage(语言类型)
Language->>Resource : 加载语言包JSON
Resource-->>Language : JSON数据
Language->>Resource : 加载字体资源
Resource-->>Language : 字体数据
Language-->>Init : 加载完成
Init->>Game : 继续启动流程

图表来源

Initialize.ts

资源路径解析

系统通过配置文件解析语言资源路径：

flowchart TD
Start([开始加载]) --> GetLang[获取当前语言类型]
GetLang --> CheckDefault{语言设置为空?}
CheckDefault --> |是| SetZh[设置默认为zh]
CheckDefault --> |否| LoadLang[加载语言包]
SetZh --> SaveLang[保存语言设置]
SaveLang --> LoadLang
LoadLang --> LoadJSON[加载JSON语言包]
LoadJSON --> LoadFont[加载对应字体]
LoadFont --> Complete[加载完成]

图表来源

Initialize.ts

章节来源

Initialize.ts

运行时语言切换

切换机制实现

系统支持运行时动态切换语言，通过存储系统持久化用户偏好：

sequenceDiagram
participant User as 用户操作
participant UI as UI界面
participant Storage as 存储系统
participant Language as 语言模块
participant VM as MVVM框架
User->>UI : 选择语言
UI->>Storage : 保存语言设置
Storage->>Language : setLanguage(新语言)
Language->>Language : 加载新语言包
Language->>VM : 触发UI更新
VM->>UI : 更新所有绑定文本
UI-->>User : 显示新语言界面

图表来源

Initialize.ts

语言切换流程

步骤	操作	说明
1	获取当前设置	从存储中读取用户语言偏好
2	验证语言类型	确保语言类型在支持列表中
3	加载语言包	异步加载对应JSON文件
4	更新字体资源	加载对应语言的字体文件
5	触发UI更新	通过MVVM框架更新所有文本

章节来源

Initialize.ts

MVVM框架集成

ViewModel绑定机制

系统通过MVVM框架实现数据与视图的自动绑定：

classDiagram
class VMCustom {
+string watchPath
+string componentName
+string componentProperty
+boolean controller
+onValueChanged(newValue, oldValue)
+onValueInit()
}
class VMBase {
+string[] watchPathArr
+boolean templateMode
+any templateValueArr
+ViewModel VM
+onLoad()
+onEnable()
+onDisable()
}
class HInfoComp {
+Label name_node
+Label type_node
+Label ap_node
+Label hp_node
+update_data(uuid)
+load_all_hero(uuid)
}
VMCustom --|> VMBase
HInfoComp --> VMCustom : 使用

图表来源

文本绑定示例

绑定类型	watchPath	组件属性	用途
单一文本	`loading_load_json`	`Label.string`	加载提示文本
按钮文本	`btn_demo_lang`	`Label.string`	语言切换按钮
属性显示	`role_name`	`Label.string`	角色属性名称

章节来源

UI组件国际化

HInfoComp国际化实现

英雄信息组件展示了完整的国际化集成：

flowchart TD
Start([组件启动]) --> LoadData[加载英雄数据]
LoadData --> BindText[绑定国际化文本]
BindText --> UpdateUI[更新UI显示]
subgraph "文本绑定过程"
GetName[获取英雄名称]
GetType[获取英雄类型]
GetAttr[获取属性数据]
UpdateLabels[更新标签文本]
end
LoadData --> GetName
GetName --> GetType
GetType --> GetAttr
GetAttr --> UpdateLabels
UpdateLabels --> UpdateUI

图表来源

HInfoComp.ts

SIconComp国际化应用

技能图标组件展示了资源绑定的国际化：

组件功能	国际化处理	实现方式
图标显示	技能图标路径	动态加载技能资源
数据绑定	技能属性文本	ViewModel自动更新
资源管理	多语言资源	按语言类型加载

章节来源

性能优化策略

预加载策略

系统采用多层次的预加载机制：

graph TB
subgraph "预加载层级"
Level1[一级预加载<br/>核心语言包]
Level2[二级预加载<br/>常用字体资源]
Level3[三级预加载<br/>备用语言包]
end
subgraph "加载时机"
Startup[游戏启动时]
Background[后台预加载]
OnDemand[按需加载]
end
Startup --> Level1
Background --> Level2
OnDemand --> Level3

内存缓存策略

缓存级别	缓存内容	生命周期	清理策略
L1缓存	当前语言包	游戏会话期间	会话结束清理
L2缓存	字体资源	应用生命周期	应用退出清理
L3缓存	已加载语言包	永久存储	手动清理

性能监控指标

加载时间：< 200ms
内存占用：单语言包 < 5MB
切换延迟：< 50ms
缓存命中率：> 90%

扩展指南

新增语言类型

添加新语言支持的完整流程：

flowchart TD
AddLang[添加语言类型] --> CreateJSON[创建语言包文件]
CreateJSON --> UpdateConfig[更新配置文件]
UpdateConfig --> AddFonts[添加字体资源]
AddFonts --> TestLang[测试语言切换]
TestLang --> Validate[验证完整性]
subgraph "验证步骤"
CheckKeys[检查键值完整性]
CheckFormat[验证JSON格式]
CheckDisplay[测试显示效果]
end
Validate --> CheckKeys
CheckKeys --> CheckFormat
CheckFormat --> CheckDisplay

翻译一致性维护

维护要点	实施方法	工具支持
键值一致性	版本控制	Git分支管理
文本长度适配	设计评审	UI适配测试
上下文一致性	翻译记忆库	专业翻译工具
格式化字符串	占位符验证	自动化测试

占位符处理

系统支持复杂格式化字符串的国际化：

// 示例：带参数的国际化文本
oops.language.getLangByID("loading_progress", {
    current: 5,
    total: 10,
    percentage: "50%"
});

故障排除

常见问题诊断

问题类型	症状	可能原因	解决方案
语言包加载失败	显示英文或空白	文件路径错误	检查配置文件路径
字体显示异常	文本乱码	字体资源缺失	确认字体文件存在
UI更新延迟	文本未及时更新	MVVM绑定失效	重启绑定机制
内存泄漏	性能逐渐下降	缓存未清理	手动清理缓存

调试工具

graph LR
subgraph "调试工具集"
Logger[日志记录器]
Profiler[性能分析器]
Validator[配置验证器]
Monitor[运行时监控]
end
subgraph "监控指标"
LoadTime[加载时间]
MemUsage[内存使用]
CacheHit[缓存命中率]
ErrorRate[错误率]
end
Logger --> LoadTime
Profiler --> MemUsage
Validator --> CacheHit
Monitor --> ErrorRate

章节来源

Initialize.ts

总结

本多语言支持系统通过模块化设计、MVVM框架集成和性能优化策略，实现了高效、可扩展的国际化解决方案。系统具备以下优势：

核心优势

架构清晰：模块化设计便于维护和扩展
性能优异：智能缓存和预加载机制
用户体验：无缝的语言切换体验
开发友好：简洁的API和完善的文档

最佳实践

遵循命名规范，确保键值的可读性
合理规划语言包结构，避免过度嵌套
定期验证翻译质量，确保用户体验
监控性能指标，持续优化系统表现

未来发展方向

支持更多语言类型
增强动态内容的国际化能力
优化移动端的性能表现
提供更丰富的本地化功能

通过本系统的实施，开发者可以轻松实现高质量的多语言游戏体验，满足全球用户的使用需求。

14 KiB Raw Blame History Unescape Escape

多语言支持系统文档

目录

概述

核心特性

项目结构

JSON结构设计原则

键值命名规范

结构层次设计

文本键值示例

配置系统

配置文件结构

配置参数说明

语言包加载机制

初始化加载流程

资源路径解析

运行时语言切换

切换机制实现

语言切换流程

MVVM框架集成

ViewModel绑定机制

文本绑定示例

UI组件国际化

HInfoComp国际化实现

SIconComp国际化应用

性能优化策略

预加载策略

内存缓存策略

性能监控指标

扩展指南

新增语言类型

翻译一致性维护

占位符处理

故障排除

常见问题诊断

调试工具

总结

核心优势

最佳实践

未来发展方向

14 KiB

Raw Blame History