使用 dataset 管理数据

    ECharts 4 开始支持了 dataset 组件用于单独的数据集声明,从而数据可以单独管理,被多个组件复用,并且可以基于数据指定数据到视觉的映射。这在不少场景下能带来使用上的方便。

    ECharts 4 以前,数据只能声明在各个“系列(series)”中,例如:

    1. option:{
    2. xAxis:{
    3. type:'category',
    4. data:['Matcha Latte','Milk Tea','Cheese Cocoa','Walnut Brownie']
    5. },
    6. yAxis:{}
    7. series:[
    8. {
    9. type:'bar',
    10. name:'2015',
    11. data:[89.3,92.1,94.4,85.4]
    12. },
    13. {
    14. type:'bar',
    15. name:'2016',
    16. data:[95.8,89.4,91.2,76.9]
    17. },
    18. {
    19. type:'bar',
    20. name:'2017',
    21. data:[97.7,83.1,92.5,78.1]
    22. }
    23. ]
    24. }

    这种方式的优点是,直观易理解,以及适于对一些特殊图表类型进行一定的数据类型定制。但是缺点是,为匹配这种数据输入形式,常需要有数据处理的过程,把数据分割设置到各个系列(和类目轴)中。此外,不利于多个系列共享一份数据,也不利于基于原始数据进行图表类型、系列的映射安排。

    于是,ECharts 4 提供了 数据集dataset)组件来单独声明数据,它带来了这些效果:

    • 能够贴近这样的数据可视化常见思维方式:基于数据(dataset 组件来提供数据),指定数据到视觉的映射(由 encode 属性来指定映射),形成图表。
    • 数据和其他配置可以被分离开来,使用者相对便于进行单独管理,也省去了一些数据处理的步骤。
    • 数据可以被多个系列或者组件复用,对于大数据,不必为每个系列创建一份。
    • 支持更多的数据的常用格式,例如二维数组、对象数组等,一定程度上避免使用者为了数据格式而进行转换。

    入门例子

    下面是一个最简单的 dataset 的例子:

    1. option ={
    2. legend:{},
    3. tooltip:{},
    4. dataset:{
    5. // 提供一份数据。
    6. source:[
    7. ['product','2015','2016','2017'],
    8. ['Matcha Latte',43.3,85.8,93.7],
    9. ['Milk Tea',83.1,73.4,55.1],
    10. ['Cheese Cocoa',86.4,65.2,82.5],
    11. ['Walnut Brownie',72.4,53.9,39.1]
    12. ]
    13. },
    14. // 声明一个 X 轴,类目轴(category)。默认情况下,类目轴对应到 dataset 第一列。
    15. xAxis:{type:'category'},
    16. // 声明一个 Y 轴,数值轴。
    17. yAxis:{},
    18. // 声明多个 bar 系列,默认情况下,每个系列会自动对应到 dataset 的每一列。
    19. series:[
    20. {type:'bar'},
    21. {type:'bar'},
    22. {type:'bar'}
    23. ]
    24. }

    效果如下: https://echarts.baidu.com/gallery/view.html?c=dataset-simple0&edit=1&reset=1

    或者也可以使用常见的对象数组的格式:

    1. option ={
    2. legend:{},
    3. tooltip:{},
    4. dataset:{
    5. // 这里指定了维度名的顺序,从而可以利用默认的维度到坐标轴的映射。
    6. // 如果不指定 dimensions,也可以通过指定 series.encode 完成映射,参见后文。
    7. dimensions:['product','2015','2016','2017'],
    8. source:[
    9. {product:'Matcha Latte','2015':43.3,'2016':85.8,'2017':93.7},
    10. {product:'Milk Tea','2015':83.1,'2016':73.4,'2017':55.1},
    11. {product:'Cheese Cocoa','2015':86.4,'2016':65.2,'2017':82.5},
    12. {product:'Walnut Brownie','2015':72.4,'2016':53.9,'2017':39.1}
    13. ]
    14. },
    15. xAxis:{type:'category'},
    16. yAxis:{},
    17. series:[
    18. {type:'bar'},
    19. {type:'bar'},
    20. {type:'bar'}
    21. ]
    22. };

    数据到图形的映射

    本篇里,我们制作数据可视化图表的逻辑是这样的:基于数据,在配置项中指定如何映射到图形。

    概略而言,可以进行这些映射:

    • 指定 dataset 的列(column)还是行(row)映射为图形系列(series)。这件事可以使用 series.seriesLayoutBy 属性来配置。默认是按照列(column)来映射。
    • 指定维度映射的规则:如何从 dataset 的维度(一个“维度”的意思是一行/列)映射到坐标轴(如 X、Y 轴)、提示框(tooltip)、标签(label)、图形元素大小颜色等(visualMap)。这件事可以使用 series.encode 属性,以及 visualMap 组件(如果有需要映射颜色大小等视觉维度的话)来配置。上面的例子中,没有给出这种映射配置,那么 ECharts 就按最常见的理解进行默认映射:X 坐标轴声明为类目轴,默认情况下会自动对应到 dataset.source 中的第一列;三个柱图系列,一一对应到 dataset.source 中后面每一列。 下面详细解释。

    按行还是按列做映射

    有了数据表之后,使用者可以灵活得配置:数据如何对应到轴和图形系列。

    用户可以使用 seriesLayoutBy 配置项,改变图表对于行列的理解。seriesLayoutBy 可取值:

    • 'column': 默认值。系列被安放到 dataset 的列上面。
    • 'row': 系列被安放到 dataset 的行上面。 看这个例子:
    1. option ={
    2. legend:{},
    3. tooltip:{},
    4. dataset:{
    5. source:[
    6. ['product','2012','2013','2014','2015'],
    7. ['Matcha Latte',41.1,30.4,65.1,53.3],
    8. ['Milk Tea',86.5,92.1,85.7,83.1],
    9. ['Cheese Cocoa',24.1,67.2,79.5,86.4]
    10. ]
    11. },
    12. xAxis:[
    13. {type:'category', gridIndex:0},
    14. {type:'category', gridIndex:1}
    15. ],
    16. yAxis:[
    17. {gridIndex:0},
    18. {gridIndex:1}
    19. ],
    20. grid:[
    21. {bottom:'55%'},
    22. {top:'55%'}
    23. ],
    24. series:[
    25. // 这几个系列会在第一个直角坐标系中,每个系列对应到 dataset 的每一行。
    26. {type:'bar', seriesLayoutBy:'row'},
    27. {type:'bar', seriesLayoutBy:'row'},
    28. {type:'bar', seriesLayoutBy:'row'},
    29. // 这几个系列会在第二个直角坐标系中,每个系列对应到 dataset 的每一列。
    30. {type:'bar', xAxisIndex:1, yAxisIndex:1},
    31. {type:'bar', xAxisIndex:1, yAxisIndex:1},
    32. {type:'bar', xAxisIndex:1, yAxisIndex:1},
    33. {type:'bar', xAxisIndex:1, yAxisIndex:1}
    34. ]
    35. }

    效果如下: https://echarts.baidu.com/gallery/view.html?c=dataset-series-layout-by&edit=1&reset=1


    维度(dimension)

    介绍 encode 之前,首先要介绍“维度(dimension)”的概念。

    常用图表所描述的数据大部分是“二维表”结构,上述的例子中,我们都使用二维数组来容纳二维表。现在,当我们把系列(series)对应到“列”的时候,那么每一列就称为一个“维度(dimension)”,而每一行称为数据项(item)。反之,如果我们把系列(series)对应到表行,那么每一行就是“维度(dimension)”,每一列就是数据项(item)。

    维度可以有单独的名字,便于在图表中显示。维度名(dimension name)可以在定义在 dataset 的第一行(或者第一列)。例如上面的例子中,'score''amount''product' 就是维度名。从第二行开始,才是正式的数据。dataset.source 中第一行(列)到底包含不包含维度名,ECharts 默认会自动探测。当然也可以设置 dataset.sourceHeader: true 显示声明第一行(列)就是维度,或者 dataset.sourceHeader: false 表明第一行(列)开始就直接是数据。

    维度的定义,也可以使用单独的 dataset.dimensions 或者 series.dimensions 来定义,这样可以同时指定维度名,和维度的类型(dimension type):

    1. var option1 ={
    2. dataset:{
    3. dimensions:[
    4. {name:'score'},
    5. // 可以简写为 string,表示维度名。
    6. 'amount',
    7. // 可以在 type 中指定维度类型。
    8. {name:'product', type:'ordinal'}
    9. ],
    10. source:[...]
    11. },
    12. ...
    13. };
    14. var option2 ={
    15. dataset:{
    16. source:[...]
    17. },
    18. series:{
    19. type:'line',
    20. // 在系列中设置的 dimensions 会更优先采纳。
    21. dimensions:[
    22. null,// 可以设置为 null 表示不想设置维度名
    23. 'amount',
    24. {name:'product', type:'ordinal'}
    25. ]
    26. },
    27. ...
    28. };

    大多数情况下,我们并不需要去设置维度类型,因为会自动判断。但是如果因为数据为空之类原因导致判断不足够准确时,可以手动设置维度类型。

    维度类型(dimension type)可以取这些值:

    • 'number': 默认,表示普通数据。
    • 'ordinal': 对于类目、文本这些 string 类型的数据,如果需要能在数轴上使用,须是 'ordinal' 类型。ECharts 默认会自动判断这个类型。但是自动判断也是不可能很完备的,所以使用者也可以手动强制指定。
    • 'time': 表示时间数据。设置成 'time' 则能支持自动解析数据成时间戳(timestamp),比如该维度的数据是 '2017-05-10',会自动被解析。如果这个维度被用在时间数轴(axis.type'time')上,那么会被自动设置为 'time' 类型。时间类型的支持参见 data
    • 'float': 如果设置成 'float',在存储时候会使用 TypedArray,对性能优化有好处。
    • 'int': 如果设置成 'int',在存储时候会使用 TypedArray,对性能优化有好处。

    数据到图形的映射(encode)

    了解了维度的概念后,我们就可以使用 encode 来做映射。总体是这样的感觉:

    1. var option ={
    2. dataset:{
    3. source:[
    4. ['score','amount','product'],
    5. [89.3,58212,'Matcha Latte'],
    6. [57.1,78254,'Milk Tea'],
    7. [74.4,41032,'Cheese Cocoa'],
    8. [50.1,12755,'Cheese Brownie'],
    9. [89.7,20145,'Matcha Cocoa'],
    10. [68.1,79146,'Tea'],
    11. [19.6,91852,'Orange Juice'],
    12. [10.6,101852,'Lemon Juice'],
    13. [32.7,20112,'Walnut Brownie']
    14. ]
    15. },
    16. xAxis:{},
    17. yAxis:{type:'category'},
    18. series:[
    19. {
    20. type:'bar',
    21. encode:{
    22. // 将 "amount" 列映射到 X 轴。
    23. x:'amount',
    24. // 将 "product" 列映射到 Y 轴。
    25. y:'product'
    26. }
    27. }
    28. ]
    29. };

    效果如下: https://echarts.baidu.com/gallery/view.html?c=doc-example/dataset-encode-simple0&edit=1&reset=1

    encode 声明的基本结构如下,其中冒号左边是坐标系、标签等特定名称,如 'x', 'y', 'tooltip' 等,冒号右边是数据中的维度名(string 格式)或者维度的序号(number 格式,从 0 开始计数),可以指定一个或多个维度(使用数组)。通常情况下,下面各种信息不需要所有的都写,按需写即可。

    下面是 encode 支持的属性:

    1. // 在任何坐标系和系列中,都支持:
    2. encode:{
    3. // 使用 “名为 product 的维度” 和 “名为 score 的维度” 的值在 tooltip 中显示
    4. tooltip:['product','score']
    5. // 使用 “维度 1” 和 “维度 3” 的维度名连起来作为系列名。(有时候名字比较长,这可以避免在 series.name 重复输入这些名字)
    6. seriesName:[1,3],
    7. // 表示使用 “维度2” 中的值作为 id。这在使用 setOption 动态更新数据时有用处,可以使新老数据用 id 对应起来,从而能够产生合适的数据更新动画。
    8. itemId:2,
    9. // 指定数据项的名称使用 “维度3” 在饼图等图表中有用,可以使这个名字显示在图例(legend)中。
    10. itemName:3
    11. }
    12. // 直角坐标系(grid/cartesian)特有的属性:
    13. encode:{
    14. // 把 “维度1”、“维度5”、“名为 score 的维度” 映射到 X 轴:
    15. x:[1,5,'score'],
    16. // 把“维度0”映射到 Y 轴。
    17. y:0
    18. }
    19. // 极坐标系(polar)特有的属性:
    20. encode:{
    21. radius:3,
    22. angle:2
    23. }
    24. // 地理坐标系(geo)特有的属性:
    25. encode:{
    26. lng:3,
    27. lat:2
    28. }
    29. // 对于一些没有坐标系的图表,例如饼图、漏斗图等,可以是:
    30. encode:{
    31. value:3
    32. }

    下面给出个更丰富的 encode 的示例: https://echarts.baidu.com/gallery/view.html?c=dataset-encode1&edit=1&reset=1


    视觉通道(颜色、尺寸等)的映射

    我们可以使用 visualMap 组件进行视觉通道的映射。详见 visualMap 文档的介绍。这是一个示例: https://echarts.baidu.com/gallery/view.html?c=dataset-encode0&edit=1&reset=1


    默认的映射

    指的一提的是,ECharts 针对最常见直角坐标系中的图表(折线图、柱状图、散点图、K线图等)、饼图、漏斗图,给出了简单的默认的映射,从而不需要配置 encode 也可以出现图表(一旦给出了 encode,那么就不会采用默认映射)。默认的映射规则不易做得复杂,基本规则大体是:

    • 在坐标系中(如直角坐标系、极坐标系等)
      • 如果有类目轴(axis.type 为 'category'),则将第一列(行)映射到这个轴上,后续每一列(行)对应一个系列。
      • 如果没有类目轴,假如坐标系有两个轴(例如直角坐标系的 X Y 轴),则每两列对应一个系列,这两列分别映射到这两个轴上。
    • 如果没有坐标系(如饼图)

    几个常见的映射设置方式

    问:如何把第三列设置为 X 轴,第五列设置为 Y 轴?

    答:

    1. series:{
    2. // 注意维度序号(dimensionIndex)从 0 开始计数,第三列是 dimensions[2]。
    3. encode:{x:2, y:4},
    4. ...
    5. }

    问:如何把第三行设置为 X 轴,第五行设置为 Y 轴?

    答:

    1. series:{
    2. encode:{x:2, y:4},
    3. seriesLayoutBy:'row',
    4. ...
    5. }

    问:如何把第二列设置为标签?

    答:关于标签的显示 label.formatter,现在支持引用特定维度的值,例如:

    1. series:{
    2. label:{
    3. // `'{@score}'` 表示 “名为 score” 的维度里的值。
    4. // `'{@[4]}'` 表示引用序号为 4 的维度里的值。
    5. formatter:'aaa{@product}bbb{@score}ccc{@[4]}ddd'
    6. }
    7. }

    问:如何让第 2 列和第 3 列显示在提示框(tooltip)中?

    答:

    1. series:{
    2. encode:{
    3. tooltip:[1,2]
    4. ...
    5. },
    6. ...
    7. }

    问:数据里没有维度名,那么怎么给出维度名?

    答:

    1. dataset:{
    2. dimensions:['score','amount'],
    3. source:[
    4. [89.3,3371],
    5. [92.1,8123],
    6. [94.4,1954],
    7. [85.4,829]
    8. ]
    9. }

    问:如何把第四列映射为气泡图的点的大小?

    答:

    1. var option ={
    2. dataset:{
    3. source:[
    4. [12,323,11.2],
    5. [23,167,8.3],
    6. [81,284,12],
    7. [91,413,4.1],
    8. [13,287,13.5]
    9. ]
    10. },
    11. visualMap:{
    12. show:false,
    13. dimension:2,// 指向第三列(列序号从 0 开始记,所以设置为 2)。
    14. min:2,// 需要给出数值范围,最小数值。
    15. max:15,// 需要给出数值范围,最大数值。
    16. inRange:{
    17. // 气泡尺寸:5 像素到 60 像素。
    18. symbolSize:[5,60]
    19. }
    20. },
    21. xAxis:{},
    22. yAxis:{},
    23. series:{
    24. type:'scatter'
    25. }
    26. };

    问:encode 里指定了映射,但是不管用?

    答:可以查查有没有拼错,比如,维度名是:'Life Expectancy',encode 中拼成了 'Life Expectency'


    数据的各种格式

    多数常见图表中,数据适于用二维表的形式描述。广为使用的数据表格软件(如 MS Excel、Numbers)或者关系数据数据库都是二维表。他们的数据可以导出成 JSON 格式,输入到 dataset.source 中,在不少情况下可以免去一些数据处理的步骤。

    假如数据导出成 csv 文件,那么可以使用一些 csv 工具如 dsv 或者 PapaParse 将 csv 转成 JSON。

    在 JavaScript 常用的数据传输格式中,二维数组可以比较直观的存储二维表。前面的示例都是使用二维数组表示。

    除了二维数组以外,dataset 也支持例如下面 key-value 方式的数据格式,这类格式也非常常见。但是这类格式中,目前并不支持 seriesLayoutBy 参数。

    1. dataset:[{
    2. // 按行的 key-value 形式(对象数组),这是个比较常见的格式。
    3. source:[
    4. {product:'Matcha Latte', count:823, score:95.8},
    5. {product:'Milk Tea', count:235, score:81.4},
    6. {product:'Cheese Cocoa', count:1042, score:91.2},
    7. {product:'Walnut Brownie', count:988, score:76.9}
    8. ]
    9. },{
    10. // 按列的 key-value 形式。
    11. source:{
    12. 'product':['Matcha Latte','Milk Tea','Cheese Cocoa','Walnut Brownie'],
    13. 'count':[823,235,1042,988],
    14. 'score':[95.8,81.4,91.2,76.9]
    15. }
    16. }]

    多个 dataset 和他们的引用

    可以同时定义多个 dataset。系列可以通过 series.datasetIndex 来指定引用哪个 dataset。例如:

    1. var option ={
    2. dataset:[{
    3. // 序号为 0 的 dataset。
    4. source:[...],
    5. },{
    6. // 序号为 1 的 dataset。
    7. source:[...]
    8. },{
    9. // 序号为 2 的 dataset。
    10. source:[...]
    11. }],
    12. series:[{
    13. // 使用序号为 2 的 dataset。
    14. datasetIndex:2
    15. },{
    16. // 使用序号为 1 的 dataset。
    17. datasetIndex:1
    18. }]
    19. }

    ECharts 3 的数据设置方式(series.data)仍正常使用

    ECharts 4 之前一直以来的数据声明方式仍然被正常支持,如果系列已经声明了 series.data, 那么就会使用 series.data 而非 dataset

    1. {
    2. xAxis:{
    3. type:'category'
    4. data:['Matcha Latte','Milk Tea','Cheese Cocoa','Walnut Brownie']
    5. },
    6. yAxis:{},
    7. series:[{
    8. type:'bar',
    9. name:'2015',
    10. data:[89.3,92.1,94.4,85.4]
    11. },{
    12. type:'bar',
    13. name:'2016',
    14. data:[95.8,89.4,91.2,76.9]
    15. },{
    16. type:'bar',
    17. name:'2017',
    18. data:[97.7,83.1,92.5,78.1]
    19. }]
    20. }

    其实,series.data 也是种会一直存在的重要设置方式。一些特殊的非 table 格式的图表,如 treemapgraphlines 等,现在仍不支持在 dataset 中设置,仍然需要使用 series.data。另外,对于巨大数据量的渲染(如百万以上的数据量),需要使用 appendData 进行增量加载,这种情况不支持使用 dataset


    其他

    目前并非所有图表都支持 dataset。支持 dataset 的图表有:linebarpiescattereffectScatterparallelcandlestickmapfunnelcustom。后续会有更多的图表进行支持。

    最后,给出一个示例,多个图表共享一个 dataset,并带有联动交互: https://echarts.baidu.com/gallery/view.html?c=dataset-link&edit=1&reset=1