ExcelAndJSON數據導出工具說明書

ExcelAndJSON

by 老G （qq 233424570）

Part0.緣起

Excel，是遊戲開發中，策劃最經常使用的數值編輯工具。它有着公式填充，數值曲線圖等許多好用功能。做爲Office辦公套件的一部分，它的上手度，易用性也很是不錯。

JSON，是手機遊戲開發中，最經常使用的數據交換格式。它的樹形結構，讓數據訪問變得很是天然。而且，這種結構和腳本語言有着自然的兼容性（例如Python，JavaScript）。

基於上面的緣由，在手機遊戲開發過程當中，不少公司都使用Excel編輯數值，而後導出JSON，最後加載到程序中。你們也都開發了許多經過Excel導出爲JSON的工具。

但由於Excel是基於二維表的結構，最後導出爲JSON時，JSON也是一個相似二維表的結構，這嚴重限制了JSON做爲一種樹形結構的數據交換格式的表現力和易用性。形成的結果就是，你們在開發中，不斷的建表，由於二維表表現方式有限，因此只能經過當前數據得到一個主鍵，而後在另外的表上查找，甚至還可能出如今多個表間跳轉等狀況。很吃力。

除此以外，不少工具都存在着功能單1、流程複雜、配置不方便、設計不合理等問題。

爲了解決上述問題，我嘗試開發了這個工具。市面上大部分工具都起名爲：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