ECharts自定义系列的渲染逻辑
renderItem
ECharts 自定义（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'})。
renderItem 函数的参数
arguments
arguments 是 renderItem 函数的参数，包括了 params 参数和 api 参数，关于这两参数的详细介绍，请参考下述内容。
- params
renderItem 函数的第一个参数，含有：
{ context: // {Object} 一个可供开发者暂存东西的对象。 seriesId: // {string} 本系列 id。 seriesName: // {string} 本系列 name。 seriesIndex: // {number} 本系列 index。 dataIndex: // {number} 数据项的 index。 dataIndexInside: // {number} 数据项在当前坐标系中可见的数据的 index（即 dataZoom 当前窗口中的数据的 index）。 dataInsideLength: // {number} 当前坐标系中可见的数据长度（即 dataZoom 当前窗口中的数据数量）。 coordSys: // 不同的坐标系中，coordSys 里的信息不一样，含有如下这些可能： coordSys: { type: 'cartesian2d', x: // {number} grid rect 的 x y: // {number} grid rect 的 y width: // {number} grid rect 的 width height: // {number} grid rect 的 height }, coordSys: { type: 'calendar', x: // {number} calendar rect 的 x y: // {number} calendar rect 的 y width: // {number} calendar rect 的 width height: // {number} calendar rect 的 height cellWidth: // {number} calendar cellWidth cellHeight: // {number} calendar cellHeight rangeInfo: { start: // calendar 日期开端 end: // calendar 日期结尾 weeks: // calendar 周数 dayCount: // calendar 日数 } }, coordSys: { type: 'geo', x: // {number} geo rect 的 x y: // {number} geo rect 的 y width: // {number} geo rect 的 width height: // {number} geo rect 的 height }, coordSys: { type: 'polar', cx: // {number} polar 的中心坐标 cy: // {number} polar 的中心坐标 r: // {number} polar 的外半径 r0: // {number} polar 的内半径 }, coordSys: { type: 'singleAxis', x: // {number} singleAxis rect 的 x y: // {number} singleAxis rect 的 y width: // {number} singleAxis rect 的 width height: // {number} singleAxis rect 的 height } }其中，关于 dataIndex 和 dataIndexInside 的区别：
- dataIndex 指的 dataItem 在原始数据中的 index。
- dataIndexInside 指的是 dataItem 在当前数据窗口（参见 dataZoom）中的 index。
renderItem.arguments.api 中使用的参数都是 dataIndexInside 而非 dataIndex，因为从 dataIndex 转换成 dataIndexInside 需要时间开销。
- api
renderItem 函数的第二个参数，它具有以下的属性：
- value
得到给定维度的数据值：
@param {number} dimension 指定的维度（维度从 0 开始计数）。 @param {number} [dataIndexInside] 一般不用传，默认就是当前数据项的 dataIndexInside。 @return {number} 给定维度上的值。 - coord
将数据值映射到坐标系上：
@param {Array.<number>} data 数据值。 @return {Array.<number>} 画布上的点的坐标，至少包含：[x, y] 对于polar坐标系，还会包含其他信息： polar: [x, y, radius, angle] - size
给定数据范围，映射到坐标系上后的长度。
例如，cartesian2d中，api.size([2, 4]) 返回 [12.4, 55]，表示 x 轴数据范围为 2 映射得到长度是 12.4，y 轴数据范围为 4 时应设得到长度为 55。
在一些坐标系中，如极坐标系（polar）或者有 log 数轴的坐标系，不同点的长度是不同的，所以需要第二个参数，指定获取长度的点。
@param {Array.<number>} dataSize 数据范围。 @param {Array.<number>} dataItem 获取长度的点。 @return {Array.<number>} 画布上的长度 - style
能得到 series.itemStyle.normal 中定义的样式信息和视觉映射得到的样式信息，可直接用于绘制图元。也可以用这种方式覆盖这些样式信息：api.style({fill: 'green', stroke: 'yellow'})：
@param {Object} [extra] 额外指定的样式信息。 @param {number} [dataIndexInside] 一般不用传，默认就是当前数据项的 dataIndexInside。 @return {Object} 直接用于绘制图元的样式信息。 - styleEmphasis
能得到 series.itemStyle.emphasis 中定义的样式信息和视觉映射的样式信息，可直接用于绘制图元。也可以用这种方式覆盖这些样式信息：api.style({fill: 'green', stroke: 'yellow'})：
@param {Object} [extra] 额外指定的样式信息。 @param {number} [dataIndexInside] 一般不用传，默认就是当前数据项的 dataIndexInside。 @return {Object} 直接用于绘制图元的样式信息。 - visual
得到视觉映射的样式信息。比较少被使用：
@param {string} visualType 'color', 'symbol', 'symbolSize', ... @param {number} [dataIndexInside] 一般不用传，默认就是当前数据项的 dataIndexInside。 @return {string|number} 视觉映射的样式值。 - barLayout
当需要采用 barLayout 的时候，比如向柱状图上附加些东西，可以用这个方法得到 layout 信息。 参见ECharts柱状图例子。
@param {Object} opt @param {number} opt.count 每个簇有多少个 bar。 @param {number} [opt.barWidth] bar 宽度。 @param {number} [opt.barMaxWidth] bar 最大宽度。 @param {number} [opt.barGap] 每个簇的 bar 之间的宽度。 @param {number} [opt.barCategoryGap] 不同簇间的宽度。 @return {Array.<Object>} [{ width: number bar 的宽度。 offset: number bar 的偏移量，以bar最左为基准。 offsetCenter: number bar 的偏移量，以bar中心为基准。 }, ...] - currentSeriesIndices
得到系列的 当前index。注意这个 index 不同于系列定义时的 index。这个 index 是当 legend 组件进行了系列筛选后，剩余的系列排列后的 index。
@return {number} - font
得到可以直接进行样式设置的文字信息字符串。
@param {Object} opt @param {string} [opt.fontStyle] @param {number} [opt.fontWeight] @param {number} [opt.fontSize] @param {string} [opt.fontFamily] @return {string} font 字符串。 - getWidth
@return {number} echarts 容器的宽度。 - getHeight
用于设置容器的高度。
@return {number} echarts 容器的高度。 - getZr
@return {module:zrender} zrender 实例。 - getDevicePixelRatio
@return {number} 得到当前 devicePixelRatio。
- value
return
自定义系列的图形元素。每个图形元素是一个 object。详细信息参见：graphic。（width\height\top\bottom 不支持）
如果什么都不渲染，可以不返回任何东西。
例如：
// 单独一个矩形
{
type: 'rect',
shape: {
x: x, y: y, width: width, height: height
},
style: api.style()
}// 一组图形元素
{
type: 'group',
// 如果 diffChildrenByName 设为 true，则会使用 child.name 进行 diff，
// 从而能有更好的过度动画，但是降低性能。缺省为 false。
// diffChildrenByName: true,
children: [{
type: 'circle',
shape: {
cx: cx, cy: cy, r: r
},
style: api.style()
}, {
type: 'line',
shape: {
x1: x1, y1: y1, x2: x2, y2: y2
},
style: api.style()
}]
}