管理器

介绍#

多语言管理器提供以下功能：

• 数据管理：添加和获取多语言文本/图片数据
• 语言切换：支持动态切换语言类型
• 事件监听：监听多语言事件，实现实时更新

概念#

多语言类型#

传统多语言表会随着时间推移变得庞大且难以清理。为了解决这个问题，MK 框架引入多语言类型，以支持任意粒度的数据管理。

示例

// 原本
{
    "多语言键": {
        "中文": "多语言数据",
        ...
    },
}

// 增加多语言类型
{
    "多语言类型": {
        "多语言键": {
            "中文": "多语言数据",
            ...
        },
    },
}

通过多语言类型，你可以将数据划分为多个模块，而且可以从工具层共用多语言数据，使用插件将数据转移到各个模块下

配置#

多语言系统的配置位于 GlobalConfig.Language 下。

多语言种类#

在 privateTypeTab 中定义支持的语言类型，例如：

/** 中文(中华人民共和国) */
zhCn: {
    // 文本方向：从左到右
    dire: Layout.HorizontalDirection.LEFT_TO_RIGHT,
    // 支持语种（sys.languageCode 的值）
    supportStrList: ["zh"],
},

上述代码定义了一个名为 zhCn 的语言类型，其文本方向为从左到右，支持的语种为 "zh"。

默认语种#

通过 defaultTypeStr 配置默认语言类型：

// 默认为中文
defaultTypeStr = types.zhCn;
// 根据地区动态匹配默认语言
defaultTypeStr = 'auto';

当 defaultTypeStr 为 auto 时，框架会匹配 privateTypeTab 中 supportStrList 和 sys.languageCode 相同的语种作为默认语言， 如果 sys.languageCode 为多级字符串例如 "zh-cn"，框架会先匹配 "zh-cn" 再匹配 "zh"

多语言参数前后缀#

通过 argsHeadStr 和 argsTailStr 配置参数占位符。

• 默认配置：argsHeadStr = '{'，argsTailStr = '}'
• 参数使用：在多语言文本中使用 {0} 表示第一个参数，{1} 表示第二个参数，依此类推。

例如，配置 template-{0}，当 argsStrList = ['123'] 时，结果为 template-123。

属性#

typeStr#

当前的多语言语种，对应于 GlobalConfig.Language.privateTypeTab 对象的键。切换语种时，修改此属性：

// 切换到英文（美国）
mk.languageManage.typeStr = GlobalConfig.Language.types.enUs;

data#

当前语种的配置数据，对应于 GlobalConfig.Language.privateTypeTab 对象中当前 typeStr 键的值。

labelDataTab#

文本数据表，类型为 Record<_MKLanguageManage.TypeType, Language_.TypeDataStruct>。

示例：

let globalLabelData = mk.languageManage.labelDataTab['多语言类型名'];

// 数据格式
{
    "测试": {
        "zhCn": "测试",
        "enUs": "Test"
    }
}

textureDataTab#

纹理数据表，结构与 labelDataTab 一致，但存储的是图片的 db 路径（以兼容编辑器和运行时加载）。

示例：

let globalLabelData = mk.languageManage.textureDataTab['多语言类型名'];

// 数据格式
{
    "测试": {
        "zhCn": "db://assets/resources/xxx.png",
        "enUs": "db://assets/resources/xxx_en.png"
    }
}

event#

管理器事件，支持以下操作：

• 监听事件：on(eventName, callback)
• 移除事件：off(eventName, callback)
• 触发事件：emit(eventName)

使用方式请参考事件系统文档。

方法#

addLabel#

动态添加多语言文本数据。

语法：

mk.languageManage.addLabel('多语言类型名', {
    示例: {
        enUs: 'template-{0}',
        zhCn: '示例-{0}',
    },
});

addTexture#

与 addLabel 类似，区别在于传递的数据是图片的 db 路径。

语法：

mk.languageManage.addTexture('多语言类型名', {
    示例: {
        zhCn: 'db://assets/resources/xxx.png',
        enUs: 'db://assets/resources/xxx_en.png',
    },
});

getLabel#

获取指定的多语言文本。

语法：

mk.languageManage.getLabel('多语言类型名', '示例', {
    language: GlobalConfig.Language.types.zhCn,
    argsStrList: ['123'],
});

参数：

返回值：对应的多语言文本（如 示例-123）。

getTexture#

获取指定的多语言图片。

语法：

mk.languageManage.getTexture('多语言类型名', '示例', null, GlobalConfig.Language.types.zhCn);

参数：

返回值：对应的 SpriteFrame 对象。

扩展功能#

多语言数据类#

在框架功能示例仓库中，可能会看到 mk.Language_.LabelData 和 mk.Language_.TextureData 的使用：

export default new mk.Language_.LabelData(cc.js.getClassName(XXX), {
    示例: {
        enUs: 'template-{0}',
        zhCn: '示例-{0}',
    },
});

在构造函数中，框架会自动执行 addLabel，但具有以下优势：

1. 类型安全#

如果配置 zhCn 和 enUs 两个语种，缺少配置时编辑器会提示：

2. 提供 key 供外部使用#

通过 key 属性，可以快速获取多语言标识：

const key = labelData.key.示例;

配置多语言数据#

框架设想是在只需要在单个配置表中配置所有文本和图片数据，然后通过插件更新每个 mk.Language_.LabelData 和 mk.Language_.TextureData 的构造数据。

但目前没有实现这个插件，因此可以采用以下方式：

1. 使用任意配置表工具：导出 JSON 或 Typescript 文件。
2. 动态加载：通过 addLabel 或 addTexture 添加数据作为全局使用，例如 addLabel("globalText", 多语言文本数据)，暂时不必分离为模块数据

常见问题（FAQ）#

Q：如何支持新的语言类型？

在 GlobalConfig.Language.privateTypeTab 中添加新的语言类型，并确保 defaultTypeStr 指向一个有效的语言类型。

Q：如何实现多语言参数的动态替换？

通过 argsStrList 参数传递参数数组，例如 argsStrList = ['123', '456']，则 {0} 替换为 123，{1} 替换为 456。

Q：如何监听语言切换事件？

通过 event 属性监听 switchLanguage 事件：

mk.languageManage.event.on(mk.languageManage.event.key.switchLanguage, () => {
    console.log('语言已切换');
});