ExcelAndJSON
by 老G （qq 233424570）
Part0.缘起
Excel，是游戏开发中，策划最常用的数值编辑工具。它有着公式填充，数值曲线图等许多好用功能。作为Office办公套件的一部分，它的上手度，易用性也非常不错。
JSON，是手机游戏开发中，最常用的数据交换格式。它的树形结构，让数据访问变得非常自然。并且，这种结构和脚本语言有着天然的兼容性（例如Python，JavaScript）。
基于上面的原因，在手机游戏开发过程中，很多公司都使用Excel编辑数值，然后导出JSON，最后加载到程序中。大家也都开发了许多通过Excel导出为JSON的工具。
但因为Excel是基于二维表的结构，最后导出为JSON时，JSON也是一个类似二维表的结构，这严重限制了JSON作为一种树形结构的数据交换格式的表现力和易用性。造成的结果就是，大家在开发中，不断的建表，因为二维表表现方式有限，所以只能通过当前数据获得一个主键，然后在另外的表上查找，甚至还可能出现在多个表间跳转等情况。很吃力。
除此之外，很多工具都存在着功能单一、流程复杂、配置不方便、设计不合理等问题。
为了解决上述问题，我尝试开发了这个工具。市面上大部分工具都起名为：ExcelToJSON。而我的想法是，结合Excel和JSON的优点，所以我的工具起名为：ExcelAndJSON。
Part1.运行环境
-
支持xlsx格式的Office
-
Python 2.7
-
xlrd
Part2.特点
易用
-
快速的上手速度
-
配置简单，所见即所得
输出可定制
-
支持各种输出格式的定制方式：数组与字典、折叠、引用、可选字段的输出
数据完整性
-
单元格中的数据都会输出，不会允许跳过空数据，保证JSON结构的同一化
-
所有的属性值，如果不填写，缺省值都是null，防止bool判断出错
-
支持的字段类型较多，建议明确书写字段类型参数。如果当前单元格的数据没有填写对应的字段类型，程序会自动判断。
格式自携带
-
数据与数据格式存储在同一张sheet上（主表模式除外），便于同步
Part3.初级功能
初级功能适用于简单的单机游戏，休闲益智类游戏，等没有太多复杂数值要处理的游戏类型。它的上手速度较快，而且也提供了足够的支持。
单表模式
顾名思义，单表模式就是只有一个workbook文件的模式。该模式下，我们只使用一个.xlsx文件。所有的sheet都在这个文件上。
单表模式的命令，举例如下：
python excel_and_json.py singlebook -o ./ -i single.xlsx命令说明：
-
singlebook：开启单表模式
-
-o：输出目录
-
-i：输入的.xlsx
表头
表头决定了sheet的各种格式和内容信息
| __default__ | |||||
|---|---|---|---|---|---|
| __folding__ | |||||
| __type__ | s | i | i | i | i |
| __name__ | name | hp | mp | atk | def |
表头最左侧是一些约定标记，这些标记表示了该行是什么参数类型：
-
__type__：必选标记，表示该行是字段类型 -
__name__：必选标记，表示该行是字段名 -
__default__：可选标记，表示该行是缺省值 -
__folding__：可选标记，表示该行是折叠属性，在高级功能中详述
字段类型
字段类型是必选标记。ExcelAndJSON支持如下的字段类型：
-
s：字符串
-
i：整数
-
f：小数
-
b：布尔
-
as：字符串数组
-
ai：整数数组
-
af：小数数组
-
d：字典，若在字典中想使用数字字符串作为值，请在数字两端加""
-
r：引用，可以引用另一张sheet中的内容，在高级功能中详述
缺省值
缺省值是可选标记。如果该单元格是空白，程序会自动在该单元格上填写缺省值。
-
为了保证布尔判断的正确性，以及表格结构的完整性，所有默认的缺省值都是null
-
可以自定义缺省值，但与单元格一样，需要保证数据类型的正确性
数据区
在表头下面的，就是数据区。数据区的大小是程序自行判断的，为了保证程序正确判断数据区的单元格位置，请在数据区下面一行和最右侧一列，保持空白。在数据区之外的单元格，程序不会读取，可自由编辑。
null
null为保留字，在单元格中可以直接填写null为占位符。程序最终会输出null到JSON结构中。
字段类型自动判断
如果当前单元格的数据没有填写对应的字段类型，程序将自动判断。只支持几种类型的自动判断：i，f，s。
Part4.高级功能
高级功能适用于比较复杂的大中型游戏，有大量数值要处理。它有一定的学习成本，但相应的提供了更强大的功能。
引用
引用是一个字段类型，其类型值为r。引用允许在一张sheet中，插入另一张sheet中的一行。
| __type__ | r |
|---|---|
| __name__ | lv1award |
| zhangsan | lvAward.lv1 |
在引用属性的单元格中，填写的是lvAward.lv1。该格式为约定格式“表名.记录名”。程序会在名为“lvAward”的sheet中，查找到名为“lv1”的记录，并把该记录，作为属性值插入到当前sheet中。
注意，不允许各个sheet之间循环引用。在单表模式下，被引用的表也不会输出。
折叠
折叠是一个可选字段属性。该功能允许把一张sheet中的字段，反复折叠，变成一个JSON，该JSON会填充到最后一次折叠对应的单元格中。
按JSON格式的特点，我们有两种折叠方式：
-
按{}折叠：折叠后，会生成一个字典
-
按[]折叠：折叠后，会生成一个数组
每一次折叠，不只会折叠数据。对应的字段类型，字段名，甚至折叠属性本身都会被折叠。我们约定，在折叠字段属性填写时，左侧括号后，必须紧接一个折叠后的字段名。折叠后的字段类型为d。
折叠本身的含义可能过于抽象，但其实质是非常简单的。下面演示了折叠的整个过程：
原始表
| __folding__ | {a{b | } | {c | }} | ||
|---|---|---|---|---|---|---|
| __type__ | s | i | i | i | s | b |
| __name__ | name | hp | atk | def | description | leader |
第一次折叠
| __folding__ | {a | {c | }} | |
|---|---|---|---|---|
| __type__ | d | i | s | b |
| __name__ | b | def | description | leader |
第二次折叠
| __folding__ | {a | } | |
|---|---|---|---|
| __type__ | d | i | d |
| __name__ | b | def | c |
第三次折叠
| __folding__ | |
|---|---|
| __type__ | d |
| __name__ | a |
折叠后的JSON结构形如：
"a":{ "b":{ "name":"x x x", "hp":111, "atk":222 }, "def":333, "c":{ "description":"x x x", "leader":false } }引用与折叠的关系
特别注意，程序在进行数据输出时。先对每个sheet进行单独处理，此时会触发折叠操作。然后如果该sheet存在引用，再插入相应的数据。所以，引用插入的数据是不可以被折叠的。
主表模式
顾名思义，主表模式是存在一个独立的主要workbook文件，该.xlsx内部存储了一些用于输出的配置信息。一个主表workbook可以读取和加载大量的数据workbook。并按照相应的定制信息，进行sheet的输出。
主表模式的命令，举例如下：
python excel_and_json.py mainbook -o ./ -i main.xlsx命令说明：
-
mainbook：开启主表模式
-
-o：输出目录
-
-i：输入的.xlsx
输入的workbook
使用__workbook__进行标记，在后面紧接要使用的workbook名。
| __workbook__ | workbook1 | workbook2 |
|---|
输出的sheet
在__workbook__标记下面，每一行都是一个要输出sheet。每行开头为该sheet的名字。
| sheet1 | aaa | skill1 | skill2 | skill3 | option | lv1 | lv2 |
|---|---|---|---|---|---|---|---|
| sheet2 | name | atk | def | hp | |||
| sheet3 | lv1 | lv2 | lv3 | ||||
| sheet4 | |||||||
| sheet4->sheet5 |
-
选择输出的字段：如果需要字段的选择性输出，可以在sheet名后面接要输出的字段名。如果不写，则该sheet的所有字段都会被输出。
-
表改名：支持在输出时修改表的名字，方便把一个表拆成多个。表的旧名和新名之间，用->连接。
GitHub源代码仓库地址：
https://github.com/gdgoldlion/ExcelAndJSON
