ECharts自定義系列的渲染邏輯

renderItem 

ECharts 自定義（custom）系列需要開發(fā)者自己提供圖形渲染的邏輯。這個渲染邏輯一般命名為 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 中的每個數(shù)據(jù)項（為方便描述，這里稱為 dataItem)，會調(diào)用此 renderItem 函數(shù)。

renderItem 函數(shù)提供了兩個參數(shù)：

• params：包含了當前數(shù)據(jù)信息和坐標系的信息。
• api：是一些開發(fā)者可調(diào)用的方法集合。

renderItem 函數(shù)須返回根據(jù)此 dataItem 繪制出的圖形元素的定義信息，參見 renderItem.return。

一般來說，renderItem 函數(shù)的主要邏輯，是將 dataItem 里的值映射到坐標系上的圖形元素。這一般需要用到 renderItem.arguments.api 中的兩個函數(shù)：

• api.value(...)：意思是取出 dataItem 中的數(shù)值。例如 api.value(0) 表示取出當前 dataItem 中第一個維度的數(shù)值。
• api.coord(...)：意思是進行坐標轉(zhuǎn)換計算。例如 var point = api.coord([api.value(0), api.value(1)]) 表示 dataItem 中的數(shù)值轉(zhuǎn)換成坐標系上的點。

有時候還需要用到 api.size(...) 函數(shù)，表示得到坐標系上一段數(shù)值范圍對應的長度。

返回值中樣式的設(shè)置可以使用 api.style(...) 函數(shù)，他能得到 series.itemStyle.normal 中定義的樣式信息，以及視覺映射的樣式信息。也可以用這種方式覆蓋這些樣式信息：api.style({fill: 'green', stroke: 'yellow'})。

renderItem 函數(shù)的參數(shù)

arguments

arguments 是 renderItem 函數(shù)的參數(shù)，包括了 params 參數(shù)和 api 參數(shù)，關(guān)于這兩參數(shù)的詳細介紹，請參考下述內(nèi)容。

• params
  

  renderItem 函數(shù)的第一個參數(shù)，含有：

  {
      context: // {Object} 一個可供開發(fā)者暫存東西的對象。
      seriesId: // {string} 本系列 id。
      seriesName: // {string} 本系列 name。
      seriesIndex: // {number} 本系列 index。
      dataIndex: // {number} 數(shù)據(jù)項的 index。
      dataIndexInside: // {number} 數(shù)據(jù)項在當前坐標系中可見的數(shù)據(jù)的 index（即 dataZoom 當前窗口中的數(shù)據(jù)的 index）。
      dataInsideLength: // {number} 當前坐標系中可見的數(shù)據(jù)長度（即 dataZoom 當前窗口中的數(shù)據(jù)數(shù)量）。
      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 日期結(jié)尾
              weeks: // calendar 周數(shù)
              dayCount: // calendar 日數(shù)
          }
      },
      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 的內(nèi)半徑
      },
      coordSys: {
          type: 'singleAxis',
          x: // {number} singleAxis rect 的 x
          y: // {number} singleAxis rect 的 y
          width: // {number} singleAxis rect 的 width
          height: // {number} singleAxis rect 的 height
      }
  }

  其中，關(guān)于 dataIndex 和 dataIndexInside 的區(qū)別：

  • dataIndex 指的 dataItem 在原始數(shù)據(jù)中的 index。
  • dataIndexInside 指的是 dataItem 在當前數(shù)據(jù)窗口（參見 dataZoom）中的 index。

  renderItem.arguments.api 中使用的參數(shù)都是 dataIndexInside 而非 dataIndex，因為從 dataIndex 轉(zhuǎn)換成 dataIndexInside 需要時間開銷。

• api
  

  renderItem 函數(shù)的第二個參數(shù)，它具有以下的屬性：

  • value
    

    得到給定維度的數(shù)據(jù)值：

    @param {number} dimension 指定的維度（維度從 0 開始計數(shù)）。
    @param {number} [dataIndexInside] 一般不用傳，默認就是當前數(shù)據(jù)項的 dataIndexInside。
    @return {number} 給定維度上的值。

  • coord
    

    將數(shù)據(jù)值映射到坐標系上：

    @param {Array.<number>} data 數(shù)據(jù)值。
    @return {Array.<number>} 畫布上的點的坐標，至少包含：[x, y]
            對于polar坐標系，還會包含其他信息：
            polar: [x, y, radius, angle]

  • size
    

    給定數(shù)據(jù)范圍，映射到坐標系上后的長度。

    例如，cartesian2d中，api.size([2, 4]) 返回 [12.4, 55]，表示 x 軸數(shù)據(jù)范圍為 2 映射得到長度是 12.4，y 軸數(shù)據(jù)范圍為 4 時應設(shè)得到長度為 55。

    在一些坐標系中，如極坐標系（polar）或者有 log 數(shù)軸的坐標系，不同點的長度是不同的，所以需要第二個參數(shù)，指定獲取長度的點。

    @param {Array.<number>} dataSize 數(shù)據(jù)范圍。
    @param {Array.<number>} dataItem 獲取長度的點。
    @return {Array.<number>} 畫布上的長度

  • style
    

    能得到 series.itemStyle.normal 中定義的樣式信息和視覺映射得到的樣式信息，可直接用于繪制圖元。也可以用這種方式覆蓋這些樣式信息：api.style({fill: 'green', stroke: 'yellow'})：

    @param {Object} [extra] 額外指定的樣式信息。
    @param {number} [dataIndexInside] 一般不用傳，默認就是當前數(shù)據(jù)項的 dataIndexInside。
    @return {Object} 直接用于繪制圖元的樣式信息。

  • styleEmphasis
    

    能得到 series.itemStyle.emphasis 中定義的樣式信息和視覺映射的樣式信息，可直接用于繪制圖元。也可以用這種方式覆蓋這些樣式信息：api.style({fill: 'green', stroke: 'yellow'})：

    @param {Object} [extra] 額外指定的樣式信息。
    @param {number} [dataIndexInside] 一般不用傳，默認就是當前數(shù)據(jù)項的 dataIndexInside。
    @return {Object} 直接用于繪制圖元的樣式信息。

  • visual
    

    得到視覺映射的樣式信息。比較少被使用：

    @param {string} visualType 'color', 'symbol', 'symbolSize', ...
    @param {number} [dataIndexInside] 一般不用傳，默認就是當前數(shù)據(jù)項的 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
    

    得到可以直接進行樣式設(shè)置的文字信息字符串。

    @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
    

    用于設(shè)置容器的高度。

    @return {number} echarts 容器的高度。

  • getZr
    

    @return {module:zrender} zrender 實例。

  • getDevicePixelRatio
    

    @return {number} 得到當前 devicePixelRatio。

return 

自定義系列的圖形元素。每個圖形元素是一個 object。詳細信息參見：graphic。（width\height\top\bottom 不支持）

如果什么都不渲染，可以不返回任何東西。

例如：

// 單獨一個矩形
{
    type: 'rect',
    shape: {
        x: x, y: y, width: width, height: height
    },
    style: api.style()
}

// 一組圖形元素
{
    type: 'group',
    // 如果 diffChildrenByName 設(shè)為 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()
    }]
}