ECharts 入门教程 ECharts图表自定义系列

2024-02-25 开发教程 ECharts 入门教程匿名 5℃

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 需要时间开销。

上一节：设置ECharts主题河流图的提示框浮层

下一节： ECharts自定义系列属性

"ECharts 入门教程"的目录

ECharts 入门教程 ECharts图表自定义系列

renderItem 方法