协议->Excel数据映射和支持的配置读取源 （scheme）

在 快速上手 章节里我们提供了一个基本的转表使用流程。整个流程图示如下：

../_images/xresconv_process.png

上一章节里我们展示了 转表引擎-xresloader 的最基础的使用方式。 在使用的时候，我们需要告诉 xresloader 怎么把Excel里的数据对引到协议的数据结构里。 本章节主要是针对 协议描述 的说明。

配置项的结构

所有的数据源和规则设置都是Key-Value的形式。并且Value有三个，分别是**主配置，次要配置，补充配置**。 这三个参数对于不同配置的含义是不同的，具体没想配置的含义请参照 data-mapping-available-options 章节。

数据映射-Scheme

我们通过一些列scheme的配置来告诉 xresloader 从Excel的哪些地方读取数据，又转化到协议的哪个数据结构和哪个字段中。

数据源

我们通过 DataSource 来读取我们从哪个文件、哪个表及第几行第几列开始读数据。 比如：

../_images/data_mapping_data_source.png

然后再通过 ProtoName 和 KeyRow 来把Excel数据映射到哪个协议数据结构里和映射哪些字段。

../_images/data_mapping_data_key_and_proto.png

类型嵌套和Message嵌套

对于复杂的数据类型，我们使用 父级字段名.子结构字段名 来标识映射关系。比如在 xresloader sample 中。

../_images/data_mapping_rec_message.png

以上划红线处为Excel KeyRow 配置和对应的协议结构。

数组和下标

对于数组类型（protobuf的repeated类型）。我们使用 字段名[0开始的下标] 来表示。如果是数组嵌套数组，那么则是 父级字段名[父结构下标].子结构字段名[子结构下标] 。

../_images/data_mapping_arr_in_arr.png

以上示例是 xresloader sample 中的 arr_in_arr 表。

可用的配置项

字段

简介

主配置

次配置

补充配置

说明
DataSource
配置数据源
文件路径
表名
数据起始行号,列号
(英文逗号分隔)
必须。
可多个。多个则表示把多个Excel表数
据合并再生成配置输出，这意味着这多
个Excel表的描述Key的顺序和个数必须
相同。
MacroSource
元数据数据源
文件路径
表名
数据起始行号,列号
(英文逗号分隔)
+ 可选

编程接口配置
ProtoName
协议描述名称
如: role_cfg






+ 必须
+ 协议类型名称
+ 也可以是 包名 . 协议名

OutputFile

输出文件

如: role_cfg.bin

  • 必须

KeyRow

字段名描述行

如: 2

  • 必须
KeyCase
字段名大小写
如: 小写






+ 字段名映射时的大小写转换
+ 可选值: 大写/小写/不变
+ 如果不需要则留空
KeyWordSplit
字段名分词字符









+ 可选
+ 字段名映射时单词之间填充的字符串
+ 如果不需要则留空
KeyPrefix
字段名固定前缀









+ 可选
+ 字段名映射时附加的前缀
+ 如果不需要则留空
KeySuffix
字段名固定后缀









+ 可选
+ 字段名映射时附加的后缀
+ 如果不需要则留空
KeyWordRegex
分词规则（正则表达式）



示例:
判断规则



[A-Z_$ trn]
移除分词符号规则



[_$ trn]
前缀过滤规则



[a-zA-Z_$]
+ 可选
+ 字段名映射时单词的分词规则
+ 正则表达式
+ 如果不需要则留空
Encoding
编码转换
UTF-8






注：Google的protobuf库的代码里写死
了UTF-8，故而该选项对Protobuf的二
进制输出无效
UeCfg-UProperty
UnrealEngine配置
支持的字段属性
字段分组
默认值: XResConfig
蓝图权限
默认值: XResConfig
编辑权限
默认值: EditAnywhere
+ 可选
UeCfg-CaseConvert
是否开启驼峰命名转换
（默认开启）
true/false






+ 可选
+ 开启后将使用首字母大写的
驼峰命名法生成字段名和类名
UeCfg-CodeOutput
设置UE代码输出目录
代码输出目录
Publich目录前缀
Private目录前缀
+ 可选
+ 生成的cpp文件的包含路径和
Publich目录前缀有关
UeCfg-DestinationPath
资源输出目录
资源输出目录






+ 可选
UeCfg-CsvObjectWrapper
指定 Ue-Csv 模式输
出时，map和array的包裹
字符
左包裹字符
右包裹字符



+ 可选
+ 版本>=2.9.3
UeCfg-EnableDefaultLoader
是否启用UE默认的Loader

输出的数据
true/false






+ 可选
+ 默认值: true
+ 版本>=2.13.1
UeCfg-IncludeHeader
UE代码额外的自定义包
输出的数据
头文件路径
头文件路径
头文件路径
+ 可选
+ 版本>=2.13.1
JsonCfg-LargeNumberAsString
JSON输出时大整数转字符串
true/false




+ 可选
+ 版本>=2.16.0
CallbackScript
使用Javascript脚本处理
输出的数据
Javascript脚本路径






+ 可选
+ 版本>=2.13.0

如果Excel里字段名使用上面示例里的规则，如果填的是 0UnlockLevel_num，则会忽略第一个0（不符合前缀过滤规则）,按分词规则分词为Unlock、Level和num， 同时移除下划线分词符号（移除分词符号规则）。 然后按上面的大小写规则和 字段名分词字符 组成新的字段名，最后应用大小写规则。 假设 字段名分词字符 是 _ 。 字段名大小写 是小写，则最后对应的协议的字段名是 unlock_level_num 。

字段名分词、大小写转换、等字段名转换的功能建议非必要不要使用。这里只是为了有些时候需要和其他工具搭配使用的时候的一些适配。

关于设置编码

由于protobuf里写死的UTF-8，所以编码设置不是对所有的功能都生效。如果输出的类型是代码文件或者文本文件，那么转表工具会尝试把文本内容转换成该编码。 对于二进制输出，这个选项是无效的。

关于使用 CallbackScript 处理数据

CallbackScript指向的脚本中，需要满足已下条件:

  • 可使用 gOurInstance 访问数据源接口（ DataSrcImpl.getOurInstance() ）

  • 可使用 gSchemeConf 访问数据转换配置接口（ SchemeConf.getInstance() ）

  • 提供 function initDataSource() 函数，将在切换数据源时触发（文件名或sheet名）。

  • 提供 function currentMessageCallback(originMsg, typeDesc) 函数，将在切换数据源时触发（文件名或sheet名）。

    • originMsg 为原始数据结构的 HashMap 结构

    • typeDesc 为数据类型描述信息, org.xresloader.core.data.dst.DataDstWriterNode.DataDstTypeDescriptor 结构

从哪里读取字段映射信息？

字段映射信息我们除了可以直接使用 转表引擎-xresloader 的 -m 选项指定外，还支持多种读取来源。 如果从文件中读取，我们是根据文件后缀来区分读取来源的。

直接写在批量转表文件里（推荐）

在使用批量转表功能的时候建议直接写在批量转表配置里，详见 批量转表工具

直接写在Excel里: 文件后缀.xls,.xlsx

当字段映射信息保存在Excel里时，scheme的名字就是表名（ -m 参数）。我们会先查找列明为 字段或header 、主配置或major 、次配置或minor 和 补充配置或addition 的字段，并依此列读取相应配置。如:

字段

简介

主配置

次配置

补充配置

说明

DataSource

配置数据源(文件路径,表名)

资源转换示例.xlsx

upgrade_10001

3,1

次配置为表名，补充配置为数据起始位置(行号, 列号)

DataSource

配置数据源(文件路径,表名)

upgrade_10002

3,1

次配置为表名，补充配置为数据起始位置(行号, 列号)

MacroSource

元数据数据源(文件路径,表名)

资源转换示例.xlsx

macro

2,1

次配置为表名，补充配置为数据起始位置(行号, 列号)

编程接口配置

ProtoName

协议描述名称

role_upgrade_cfg

OutputFile

输出文件

role_upgrade_cfg.bin

KeyRow

字段名描述行

2

KeyCase

字段名大小写

不变

大写/小写/不变

KeyWordSplit

字段名分词字符

KeyPrefix

字段名固定前缀

KeySuffix

字段名固定后缀

KeyWordRegex

分词规则

(判断规则,移除分词符号规则,前缀过滤规则)正则表达式

Encoding

编码转换

UTF-8

直接写在json文件里: 文件后缀.json

当字段映射信息保存在Excel里时，我们认为json的根节点包含一个数组，下面时key-value类型数据，key为scheme的名字（ -m 参数）。里面还是Key-Value类型或Key-List类型。对应着每项配置。如：

{
    "scheme_kind": {
        "DataSource": ["资源转换示例.xlsx", "kind", "3,1"],
        "MacroSource": ["资源转换示例.xlsx", "macro", "2,1"],

        "ProtoName": "role_cfg",
        "OutputFile": "role_cfg.bin",
        "KeyRow": 2,
        "KeyCase": "小写",
        "KeyWordSplit": "_",
        "KeyWordRegex": ["[A-Z_\\$ \\t\\r\\n]", "[_\\$ \\t\\r\\n]", "[a-zA-Z_\\$]"],
        "Encoding": "UTF-8"
    }
}

直接写在ini文件里: 文件后缀.ini,.conf,.cfg

当字段映射信息保存在Excel里时，scheme的名字（ -m 参数）是section的名字，里面的数据是:

  • Key名称.0 => Key名称的主配置

  • Key名称.1 => Key名称的次配置

  • Key名称.2 => Key名称的补充配置

比如:

[scheme_kind]
DataSource.0 = 资源转换示例.xlsx
DataSource.1 = kind
DataSource.2 = 3,1

MacroSource.0 = 资源转换示例.xlsx
MacroSource.1 = macro
MacroSource.2 = 2,1

ProtoName = role_cfg
OutputFile = role_cfg.bin
KeyRow = 2
KeyCase = 小写
KeyWordSplit = _
KeyWordRegex.0 = [A-Z_\$ \t\r\n]
KeyWordRegex.1 = [_\$ \t\r\n]
KeyWordRegex.2 = [a-zA-Z_\$]
Encoding = UTF-8

完整的样例

以上配置选项在 xresloader sample 中有完整的示例，并且在。 xresloader 的 README.md 中有举例说明。