一起读 ECharts 配置项手册之 series[i]-line（上）

之前的文章写得都比较杂，还总是想不到要写点什么……

所以最近打算把 ECharts 所有系列挨个聊一遍，写一个 series 系列的简单介绍，解决一大段时间的难选题问题，顺便方便比我还新的新手入门。

正文

• series[i]-line.type

series[i]-line 也就是折线图/面积图，要使用折线图/面积图时，首先需要使用 series[i]-line 的第一个配置「type」，将其设置为字符串值 'line'。

• series[i]-line.id

「id」这个配置无默认值，但实测最新的 ECharts 4.2.1 是有默认值的，规则如下（「seriesId」即「id」，「seriesIndex」即 series[i] 的 i，「seriesName」是后面的「series[i]-line.name」）

seriesId = 'series' + seriesIndex + '0'；

seriesName = 'series' + seriesIndex

「id」可传入字符串值作为当前 series[i] 的 ID，用途如官方所说，「可用于在 option 或者 API 中引用组件」。

举个栗子，这样的配置项，series 中有多个 series[i]

option = {
  ...,
  series: [
    {
      id: 'series1',
      ...
    }, {
      id: 'series2',
      ...
    }, {
      id: 'series3',
      ...
    },
  ]
}

我们想更新 series2 的数据，可以这么写，setOption 会自动匹配。

myChart.setOption({
  series: [{
    id: 'series2',
    data: [1, 2, 3, 4, 5]
  }]
})

• series[i]-line.name

「name」系列名称，可用于

1. tooltip.formatter 的模版变量 {a}
2. legend.data 的图例筛选［ seriesName1, seriesName2, ...］
3. setOption 更新数据和配置项时用于指定对应的系列（与前面的「id」作用类似）

• series[i]-line.coordinateSystem

「coordinateSystem」，用于指定该系列使用的坐标系

1. 默认值为 'cartesian2d'，使用二维的直角坐标系（也称笛卡尔坐标系），通过 xAxisIndex, yAxisIndex 指定相应的坐标轴组件。
2. 也可以设置为 'polar'，使用极坐标系，通过 polarIndex 指定相应的极坐标组件

• series[i]-line.xAxisIndex 和 series[i]-line.yAxisIndex

默认值为 0，使用的 x/y 轴的 index（xAxis[i] / yAxis[i]），在单个图表实例中存在多个 x/y 轴的时候有用。

• series[i]-line.polarIndex

与上条类似，默认值为 0，使用的极坐标系的 index（polar[i]），在单个图表实例中存在多个极坐标系的时候有用。

• series[i]-line.symbol

标记的图形，可传入字符串值或函数。默认值为 'emptyCircle'。

1. 还可以设置为'circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow', 'none' ；
2. 通过 'image://url' 设置为图片，其中 URL 为图片的链接，或者 dataURI；
3. 通过 'path://' 将图标设置为任意的矢量路径，支持任意比例。SVG PathData 可以去阿里巴巴矢量图标库 Iconfont 网站下载，也可以从 Adobe Illustrator 等工具编辑导出。
4. 如果需要每个数据的图形不一样，可以设置为如下格式的回调函数：(value: Array|number, params: Object) => string
   1. 其中第一个参数 value 为 data 中的数据值。
   2. 第二个参数params 是其它的数据项参数。
   3. 经验证这个回调函数在 4.2.1 里还未支持，在 4.3.0-rc.2（Pre-release） 里已提供 。

• series[i]-line.symbolSize

标记的大小，可传入数值、数组或函数，默认值为 4（宽和高均为 4），也可以分别设置宽高，如 [20, 10] 表示标记宽为 20，高为 10。

同样支持回调函数：

(value: Array|number, params: Object) => number|Array

1. 其中第一个参数 value 为 data 中的数据值
2. 第二个参数params 是其它的数据项参数。

• series[i]-line.symbolRotate

标记的旋转角度，可传入数值，如 90（代表逆时针旋转 90 度）。

• series[i]-line.symbolKeepAspect

如果 symbol 是 path:// 的形式，是否在缩放时保持该图形的长宽比，可传入布尔值，默认为 false。

• series[i]-line.symbolOffset

标记相对于原本位置的偏移，可传入数组，默认值为 [0, 0] ，数组元素既可以是数值，也可以是百分比（以元素尺寸，即宽或者高作为 100%）。数组第一个值代表向右的偏移量，第二个值代表向下的偏移量。

• series[i]-line.showSymbol

是否显示 symbol, 可传入布尔值，默认为 true。如果 false 则只有在 tooltip hover 的时候显示。

• series[i]-line.showAllSymbol

是否显示所有 symbol 图形，可传入布尔值，只在主轴为类目轴（axis.type 为 'category'）时有效，可选值如下：

1. 默认值 'auto'，如果有足够空间则显示所有 symbol 图形，否则随主轴标签间隔隐藏策略；
2. true，显示所有 symbol 图形；
3. 随主轴标签间隔隐藏策略，效果如下图。

• series[i]-line.hoverAnimation

是否开启 hover 在拐点标志上的提示动画效果（强调/高亮），可传入布尔值，默认为 true。比如鼠标浮在该 symbol 上、浮在 series 对应图例（legend）上、浮在该 symbol 所在轴（tootip.trigger 为 'axis'）等。

• series[i]-line.legendHoverLink

是否启用图例 hover 时的联动高亮，即鼠标浮在图例（legend）上的时候，该图例对应的 series 的 symbol 是否高亮（放大）可传入布尔值，默认为 true。

• series[i]-line.stack

数据堆叠，同个类目轴上系列配置相同的stack值后，后一个系列的值会在前一个系列的值上相加（堆叠柱图也是用这个属性实现）。相同数据是否堆叠的对比，如效果官方例子所示：

• series[i]-line.cursor

鼠标浮在该系列的 symbol 上时，鼠标光标的样式，同 CSS 的 cursor，可传入字符串值，默认为一只手 'pointer' ，其他可用属性还有 'crosshair'，'move'，'wait' 等等。

• series[i]-line.connectNulls

是否连接空数据，可传入布尔值，默认值为 false。效果如下：

• series[i]-line.clipOverflow

是否对超出部分裁剪，可传入布尔值，默认为裁剪 true。

• series[i]-line.step

是否是阶梯线图，可传入布尔值或字符串值，默认为 false。可以设置为 true 显示成阶梯线图，也支持设置成 'start'（与 true 等效）, 'middle', 'end' 分别配置在当前点，当前点与下个点的中间点，下个点拐弯，效果见下图（官方示例）。

• series[i]-line.smooth

是否曲线平滑度，可传入布尔值或 0 到 1 的数值（数值越大越平滑），默认值为 false，与传入 0 等效，即折线效果；传入 true，与传入 0.5 等效。具体效果如下图所示。

• series[i]-line.smoothMonotone

平滑算法，可传入字符串值，默认值手册未提及，经测试应该为 'none'，即老算法；传入 'x' 则曲线在数据点处方向为水平，传入 'y' 则为竖直。具体效果如下图。

• series[i]-line.sampling

官方描述：折线图在数据量远大于像素点时候的降采样策略，开启后可以有效的优化图表的绘制效率，默认关闭，也就是全部绘制不过滤数据点。

'average' 取过滤点的平均值

'max' 取过滤点的最大值

'min' 取过滤点的最小值

'sum' 取过滤点的和

具体效果如下图：

• series[i]-line.zlevel

折线图所有图形的 zlevel 值，可传入数值，默认值为 0。

主要用于 Canvas 分层，将变化较多和较少的组件通过分层隔离开，但要注意分层过多会加大内存开销，需要用手机浏览时谨慎使用。

• series[i]-line.z

官方描述：折线图组件的所有图形的z值。控制图形的前后顺序。z 值小的图形会被 z 值大的图形覆盖。z 相比 zlevel 优先级更低，而且不会创建新的 Canvas。

可传入数值，默认值为 2。

• series[i]-line.silent

官方描述：图形是否不响应和触发鼠标事件，默认为 false，即响应和触发鼠标事件。

可传入布尔值。

series[i]-line.animation

是否开启动画，可传入布尔值，默认为 true。

series[i]-line.animationThreshold

关闭动画的阈值，当单个 series 显示的图形数量大于阈值时会关闭动画。

可传入数值，默认 2000.

• series[i]-line.animationDuration

初始动画持续的时长，symbol 渲染动画的快慢，可传入数值，默认值 1000（毫秒），也可通过回调函数为每个数据定义不同的时长。

animationDuration: function (idx) {
    // 越往后的数据动画时长越长
    return idx * 100;
}

• series[i]-line.animationDurationUpdate

更新动画持续的时长， symbol 渲染动画的快慢，可传入数值，默认值 1000（毫秒），也可通过回调函数为每个数据定义不同的时长。

• series[i]-line.animationDelay

初始动画的延迟时间，symbol 渲染动画的早晚，可传入数值，默认值 0（毫秒），也可通过回调函数为每个数据定义不同的时长。

animationDelay: function (idx) {
    // 越往后的数据延迟越长
    return idx * 100;
}

• series[i]-line.animationDelayUpdate

更新动画的延迟时间，symbol 渲染动画的早晚，可传入数值，默认值 0（毫秒），也可通过回调函数为每个数据定义不同的时长。

series[i]-line.animationEasing

初始动画的缓动效果，line 渲染动画的效果，可传入字符串值，默认为「linear」，匀速渲染。

其他效果如「quadraticIn」、「cubicIn」等见手册处提供的官方示例：

series[i]-line.animationEasingUpdate

更新动画的缓动效果，line 渲染动画的效果，可传入字符串值，默认为「linear」，匀速渲染。

• series[i]-line.data

系列中的数据内容数组。数组项通常为具体的数据项。可传入 Object。

Object 常见的形式有：

1、二维数组表示

series: [{
    data: [
        // 维度X   维度Y   其他维度 ...
        [  3.4,    4.5,   15,   43],
        [  4.2,    2.3,   20,   91],
        [  10.8,   9.5,   30,   18],
        [  7.2,    8.8,   18,   57]
    ]
}

其中「维度X」和「维度Y」会默认对应于平面直角坐标系的 xAxis 和 yAxis，或者极坐标系的 radiusAxis 和 angleAxis。

2、一维数组表示

当只有一个轴为类目轴（axis.type 为 'category'）的时候，数据可以简化为一维数组。例如：

xAxis: {
    data: ['a', 'b', 'm', 'n']
},
series: [{
    // 与 xAxis.data 一一对应。
    data: [23,  44,  55,  19]
    // 它其实是下面这种形式的简化：
    // data: [[0, 23], [1, 44], [2, 55], [3, 19]]
}]

3、数组项为（部分/全部）对象的情况

用于数据图形样式的个性化定制，例如：

[
    12,
    34,
    {
        value : 56,
        //自定义标签样式，仅对该数据项有效
        label: {},
        //自定义特殊 itemStyle，仅对该数据项有效
        itemStyle:{}
    },
    10
]
// 或
[
    [12, 33],
    [34, 313],
    {
        value: [56, 44],
        label: {},
        itemStyle:{}
    },
    [10, 33]
]

对象的 key 支持：

name：数据项名称，

value：单个数据项的数值，

symbol&symbolSize：单个数据项的图形&图形大小，

symbolRotate：单个数据项的图形角度，

symbolKeepAspect：单个数据项的图形是否保持宽高比，

symbolOffset ：单个数据项的图形的位置偏移量，

label：单个数据项的文字标签，比 series[i]-line.label 优先级高，

itemStyle：单个数据项的图形样式，比 series[i]-line.itemStyle 优先级高，

emphasis：单个数据项的图形的高亮形式，比 series[i]-line.emphasis 优先级高，

tooltip：单个数据项图形的提示框，比 series[i]-line.tooltip 优先级高。

待续

不写不知道，一写发现内容真挺多的，一个 series[i]-line 好长时间都没写完，只好把一些子配置太多的配置项，留到下次写

另外，也在考虑是否有必要逐个介绍配置项，因为有些仅仅是官方手册的摘抄……

比如只介绍些相对复杂的或有需要注意情况的？

各位读者大人，帮我拿个主意吧

待续内容

• series[i]-line.label

官方描述：图形上的文本标签，可用于说明图形的一些数据信息，比如值，名称等。

该配置项有大量子配置，常用的有 show、position、color、formatter 等等，我们下次展开。

• series[i]-line.itemStyle、series[i]-line.lineStyle、series[i]-line.areaStyle、series[i]-line.emphasis

官方描述分别为：折线拐点标志的样式、折线线条样式、区域填充样式、图形的高亮样式。

这 4 个配置项同样有不少子配置，下次展开。

• series[i]-line.dimensions、series[i]-line.encode、series[i]-line.seriesLayoutBy、series[i]-line.datasetIndex

这 4 个配置与 4.0 新功能「使用 dataset 管理数据集」有关，下次展开。

• series[i]-line.markPoint、series[i]-line.markLine、series[i]-line.markArea、series[i]-line.tooltip

分别用于：图标的标注、标线、标域，图形的提示框，这 4 个配置项同样有不少子配置，下次展开。