ECharts图表自定义系列

series[i]-custom表示ECharts图表的自定义系列，自定义系列也就是您能够根据您自己的需要对ECharts图表中的图形元素自定义其渲染方式，这样做可以帮助您扩展出不一样的图表。

同时，echarts 会统一管理图形的创建删除、动画、与其他组件（如 dataZoom、visualMap）的联动，使开发者不必纠结这些细节。

例如，下面的例子使用 custom series 扩展出了 x-range 图：

点击编辑实例 》》

更多的例子参见：custom examples

您可以参考：自定义系列教程

renderItem 方法

开发者自定义渲染逻辑（renderItem 函数），有关 renderItem 函数的详细内容您可以参考下节内容。

custom 系列需要开发者自己提供图形渲染的逻辑。这个渲染逻辑一般命名为 renderItem。例如：

var option = {
    ...,
    series: [{
        type: 'custom',
        renderItem: function (params, api) {
            var categoryIndex = api.value(0);
            var start = api.coord([api.value(1), categoryIndex]);
            var end = api.coord([api.value(2), categoryIndex]);
            var height = api.size([0, 1])[1] * 0.6;

            return {
                type: 'rect',
                shape: echarts.graphic.clipRectByRect({
                    x: start[0],
                    y: start[1] - height / 2,
                    width: end[0] - start[0],
                    height: height
                }, {
                    x: params.coordSys.x,
                    y: params.coordSys.y,
                    width: params.coordSys.width,
                    height: params.coordSys.height
                }),
                style: api.style()
            };
        },
        data: data
    }]
}

对于 data 中的每个数据项（为方便描述，这里称为 dataItem)，会调用此 renderItem 函数。

renderItem 函数提供了两个参数：

• params：包含了当前数据信息和坐标系的信息。
• api：是一些开发者可调用的方法集合。

renderItem 函数须返回根据此 dataItem 绘制出的图形元素的定义信息，参见 renderItem.return。

一般来说，renderItem 函数的主要逻辑，是将 dataItem 里的值映射到坐标系上的图形元素。这一般需要用到 renderItem.arguments.api 中的两个函数：

• api.value(...)，意思是取出 dataItem 中的数值。例如 api.value(0) 表示取出当前 dataItem 中第一个维度的数值。
• api.coord(...)，意思是进行坐标转换计算。例如 var point = api.coord([api.value(0), api.value(1)]) 表示 dataItem 中的数值转换成坐标系上的点。

有时候还需要用到 api.size(...) 函数，表示得到坐标系上一段数值范围对应的长度。

返回值中样式的设置可以使用 api.style(...) 函数，他能得到 series.itemStyle.normal 中定义的样式信息，以及视觉映射的样式信息。也可以用这种方式覆盖这些样式信息：api.style({fill: 'green', stroke: 'yellow'})。

维度的映射（encode 和 dimensions 属性）

custom 系列往往需要定义 series.encode，主要用于指明 data 的哪些维度映射到哪些数轴上。从而，echarts 能根据这些维度的值的范围，画出合适的数轴刻度。 同时，encode.tooltip 和 encode.label 也可以被指定，指明默认的 tooltip 和 label 显示什么内容。series.dimensions 也可以被指定，指明显示在 tooltip 中的维度名称，或者维度的类型。

例如：

series: {
    type: 'custom',
    renderItem: function () {
        ...
    },
    encode: {
        x: [2, 4, 3],
        y: 1,
        label: 0,
        tooltip: [2, 4, 3]
    }
}

与 dataZoom 组件的结合

与 dataZoom 结合使用的时候，常常使用会设置 dataZoom.filterMode 为 'weakFilter'，从而让 dataItem 部分超出坐标系边界的时候，不会整体被过滤掉。

关于 dataIndex 和 dataIndexInside 的区别

• dataIndex 指的 dataItem 在原始数据中的 index。
• dataIndexInside 指的是 dataItem 在当前数据窗口（参见 dataZoom）中的 index。

renderItem.arguments.api 中使用的参数都是 dataIndexInside 而非 dataIndex，因为从 dataIndex 转换成 dataIndexInside 需要时间开销。