Apache ECharts 5 升级指南

本指南适用于希望从 ECharts 4.x（下文简称 v4）升级到 ECharts 5.x（下文简称 v5）的用户。你可以在 ECharts 5 新特性中了解 v5 带来了哪些值得升级的新功能。在大多数情况下，开发者无需为此次升级做任何额外操作，因为 ECharts 一直以来都尽可能地保持 API 的稳定和向后兼容。但是，v5 仍然带来了一些需要特别注意的破坏性改动。此外，在某些情况下，v5 提供了更好的 API 来替代旧有的实现，这些被取代的 API 将不再被推荐使用（尽管我们已尽力对这些改动保持兼容）。我们将在此文档中详细解释这些变化。

不兼容改动

默认主题

首先，默认主题已发生改变。v5 在主题设计上做了大量的改动和优化。如果你仍想保留旧版本的颜色，可以手动声明颜色，如下所示：

chart.setOption({
  color: [
    '#c23531',
    '#2f4554',
    '#61a0a8',
    '#d48265',
    '#91c7ae',
    '#749f83',
    '#ca8622',
    '#bda29a',
    '#6e7074',
    '#546570',
    '#c4ccd3'
  ]
  // ...
});

或者，制作一个简单的 v4 主题：

var themeEC4 = {
  color: [
    '#c23531',
    '#2f4554',
    '#61a0a8',
    '#d48265',
    '#91c7ae',
    '#749f83',
    '#ca8622',
    '#bda29a',
    '#6e7074',
    '#546570',
    '#c4ccd3'
  ]
};
var chart = echarts.init(dom, themeEC4);
chart.setOption(/* ... */);

引入 ECharts

移除对默认导出的支持

自 v5 起，ECharts 仅提供 命名导出（named exports）。

因此，如果你之前是这样引入 echarts 的：

import echarts from 'echarts';
// Or import core module
import echarts from 'echarts/lib/echarts';

在 v5 中将会报错。你需要修改代码以导入整个模块，如下所示：

import * as echarts from 'echarts';
// Or
import * as echarts from 'echarts/lib/echarts';

摇树优化（Tree-shaking）接口

在 5.0.1 版本中，我们引入了新的 摇树优化接口。

import * as echarts from 'echarts/core';
import { BarChart } from 'echarts/charts';
import { GridComponent } from 'echarts/components';
// Note that the Canvas renderer is no longer included by default and needs to be imported explictly, or import the SVGRenderer if you need to use the SVG rendering mode
import { CanvasRenderer } from 'echarts/renderers';

echarts.use([BarChart, GridComponent, CanvasRenderer]);

为了让你能更方便地根据你的 option 配置了解需要引入哪些模块，我们的新版示例页面增加了一个新功能，可以生成支持摇树优化的代码。你可以在示例页面的“完整代码”标签页中查看需要引入的模块及相关代码。

在大多数情况下，我们建议尽可能使用新的摇树优化接口，因为它能最大限度地发挥打包工具的摇树优化功能，并有效解决命名空间冲突，避免内部结构的暴露。如果你仍在使用 CommonJS 方式编写模块，之前的引入方式仍然支持。

const echarts = require('echarts/lib/echarts');
require('echarts/lib/chart/bar');
require('echarts/lib/component/grid');

其次，由于我们的源代码已使用 TypeScript 重写，v5 将不再支持从 echarts/src 导入文件。你需要将其更改为从 echarts/lib 导入。

依赖项变更

注意：本节仅适用于使用摇树优化接口以确保最小打包体积的开发者，不适用于全量引入包的用户。

为了保持打包体积足够小，我们移除了一些原先默认引入的依赖项。例如，如上所述，使用新的按需引入接口时，CanvasRenderer 不再默认包含，这确保了在仅使用 SVG 渲染模式时不会引入不必要的 Canvas 渲染代码。此外，以下依赖项也进行了调整：

  • 在使用折线图和柱状图时，直角坐标系组件不再默认引入。因此，之前使用以下引入方式的代码：
const echarts = require('echarts/lib/echarts');
require('echarts/lib/chart/bar');
require('echarts/lib/chart/line');

需要再次单独引入 grid 组件：

require('echarts/lib/component/grid');

相关 issue：#14080, #13764

  • aria 组件不再默认引入。如有需要，你必须手动引入。
import { AriaComponent } from 'echarts/components';
echarts.use(AriaComponent);

或

require('echarts/lib/component/aria');

内置 GeoJSON 移除

v5 移除了内置的 geoJSON（之前位于 echarts/map 文件夹中）。这些 geoJSON 文件一直以来都来源于第三方。如果用户仍需要它们，可以从旧版本中获取，或者寻找更合适的数据并通过 registerMap 接口注册到 ECharts 中。

浏览器兼容性

v5 不再支持 IE8。我们不再维护和升级之前用于 IE8 兼容的 VML 渲染器。如果开发者对 VML 渲染器有强烈需求，欢迎提交 Pull Request 来升级 VML 渲染器，或维护一个独立的第三方 VML 渲染器，因为从 v5.0.1 开始我们支持注册独立的渲染器。

配置项调整

Y 轴（数值轴）的轴线和刻度默认隐藏

自 v5 起，Y 轴（value 轴）的轴线和轴刻度线默认隐藏。如果你偏好之前的样式，需要显式配置如下：

yAxis: {
  type: 'value',
  // explicitly set `axisLine.show` & `axisTick.show` as `true`
  axisLine: {
    show: true
  },
  axisTick: {
    show: true
  }
}

视觉样式设置优先级变更

自 v5 起，visualMap 组件与 itemStyle | lineStyle | areaStyle 之间的视觉效果优先级被反转。

也就是说，在之前的 v4 中，由 visualMap 组件生成的视觉效果（即颜色、图形、符号大小等）具有最高优先级，会覆盖在 itemStyle | lineStyle | areaStyle 中的相同视觉设置。这在使用 visualMap 组件的同时需要为某些特定数据项指定样式时带来了麻烦。自 v5 起，在 itemStyle | lineStyle | areaStyle 中指定的视觉效果具有最高优先级。

在大多数情况下，用户从 v4 迁移到 v5 时可能不会注意到这一变化。但用户仍可以检查是否同时指定了 visualMap 组件和 itemStyle | lineStyle | areaStyle。

富文本的 padding

v5 调整了 rich.?.padding，使其更符合 CSS 规范。在 v4 中，例如 rich. .padding: [11, 22, 33, 44] 表示 padding-top 是 33，padding-bottom 是 11。在 v5 中，上下位置进行了调整，rich. .padding: [11, 22, 33, 44] 表示 padding-top 是 11，padding-bottom 是 33。

如果用户正在使用 rich.?.padding，需要调整这个顺序。

扩展

以下扩展需要升级到新版本以支持 ECharts v5：

废弃的 API

自 v5 起，一些 API 和 ECharts 配置项已被废弃，但仍然向后兼容。用户可以**继续使用这些废弃的 API**，仅在开发模式下会在控制台打印一些警告。但如果用户有空余时间，从长远维护的角度考虑，建议升级到新的 API。

废弃的 API 及其对应的新 API 列表如下：

  • 图形元素的变换相关属性发生变化
    • 变化
      • position: [number, number] 更改为 x: number/y: number。
      • scale: [number, number] 更改为 scaleX: number/scaleY: number。
      • origin: [number, number] 更改为 originX: number/originY: number。
    • position、scale 和 origin 仍然支持，但已被废弃。
    • 这会影响以下地方：
      • 在 graphic 组件中：每个元素的声明。
      • 在 custom series（自定义系列）中：renderItem 返回值中每个元素的声明。
      • 直接使用 zrender 图形元素。
  • 图形元素上与文本相关的属性发生变化
    • 变化
      • 附加文本（或称矩形文本）的声明发生了变化。
        • 除 Text 元素外，style.text 属性被废弃。取而代之的是，提供了 textContent 和 textConfig 属性集以支持更强大的功能。
        • 以下左侧的相关属性已被废弃。请使用右侧的属性代替。
          • textPosition => textConfig.position
          • textOffset => textConfig.offset
          • textRotation => textConfig.rotation
          • textDistance => textConfig.distance
      • 以下左侧在 style 和 style.rich.? 中的属性已被废弃。请使用右侧的属性代替。
        • textFill => fill
        • textStroke => stroke
        • textFont => font
        • textStrokeWidth => lineWidth
        • textAlign => align
        • textVerticalAlign => verticalAlign
        • textLineHeight => lineHeight
        • textWidth => width
        • textHeight => height
        • textBackgroundColor => backgroundColor
        • textPadding => padding
        • textBorderColor => borderColor
        • textBorderWidth => borderWidth
        • textBorderRadius => borderRadius
        • textBoxShadowColor => shadowColor
        • textBoxShadowBlur => shadowBlur
        • textBoxShadowOffsetX => shadowOffsetX
        • textBoxShadowOffsetY => shadowOffsetY
      • 注意：这些属性没有改变
        • textShadowColor
        • textShadowBlur
        • textShadowOffsetX
        • textShadowOffsetY
    • 这会影响以下地方：
      • 在 graphic 组件中：每个元素的声明。[兼容，但在某些复杂情况下不完全相同。]
      • 在 custom series（自定义系列）中：renderItem 返回值中每个元素的声明。[兼容，但在某些复杂情况下不完全相同。]
      • 直接使用 zrender API 创建图形元素。[不兼容，破坏性变更。]
  • 图表实例上的 API
    • chart.one(...) 已被废弃。
  • label:
    • 在属性 color、textBorderColor、backgroundColor 和 borderColor 中，值 'auto' 已被废弃。请使用值 'inherit' 代替。
  • hoverAnimation:
    • 配置项 series.hoverAnimation 已被废弃。请使用 series.emphasis.scale 代替。
  • line 系列:
    • 配置项 series.clipOverflow 已被废弃。请使用 series.clip 代替。
  • custom 系列:
    • 在 renderItem 中，api.style(...) 和 api.styleEmphasis(...) 已被废弃。因为它们并非真正必要，且难以保证向后兼容。用户可以通过 api.visual(...) 获取系统指定的视觉元素。
  • sunburst 系列:
    • Action 类型 sunburstHighlight 已被废弃。请使用 highlight 代替。
    • Action 类型 sunburstUnhighlight 已被废弃。请使用 downplay 代替。
    • 配置项 series.downplay 已被废弃。请使用 series.blur 代替。
    • 配置项 series.highlightPolicy 已被废弃。请使用 series.emphasis.focus 代替。
  • pie 系列:
    • 以下左侧的 Action 类型已被废弃。请使用右侧的代替：
      • pieToggleSelect => toggleSelect
      • pieSelect => select
      • pieUnSelect => unselect
    • 以下左侧的事件类型已被废弃。请使用右侧的代替：
      • pieselectchanged => selectchanged
      • pieselected => selected
      • pieunselected => unselected
    • 配置项 series.label.margin 已被废弃。请使用 series.label.edgeDistance 代替。
    • 配置项 series.clockWise 已被废弃。请使用 series.clockwise 代替。
    • 配置项 series.hoverOffset 已被废弃。请使用 series.emphasis.scaleSize 代替。
  • map 系列:
    • 以下左侧的 Action 类型已被废弃。请使用右侧的代替：
      • mapToggleSelect => toggleSelect
      • mapSelect => select
      • mapUnSelect => unselect
    • 以下左侧的事件类型已被废弃。请使用右侧的代替：
      • mapselectchanged => selectchanged
      • mapselected => selected
      • mapunselected => unselected
    • 配置项 series.mapType 已被废弃。请使用 series.map 代替。
    • 配置项 series.mapLocation 已被废弃。
  • graph 系列:
    • 配置项 series.focusNodeAdjacency 已被废弃。请使用 series.emphasis: { focus: 'adjacency'} 代替。
  • gauge 系列:
    • 配置项 series.clockWise 已被废弃。请使用 series.clockwise 代替。
    • 配置项 series.hoverOffset 已被废弃。请使用 series.emphasis.scaleSize 代替。
  • dataZoom 组件:
    • 如果使用 SVGPath，配置项 dataZoom.handleIcon 需要加上前缀 path://。
  • radar:
    • 配置项 radar.name 已被废弃。请使用 radar.axisName 代替。
    • 配置项 radar.nameGap 已被废弃。请使用 radar.axisNameGap 代替。
  • 解析与格式化
    • echarts.format.formatTime 已被废弃。请使用 echarts.time.format 代替。
    • echarts.number.parseDate 已被废弃。请使用 echarts.time.parse 代替。
    • echarts.format.getTextRect 已被废弃。

贡献者 在 GitHub 上编辑此页

plainheartOviliafuchunhuipissang