json-table-view
v1.1.0
Published
json转化为表格的工具
Downloads
6
Readme
json-table-view
json-table-view是一个将常规的json数据转化为表格结构的工具。通过内建的builder模式，可以扩展支持HTML、Excel等多种输出格式，并同时支持浏览器端和node端。
可以通过在线的网站试一试。
最近更新
- 增加导出为xlsx的builder：src/json_to_excel.js
- 增加命令行工具：json-to-table
1. 安装
1.1. Node
1.2. 浏览器
2. 快速上手
3. 进阶
3.1. Meta
3.2. Builder
3.3. buildMeta
3.4. buildMetaFromData
4. 注意事项
5. 参与开发
6. Licence
1. 安装
1.1. Node
Node下通过npm安装
npm install json-table-view然后通过require命令引入相关函数
const { jsonToTableBuilder, jsonToHTMLTable } = require('json-table-view')1.2. 浏览器
通过script标签引入js文件
<script src="path/to/json-table-view/dist/bundle/json-table-view.bundle.js"></script>然后通过全局变量引入
const { jsonToTableBuilder, jsonToHTMLTable } = JSONTableView2. 快速上手
给定meta和data，即可以将JSON格式的data数据转化为表格形式。下面是一个快速示例：
// 给定meta，即表头结构
const meta = {
order: ['a', 'b', 'c'],
mappings: {
a: {
title: '日'
},
b: {
title: '月'
},
c: {
title: '星',
array: true,
inner: {
order: ['d', 'e'],
mappings: {
d: {
title: '晨',
},
e: {
title: '辉'
}
}
}
}
}
}
// 给定数据
const data = [
{
a: '1',
b: '2',
c: [
{
d: '3',
e: '4'
}
]
},
{
a: '5',
b: '6',
c: [
{
d: '7',
e: '8'
},
{
d: '9',
e: '10'
}
]
}
]
// 直接生成HTML Table源码
const tableHTML = jsonToHTMLTable(meta, data)生成的表格形式如下：
3. 进阶
3.1. Meta
Meta用于定义表头，最后表格的结构，都是通过meta的元素定义的。
示例1，单层数据：
const meta = {
order: ['a', 'b', 'c'],
mappings: {
a: {
title: '日'
},
b: {
title: '月'
},
c: {
title: '星'
}
}
}
const data = [
{
a: '1',
b: '2',
c: '3'
},
{
a: '6',
b: '7',
c: '8'
}
]
jsonToHTMLTable(meta, data)其中order用于定义列的顺序，因为JavaScript对象的键值顺序不保证。mappings中，title对应列的表头显示。最终，生成的表格结构如下：
示例2，双层数据：
const meta = {
order: ['a', 'b', 'c'],
mappings: {
a: {
title: '日'
},
b: {
title: '月'
},
c: {
title: '星',
inner: {
order: ['d', 'e'],
mappings: {
d: {
title: '晨',
},
e: {
title: '辉'
}
}
}
}
}
}
const data = [
{
a: '1',
b: '2',
c: {
d: '3',
e: '4'
}
},
{
a: '6',
b: '7',
c: {
d: '8',
e: '9'
}
}
]
jsonToHTMLTable(meta, data)可以看出，双层数据在meta的内部定义一个inner的结构，其结构与外部meta的结构一致。同样的，三层、四层等多层数据也是支持的。上例生成的结构如下：
一个数据可以是数组，其meta的定义不用改变：
const meta = {
order: ['a', 'b', 'c'],
mappings: {
a: {
title: '日'
},
b: {
title: '月'
},
c: {
title: '星',
inner: {
order: ['d', 'e'],
mappings: {
d: {
title: '晨',
},
e: {
title: '辉'
}
}
}
}
}
}
const data = [
{
a: '1',
b: '2',
c: [
{
d: '3',
e: '4'
}
]
},
{
a: '6',
b: '7',
c: [
{
d: '8',
e: '9'
},
{
d: '10',
e: '11'
}
]
}
]
jsonToHTMLTable(meta, data)上例生成的表格结构如下：
不仅是数组，像undefined、null以及缺失部分字段都能很好的支持。可以自己试一试。
3.2. Builder
使用内建的jsonToHTMLTable函数，只能生成HTML Table源码。需要更灵活的输出格式，或者是输出Excel等其他格式，就需要自己编写Builder了。工具提供了一个框架，其封装了将json解析为表格结构的逻辑，自定义Builder只需要提供几个回调函数处理解析结果即可。
框架会将解析的表格结构传给Builder，Builder需要定义以下五个回调函数：
const builder = {
table: function (next) {},
head: function (next) {},
body: function (next) {},
row: function (next, location) {},
cell: function (next, location) {}
}其中，next是一个函数，调用它框架会继续解析，否则就没有后续了。next接收参数builder，上述例子中，是调用next(this).
location是标记位置，它是一个javascript对象。它包含属性：
- rowNumber: 当前位置的行号。注意，行号的计算从1开始，head和body分别重新计算。
- colNumber: 当前位置的列号。注意，列号的计算从1开始。
- rowSpan: 当前位置跨越的行数。
- colspan: 当前位置跨越的列数。
- at: 其值为head或body，指示当前位置是处于表头还是表体中。
table、head、body回调不会得到location参数，row回调location参数值只包括属性rowNumber和at，只有data回调会包括所有的五个属性。
data是该单元格显示的数据，它是基本类型数据（字符串、数字、布尔值、null、undefined）或基本类型的数组。
一个简单的builder示例如下：
const builder = {
table: function (next) {
console.log('<table>') // table的前置处理
next(this) // 调用next将进入head.
console.log('</table>') // table的后置处理
},
head: function (next) {
console.log('<head>') // head的前置处理。
next(this) // 调用next将进入row.
console.log('</head>') // head的后置处理。
},
body: function (next) {
console.log('<body>') // body的后置处理。
next(this) // 调用next将进入row.
console.log('</body>') // body的后置处理。
},
row: function (next, location) {
console.log('<row>') // row的前置处理。
next(this) // 调用next将进入cell.
console.log('</row>') // row的后置处理。
},
cell: function (data, location) {
console.log('<col>' + data + '</col>') // cell的处理。
}
}怎么说呢，务必要学会这种wrapper的方式编写builder的逻辑。
3.3. buildMeta
meta必须是给定的规范形式，不能有一点容错率，有时候会觉得这在书写上不方便。buildMeta可以将简写形式的meta转化为完整的形式，使用中可以充分地利用这一特性。
省略orders
省略的orders可以从mappings的字段读取，例如：
const meta = {
mappings: {
a: {
title: '日'
},
b: {
title: '月'
},
c: {
title: '星'
}
}
}
console.log(buildMeta(meta))
/* Output:
* > {
* > order: ['a', 'b', 'c'],
* > mappings: {
* > a: {
* > title: '日'
* > },
* > b: {
* > title: '月'
* > },
* > c: {
* > title: '星'
* > }
* > }
* > }
*/在本例中，orders的顺序为['a', 'b', 'c']，但实际情况不保证。
字符串mapping
mapping的完整内容是一个对象，其中包含title等字段。mapping同时也可以是一个字符串，其自动识别为title，例如：
const meta = {
order: ['a', 'b', 'c'],
mappings: {
a: '日',
b: '月',
c: '星'
}
}
console.log(buildMeta(meta))
/* Output:
* > {
* > order: ['a', 'b', 'c'],
* > mappings: {
* > a: {
* > title: '日'
* > },
* > b: {
* > title: '月'
* > },
* > c: {
* > title: '星'
* > }
* > }
* > }
*/连贯用法
不能直接将简写的meta传入jsonToHTMLTable等函数，连贯的用法是：
jsonToHTMLTable(buildMeta(meta), data)3.4. buildMetaFromData
有时候不太想提供meta，想要快速地将数据渲染成表格。可以通过buildMetaFromData方法获取数据的meta，注意使用连贯用法：
jsonToHTMLTable(buildMetaFromData(data), data)4. 注意事项
meta和data的格式需要完全地符合要求，最好不要有太大的偏差。框架本身能够做到一些容错处理，但不可保证对于一些偏离较大的meta和data会产生一些不可预知的运行时异常。常见的诸如meta的格式不完整，data的某些部分与meta对不上。
当然，本来可以通过JSON Schema之类的校验工具提供更加友好的错误提示，但并没有做。后期可能会补上。
5. 参与开发
如果对本项目的开发有兴趣，可以加入进来。加入的途径有三种：
- 对本框架的核心功能进行补充和优化；
- 增加新的builder，优化现有的builder；
- 加入到文档撰写的工作来。
本项目所采用的技术有：
- 基于node.js v6.10.0版本，采用es6语法编写；
- 基于webpack构建生成支持umd标准的库；
- 测试框架是ava；
- 文档采用markdown-pp编译。
构建命令：
npm build测试命令：
npm test文档编译需要首先cd到目录docs，然后调用：
markdown-pp -o ../README.md index.md需要预先安装python的包markdown-pp. markdown-pp安装方法：
pip install MarkdownPP