ECharts 入门教程 ECharts自定义系列属性

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

ECharts自定义系列属性

在上一节的内容中，我们初步认识了ECharts自定义系列，而本节的内容是介绍ECharts自定义系列属性。

type

在ECharts自定义系列中 type 属性的取值为 'custom'

name

系列名称，用于tooltip的显示，legend 的图例筛选，在 setOption 更新数据和配置项时用于指定对应的系列。

legendHoverLink

是否启用图例 hover 时的联动高亮，默认为 true。

coordinateSystem

该系列使用的坐标系，可选：

null 或者 'none'：无坐标系。

'cartesian2d'（默认）：使用二维的直角坐标系（也称笛卡尔坐标系），通过 xAxisIndex, yAxisIndex指定相应的坐标轴组件。

'polar'：使用极坐标系，通过 polarIndex 指定相应的极坐标组件

'geo'：使用地理坐标系，通过 geoIndex 指定相应的地理坐标系组件。

'none'：不使用坐标系。

xAxisIndex

使用的 x 轴的 index，在单个图表实例中存在多个 x 轴的时候有用。

yAxisIndex

使用的 y 轴的 index，在单个图表实例中存在多个 y轴的时候有用。

polarIndex

使用的极坐标系的 index，在单个图表实例中存在多个极坐标系的时候有用。

geoIndex

使用的地理坐标系的 index，在单个图表实例中存在多个地理坐标系的时候有用。

calendarIndex

使用的日历坐标系的 index，在单个图表实例中存在多个日历坐标系的时候有用。

itemStyle

图形样式，有 normal 和 emphasis 两个状态。normal 是图形在默认状态下的样式；emphasis 是图形在高亮状态下的样式，比如在鼠标悬浮或者图例联动高亮时。

dimensions

使用 dimensions 定义 data 每个维度的信息。例如：

series: {
    type: 'xxx',
    // 定义了每个维度的名称。这个名称会被显示到默认的 tooltip 中。
    dimensions: ['date', 'open', 'close', 'highest', 'lowest']
    data: [
        // 有了上面 dimensions 定义后，下面这五个维度的名称分别为：
        // 'date', 'open', 'close', 'highest', 'lowest'
        [12, 44, 55, 66, 2],
        [23, 6, 16, 23, 1],
        ...
    ]
}

series: {
    type: 'xxx',
    dimensions: [
        null,                // 如果此维度不想给出定义，则使用 null 即可
        {type: 'ordinal'},   // 只定义此维度的类型。
                             // 'ordinal' 表示离散型，一般文本使用这种类型。
                             // 如果类型没有被定义，会自动猜测类型。
        {name: 'good', type: 'number'},
        'bad'                // 等同于 {name: 'bad'}
    ]
}

dimensions 数组中的每一项可以是：

string，如 'someName'，等同于 {name: 'someName'}
Object，属性可以有：
- name: string。
- type: string，支持
  - number
  - float，即 Float64Array
  - int，即 Int32Array
  - ordinal，表示离散数据，一般指字符串。
  - time，表示时间类型，时间类型的支持参见 data

值得一提的是，当定义了 dimensions 后，默认 tooltip 中对个维度的显示，会变为『竖排』，从而方便显示每个维度的名称。如果没有定义 dimensions，则默认 tooltip 会横排显示，且只显示数值没有维度名称可显示。

encode

可以定义 data 的哪个维度被编码成什么。比如：

series: {
    type: 'xxx',
    encode: {
        x: [3, 1, 5],      // 表示维度 3、1、5 映射到 x 轴。
        y: 2,              // 表示维度 2 映射到 y 轴。
        tooltip: [3, 2, 4] // 表示维度 3、2、4 会在 tooltip 中显示。
        label: 3           // 表示 label 使用维度 3。
    },
    data: [
        // 每一列称为一个『维度』。
        // 这里分别是维度 0、1、2、3、4。
        [12, 44, 55, 66, 2],
        [23, 6, 16, 23, 1],
        ...
    ]
}

encode 支持的属性，根据坐标系不同而不同。对于直角坐标系（cartesian2d），支持 x、y。对于极坐标系（polar），支持 radius、angle。对于地理坐标系（geo），支持 lng，lat。此外，均支持 tooltip 和 label 和 itemName（用于指定 tooltip 中数据项名称）。

当使用 dimensions 给维度定义名称后，encode 中可直接引用名称，例如：

series: {
    type: 'xxx',
    dimensions: ['date', 'open', 'close', 'highest', 'lowest'],
    encode: {
        x: 'date',
        y: ['open', 'close', 'highest', 'lowest']
    },
    data: [ ... ]
}

data[i]

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

通常来说，数据用一个二维数组表示。如下，每一列被称为一个『维度』。

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]
    ]
}]

在直角坐标系 (grid) 中『维度X』和『维度Y』会默认对应于 xAxis 和 yAxis。
在极坐标系 (polar) 中『维度X』和『维度Y』会默认对应于 radiusAxis 和 angleAxis。
后面的其他维度是可选的，可以在别处被使用，例如：
- 在 visualMap 中可以将一个或多个维度映射到颜色，大小等多个图形属性上。
- 在 series.symbolSize 中可以使用回调函数，基于某个维度得到 symbolSize 值。
- 使用 tooltip.formatter 或 series.label.normal.formatter 可以把其他维度的值展示出来。

特别地，当只有一个轴为类目轴（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]]
}]

『值』与轴类型的关系：

当某维度对应于数值轴（axis.type 为 'value' 或者 'log'）的时候：
其值可以为 number（例如 12）。（也可以兼容 string 形式的 number，例如 '12'）

当某维度对应于类目轴（axis.type 为 'category'）的时候：
其值须为类目的『序数』（从 0 开始）或者类目的『字符串值』。例如：

xAxis: {
      type: 'category',
      data: ['星期一', '星期二', '星期三', '星期四']
  },
  yAxis: {
      type: 'category',
      data: ['a', 'b', 'm', 'n', 'p', 'q']
  },
  series: [{
      data: [
          // xAxis    yAxis
          [  0,        0,    2  ], // 意思是此点位于 xAxis: '星期一', yAxis: 'a'。
          [  '星期四',  2,    1  ], // 意思是此点位于 xAxis: '星期四', yAxis: 'm'。
          [  2,       'p',   2  ], // 意思是此点位于 xAxis: '星期三', yAxis: 'p'。
          [  3,        3,    5  ]
      ] }]

双类目轴的示例可以参考 Github Punchcard 示例。

当某维度对应于时间轴（type 为 'time'）的时候，值可以为：
- 一个时间戳，如 1484141700832，表示 UTC 时间。
- 或者字符串形式的时间描述：
  - ISO 8601 的子集，只包含这些形式（这几种格式，除非指明时区，否则均表示本地时间，与 moment 一致）：
    - 部分年月日时间: '2012-03', '2012-03-01', '2012-03-01 05', '2012-03-01 05:06'.
    - 使用 'T' 或空格分割: '2012-03-01T12:22:33.123', '2012-03-01 12:22:33.123'.
    - 时区设定: '2012-03-01T12:22:33Z', '2012-03-01T12:22:33+8000', '2012-03-01T12:22:33-05:00'.
  - 其他的时间字符串，包括（均表示本地时间）: '2012', '2012-3-1', '2012/3/1', '2012/03/01', '2009/6/12 2:00', '2009/6/12 2:05:08', '2009/6/12 2:05:08.123'
- 或者用户自行初始化的 Date 实例：
  - 注意，用户自行初始化 Date 实例的时候，浏览器的行为有差异，不同字符串的表示也不同。
  - 例如：在 chrome 中，new Date('2012-01-01') 表示 UTC 时间的 2012 年 1 月 1 日，而 new Date('2012-1-1') 和 new Date('2012/01/01') 表示本地时间的 2012 年 1 月 1 日。在 safari 中，不支持 new Date('2012-1-1')这种表示方法。
  - 所以，使用 new Date(dataString) 时，可使用第三方库解析（如 moment），或者使用 echarts.number.parseDate，或者参见这里。

当需要对个别数据进行个性化定义时：

数组项可用对象，其中的 value 像表示具体的数值，如：

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

空值：

当某数据不存在时（ps：不存在不代表值为 0），可以用 '-' 或者 null 或者 undefined 或者 NaN 表示。

例如，无数据在折线图中可表现为该点是断开的，在其它图中可表示为图形不存在。

zlevel

自定义图所有图形的 zlevel 值。

zlevel用于 Canvas 分层，不同zlevel值的图形会放置在不同的 Canvas 中，Canvas 分层是一种常见的优化手段。我们可以把一些图形变化频繁（例如有动画）的组件设置成一个单独的zlevel。需要注意的是过多的 Canvas 会引起内存开销的增大，在手机端上需要谨慎使用以防崩溃。

zlevel 大的 Canvas 会放在 zlevel 小的 Canvas 的上面。

自定义图组件的所有图形的z值，默认值为 2。控制图形的前后顺序。z值小的图形会被z值大的图形覆盖。

z相比zlevel优先级更低，而且不会创建新的 Canvas。

silent

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

animation

是否开启动画，默认为true。

animationThreshold

是否开启动画的阈值，默认值为 2000，当单个系列显示的图形数量大于这个阈值时会关闭动画。

animationDuration

初始动画的时长，默认为 1000，支持回调函数，可以通过每个数据返回不同的 delay 时间实现更戏剧的初始动画效果：

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

animationEasing

初始动画的缓动效果，默认为 cubicOut。

animationDelay

初始动画的延迟，支持回调函数，可以通过每个数据返回不同的 delay 时间实现更戏剧的初始动画效果。

如下示例：

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

animationDurationUpdate

数据更新动画的时长，默认时长为 300。

支持回调函数，可以通过每个数据返回不同的 delay 时间实现更戏剧的更新动画效果：

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

animationEasingUpdate

数据更新动画的缓动效果，默认效果为 cubicOut。

animationDelayUpdate

数据更新动画的延迟，支持回调函数，可以通过每个数据返回不同的 delay 时间实现更戏剧的更新动画效果。

如下示例：

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

上一节： ECharts图表自定义系列

下一节： ECharts自定义系列的渲染逻辑

"ECharts 入门教程"的目录

ECharts 入门教程 ECharts自定义系列属性

ECharts自定义系列属性