xresloader文档

xresloader 是一组用于把Excel数据结构化并导出为程序可读的数据文件的导表工具集。它包含了一系列跨平台的工具、协议描述和数据读取代码。

主要功能特点：

• 跨平台（java 11 or upper）

• Excel => protobuf/msgpack/lua/javascript/json/xml

• 完整支持协议结构，包括嵌套结构和数组嵌套

• 同时支持protobuf proto v2 和 proto v3

• 支持导出proto枚举值到lua/javascript代码和json/xml数据

• 支持导出proto描述信息值到lua/javascript代码和json/xml数据（支持自定义插件，方便用户根据proto描述自定义反射功能）

• 支持导出 UnrealEngine 支持的json或csv格式，支持自动生成和导出 UnrealEngine 的 DataTable 加载代码

• 支持别名表，用于给数据内容使用一个易读的名字

• 支持验证器，可以在数据里直接填写proto字段名或枚举名，或者验证填入数据的是否有效

• 支持通过protobuf协议插件控制部分输出

• 支持自动合表，把多个Excel数据表合并成一个输出文件

• 支持公式

• 支持oneof,支持plain模式输入字符串转为数组或复杂结构,支持map

• 支持空数据压缩（裁剪）或保留定长数组

• 支持基于正则表达式分词的字段名映射转换规则

• 支持设置数据版本号

• Lua输出支持全局导出或导出为 require 模块或导出为 module 模块。

• Javascript输出支持全局导出或导出为 nodejs 模块或导出为 AMD 模块。

• 提供CLI批量转换工具（支持python 2.7/python 3 @ Windows、macOS、Linux）

• 提供GUI批量转换工具（支持Windows、macOS、Linux）

• CLI/GUI批量转换工具支持include来实现配置复用

构建环境	构建状态
xresloader	Linux (OpenJDK 11):
xresconv-cli	直接下载发布包即可，无需构建打包
xresconv-gui
xres-code-generator	读表代码生成工具，直接下载即可，无需构建打包
xresloader-dump-bin	导出二进制转文本工具。
文档

v2.11.0-rc2及以前版本更新迁移指引

由于 v2.11.0-rc3 版本变更了默认的索引器，导致对Excel一些内置的数据类型处理和先前有一些差异。比如对于日期时间类型、百分率等。 现在会先转出原始的文本，再根据protocol的目标类型做转换。如果需要回退到老的POI索引，可以使用 --enable-excel-formular 选项切换到老的索引器。

新版本开始使用JDK 11打包，如果仍然需要 JDK1.8打包请自行下载源码并修改 pom.xml 内 maven-compiler-plugin 的 source 和 target 后使用 mvn package 命令打包。

xresloader 主要文档分为以下几个模块:

• 用户文档

• 开发文档

• 其他

用户文档

• 下载工具集
• 快速上手
  • Step-1: 下载转表工具
  • Step-2: 配置结构化的protobuf协议并使用protoc
  • Step-3: 配置Excel数据源
  • Step-4: 配置批量转表配置文件
  • Step-5: 运行转表工具
    • Step-5.1: 命令行批量转表工具
    • Step-5.2: GUI批量转表工具
  • Step-6: 加载数据
    • Step-6.1: （推荐）使用 xres-code-generator 生成解析代码(C++/Lua/C#/Upb Lua//UE蓝图)
    • Step-6.2: 手动解析
    • Step-6.3: （老式接口，不推荐，请考虑使用上面6.1的加载方法）使用读取库模板解析
  • 使用proto v2加载二进制数据的特别注意事项
• 转表引擎-xresloader
  • xresloader-可用参数列表
  • 批处理
  • 直接使用xresloader
• 协议->Excel数据映射和支持的配置读取源 （scheme）
  • 配置项的结构
  • 数据映射-Scheme
    • 数据源
    • 类型嵌套和Message嵌套
    • 数组和下标
  • 可用的配置项
    • 关于设置编码
    • 关于使用 CallbackScript 处理数据
  • 从哪里读取字段映射信息？
    • 直接写在批量转表文件里（推荐）
    • 直接写在Excel里: 文件后缀.xls,.xlsx
    • 直接写在json文件里: 文件后缀.json
    • 直接写在ini文件里: 文件后缀.ini,.conf,.cfg
  • 完整的样例
• 数据输出和数据加载
  • 输出类型
    • 导出为协议二进制数据 (推荐)
    • 导出为json、xml、lua代码等文本数据 (可选)
    • 导出为Msgpack打包的二进制数据 (可选)
    • 导出为UE支持的CSV或JSON数据和代码 (可选)
    • 导出枚举类型成代码 (可选)
    • 导出协议描述成代码 (可选)
  • Proto v2和Proto v3
  • 数据加载
    • 方式-1(推荐): （推荐）使用 xres-code-generator 生成解析代码(C++/Lua/C#/Upb Lua/UE蓝图)
    • 方式-2(可选): 使用C++加载二进制数据
    • 方式-3(可选): 使用lua-pbc加载二进制数据
    • 方式-4(可选): 使用C#和DynamicMessage-net加载二进制数据
    • 方式-5(可选): 加载msgpack文本数据
    • 方式-6(可选): 使用node.js加载javascript文本数据
    • 方式-7(可选): 使用lua加载导出的枚举类型
• 批量转表工具
  • 批量转表 - GUI和CLI工具示例
  • 批量转表 - 配置示例
  • 批量转表 - 配置结构规范
  • CLI批量转表工具 - 启动参数
  • GUI批量转表工具 - 启动参数
  • GUI批量转表工具 - 特殊事件
    • GUI事件 - 显示转表项名称 //root/gui/set_name
    • GUI事件 - 转表前事件和转表成功后事件 //root/gui/on_before_convert 和 //root/gui/on_after_convert
  • GUI批量转表工具 - 自定义按钮
    • GUI自定义按钮 - 基本配置
    • GUI自定义按钮 - 自定义脚本（点击回调）
    • GUI自定义按钮 - 按钮样式
• 数据类型说明
  • 数组、repeated和数据结构
  • 定长数组
  • 无符号整数
  • 日期和时间类型
• 使用 xres-code-generator 生成解析代码
  • 第一步，在proto文件中声明加载器和索引类型
  • 生成C++加载代码
    • UE(UnrealEngine)蓝图(Blueprint)支持
  • 生成Lua加载代码
  • 生成C#加载代码
  • 生成基于 upb 的Lua加载代码
  • 自定义模板和更多语言
• 高级功能
  • 文本替换（别名/宏）
  • 多表数据合并
  • 数据验证器
  • Protobuf 插件支持
    • Protobuf插件 - Message插件
    • Protobuf插件 - Field插件
    • Protobuf插件 - EnumValue插件
    • Protobuf插件 - Oneof插件(2.8.0版本及以上)
  • 仅导出部分字段
  • 批量转表的include标签
  • 公式支持
  • 定长数组
  • Plain模式（需要 xresloader 2.7.0及以上）
  • Oneof/Union支持（需要 xresloader 2.8.0及以上）
  • Map类型支持（需要 xresloader 2.9.0及以上）
  • 使用 CallbackScript 处理数据（需要 xresloader 2.13.0及以上）
  • 多字段复制（需要 xresloader 2.14.0-rc1及以上）
  • 剔除Excel误操作带来的空数据行（需要 xresloader 2.14.0-rc2及以上）
  • 唯一性检测（需要 xresloader 2.14.0-rc2及以上）
  • 通过自定义验证器在复用验证器规则组合（需要 xresloader 2.14.0-rc3及以上）
• 生态和周边工具
  • 二进制转可读文本工具: xresloader-dump-bin
• FAQ
  • 哪里有完整的示例？
  • 为什么会读到很多空数据？
  • 为什么Excel里填的时间，但是转出来是一个负数？
  • Windows下控制台里执行执行会报文件编码错误？（java.nio.charset.UnsupportedCharsetException: cp65001）
  • C++加载代码编译时出现xresloader符号重定义（multiple definition of org::xresloader::pb::xresloader_XXX）
  • C++加载代码编译时出现xresloader版本检查错误
  • proto v2版本API解析repeated的整数或浮点数类型字段失败(Wire Type)
  • 为什么在proto里定义的是一个无符号(unsigned)类型(uint32、uint64等)，实际输出的UE代码是有符号(signed)的(int32/int64)？
  • 为什么 UE-Csv 和 UE-Json 输出的代码会多一个 Name 字段?
  • 要如何配置可以让Excel里的数据指向UE的类型或资源
  • 为什么UE的代码输出里对 oneof 的case输出使用 FString 的字段名而不使用 UEnum()
  • 提示 Can not reserve enough space for XXX objecct heap

开发文档

• 环境和依赖项
  • 转表工具- xresloader
  • 命令行批量转表工具- xresconv-cli
  • GUI批量转表工具- xresconv-gui
  • 代码生成工具- xres-code-generator
  • C#的动态Message支持- DynamicMessage-net
• 编译和打包
  • 更新依赖包
  • 其他仓库地址
    • 公有仓库地址
    • 私有仓库地址
    • 其他maven功能
• 使用国内的源
  • 国内的Maven源
  • 加速NPM包下载
    • 关闭npm的https
    • 设置npm的软件源
    • 代理
• 转表引擎设计模型
• 批量转表工具设计模型

其他

• LICENSE
  • LICENSE - 文档
  • LICENSE - xresloader
• 关于 xresloader