exceltools

KO | EN

gitlite — search

#javascript #python #ai #typescript #llm #deep-learning #docker #macos #cli #awesome-list #security #mcp #openai #open-source

(★ 8)

convert excel to lua、xml、json with python

exceltools Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# exceltools

基于[openpyxl](https://pypi.python.org/pypi/openpyxl) 的 excel 转换工具。把 xlsx 转换成 lua / json / xml 文本配置，或 **stream 二进制配置**，并可同时生成 C++ / C# / TypeScript / Lua 多种语言的**结构描述文件**用于代码提示和配置读取。

仅支持`Python 3`和`xlsx`，不支持`Python 2`和`xls`。

## 使用

### linux 安装

```bash
apt install python3-pip
pip install openpyxl hjson
git clone https://github.com/changnet/py_exceltools.git
```

### win 安装

安装 python（同时安装 pip 并添加到 Path）：https://www.python.org/downloads/windows/

```bat
pip install openpyxl hjson
git clone https://github.com/changnet/py_exceltools.git
```

### 部署exe

部署时可以把 python 打包成 exe，在不安装python的机器上也能使用。**必须用 spec 文件打包**，否则会漏掉 `write_desc/` 与 `writers/` 下的模块（它们用扁平 import，PyInstaller 的静态分析扫不到）：

```bash
pip install pyinstaller
pyinstaller --noconfirm --distpath bin/win_x64 exceltools.spec
```

`deploy.bat` 会连同 QExcelTool（Qt GUI 前端）一起构建打包。

### 参数

```
--input        需要转换的 excel 文件所在目录
--suffix       excel 文件后缀，默认 .xlsx
--timeout      只转换最后修改时间在 N 秒内的 excel。-1 表示转换全部（全量导出）
--structpath   struct.json 路径，记录表结构与自定义类型。默认 ./struct.json
--customformat 配置复杂类型时的格式，hjson 或 lua
--supportint64 是否启用 int64 类型支持：1 启用（默认），0 时 int64 按 double 处理，

--sout <format> <data_dir> [desc_path]    服务端输出参数
--cout <format> <data_dir> [desc_path]    客户端输出参数
```

`format` 可选 `stream` / `lua` / `json` / `xml`。

`desc_path` 可选，按扩展名决定生成哪种语言的描述文件：

| 扩展名      | 语言       |
| ----------- | ---------- |
| `.h` `.hpp` | C++17      |
| `.cs`       | C#         |
| `.ts`       | TypeScript |
| `.lua`      | Lua 5.3+   |

`supportint64`用于复杂类型自动推导数据类型用。不支持int64的语言（比如js）在推导`{id = 1, count = 999999999}`时推导为`double`而不是`int64`

## 示例

```bash
python PyExcelTool/exceltools.py --input ./excels/ \
    --structpath ./struct.json --customformat hjson --supportint64 1 --timeout -1 \
    --sout stream ./stream  ./cpp/conf_d.h \
    --sout stream ./stream   ./cs/conf_d.cs \
    --cout stream ./stream   ./ts/conf_d.ts \
    --cout stream ./stream  ./lua/conf_d.lua \
    --cout json   ./json
```

服务端只导出 side 含 `s` 的字段，客户端只导出 side 含 `c` 的字段，两边的数据、描述文件、二进制内容各自独立。

在`example`中，有导出的数据示例及用法可参考

## 数据类型

由于要支持强类型语言的代码提示，每个字段必须显式指定数据类型，目前支持的数据类型如下

| 类型            | 说明                                            |
| --------------- | ----------------------------------------------- |
| `int`           | 32 位有符号整数                                 |
| `int64`         | 64 位有符号整数（`--supportint64 0` 时退化）    |
| `double`        | 双精度浮点                                      |
| `str`           | UTF-8 字符串                                    |
| `array<T>`      | 数组，T 可继续嵌套                              |
| `map<K, V>`     | 字典，K 只能是 `int` / `int64` / `str`          |
| 自定义类型      | 在 struct.json 中定义的结构体，如 `Reward`      |

### 容器类型

容器是指**数组**和**字典**，采用类似C++的写法

| 写法 | 含义 |
| --- | --- |
| `array<T>` | 数组，元素类型 `T`（可为基本/容器/自定义类型） |
| `map<K, V>` | 字典，`K` ∈ `int` / `int64` / `str`，`V` 可为基本/容器/自定义类型 |

容器中可以嵌套其他类型，例如：`array<map<int,str>>`和`map<int, Reward>`都是合法的

### 自定义类型

在配置中，可以像代码一样定义自己的类型，例如
```cpp
struct Reward {
  int id; // 配置id
  int num; // 数量
};
```
则在excel中可以直接配置为类型`Reward`，它里面的数值可配置成`{id = 1, num = 2}`

自定义类型有两种来源：

- **manual（手动定义）**：在 `struct.json` 的 `structs` 段自己定义结构及字段然后标识 `source: "manual"`即可
- **auto（自动推导）**：如果在 `struct.json` 中找不到已有的类型定义，则将会读取这个字段的数据，提取里面的字段名，生成这个结构的定义并写入到 `struct.json` 中。

注意：自动推导的结构，在导出部分文件时仅会添加新字段，不会删除结构定义或者删除字段。如果是全部导出则会根据所有配置文件重新推导这个结构，里面的字段可能会被删减。这在**热更**的时候要非常注意，强类型语言可能会导致结构体的内存布局发生变化。

### 空值

所有字段都必须指定类型，但数值可以为空。当为空时，如果导出的是`lua`、`json`这种宽松结构，则该字段将不会被导出。如果是导出`stream`这种强类型的结构，则会被填充默认值。数字默认值为`0`，字符串为`""`，容器的数量为0，自定义结构则里面的子字段全为默认值。

### 字段可见端 side

每个字段可标注 `side` 控制导出端：

- `s`：仅服务端
- `c`：仅客户端
- `sc`：两端都导

### 容器/自定义类型语法（--customformat）

需要在excel的一个单元格写复杂的数据时（例如：`{id=1, num=2}`），需要通过 `--customformat` 参数指定语法格式，它当前支持两种格式

- `hjson`（默认）：宽松 JSON，支持注释、无引号 key、尾逗号。
- `lua`：Lua 表语法。

关于[hjson](https://hjson.github.io/)格式，它是一种兼容json但写法更简单的格式。

### stream 二进制格式

`.stream` 文件格式是一种自定义的二进制流格式：

```
[magic "EXCF"][version int32=1][index_count int32]
[index_field_count int32]([name][TypeDesc])*
[body_field_count  int32]([name][TypeDesc])*
[sentinel int32 = 0]
[data ...]
```

它是为了解决json文件类型体积大，解析慢，不适合转换为强类型语言结构体的问题。读取这种格式的方法见`example`示例

## 测试

配置好各个语言的运行环境后，可直接运行`example`目录下的`test.bat`来运行测试，如果需要单独执行某些测试，则可参考下面的脚本

```bash
python test_stream.py              # Python 独立实现解析 .stream，并与 json 导出对拍
cd lua && lua test.lua             # Lua 客户端读取校验
cd ts  && tsc -p tsconfig.json && node out/test.js   # TypeScript 客户端校验（strict）
cd cs  && dotnet run               # C# 服务端校验
cd cpp && build_test.bat           # C++ 服务端校验（MSVC，路径需按机器调整）
```

## 设计理念

* 设计表结构时，数据尽量扁平化。例如一个玩家身上有 8 种装备，不应该配 8 个表，
  而是在装备表中加一个字段 pos。

* 可以用`hjson`或者`lua`把一个复杂的结构塞进一个excel格子里，但建议适当拆分复杂结构。如果一定要配置复杂结构，可以在另一张不导出的表配置数值，再用公式拼到导出的数值表。

* 自定义结构是为了让导出的结构与程序代码中的结构保持一致，但应该尽量少使用自定义结构，否则配表复杂度就会上升。多级索引和容器类型应该已经能满足大部分需求。

## 二次开发

每个项目的需求都不一样，默认导出的配置可能不满足需求。本项目为扩展预留了一些接口

* 新增**语言**或者**数据格式**
参考 `PyExcelTool/write_desc/base.py`或者`PyExcelTool/writers/` 实现新的类即可，完全不需要动已有的代码

* 导出数据的二次处理
`QExcelTool`被设计成只调用脚本去导出配置，而调用的脚本是可以自己修改的。例如有的项目在导出后需要调用翻译资料来替换字符串，有的需要在导出后压缩配置，都可以在调用的脚本中去处理

exceltools

exceltools Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

exceltools

exceltools Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README