Apache ECharts 5 升级指南

本指南适用于希望从 echarts 4.x (以下简称 v4) 升级到 echarts 5.x (以下简称 v5) 的用户。您可以在 ECharts 5 的新特性 中了解 v5 带来的值得升级的新功能。在大多数情况下，开发人员无需为此升级做任何额外的事情，因为 echarts 一直在努力保持 API 的稳定性和向后兼容性。但是，v5 仍然带来了一些需要特别注意的重大更改。此外，在某些情况下，v5 提供了更好的 API 来替换之前的 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 仅提供 命名导出。

因此，如果您像这样导入 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 API

在 5.0.1 中，我们引入了新的 tree-shaking API

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]);

为了让您更容易知道根据您的选项需要导入哪些模块，我们的新示例页面添加了一个新功能来生成可 tree-shaking 的代码，您可以查看示例页面上的 完整代码 选项卡，以查看您需要引入的模块和相关代码。

在大多数情况下，我们建议尽可能使用新的 tree-shaking 接口，因为它最大化了打包工具 tree-shaking 的能力，并有效地解决了命名空间冲突并防止了内部结构的暴露。如果您仍然使用 CommonJS 方法编写模块，则仍然支持以前的方法

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

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

依赖项更改

注意：本节仅适用于使用 tree-shaking 接口以确保最小捆绑包大小的开发人员，不适用于导入整个包的开发人员。

为了保持捆绑包的大小足够小，我们删除了一些默认情况下会导入的依赖项。例如，如上所述，当使用新的按需接口时，默认情况下不再包含 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');

参考问题：#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。我们不再维护和升级以前的 VML 渲染器 以实现 IE8 兼容性。如果开发人员强烈需要 VML 渲染器，欢迎他们提交拉取请求以升级 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 组件 生成的视觉效果（即颜色、符号、symbolSize 等）具有最高优先级，它将覆盖 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 组件中：每个元素的声明。
      • 在 自定义系列 中：renderItem 返回值中每个元素的声明。
      • 直接使用 zrender 图形元素。
  • 图形元素上的文本相关属性已更改
    • 更改
      • 附加文本（或称为 rect 文本）的声明已更改。
        • 在除 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 => hight
        • textBackgroundColor => backgroundColor
        • textPadding => padding
        • textBorderColor => borderColor
        • textBorderWidth => borderWidth
        • textBorderRadius => borderRadius
        • textBoxShadowColor => shadowColor
        • textBoxShadowBlur => shadowBlur
        • textBoxShadowOffsetX => shadowOffsetX
        • textBoxShadowOffsetY => shadowOffsetY
      • 注意：以下属性未更改
        • textShadowColor
        • textShadowBlur
        • textShadowOffsetX
        • textShadowOffsetY
    • 它影响这些地方
      • 在 graphic 组件中：每个元素的声明。[兼容，但在某些复杂情况下不完全相同。]
      • 在 自定义系列 中：renderItem 返回值中每个元素的声明。[兼容，但在某些复杂情况下不完全相同]。
      • 直接使用 zrender API 创建图形元素。[不兼容，破坏性更改]。
  • 图表实例上的 API
    • chart.one(...) 已被弃用。
  • label:
    • 在属性 color、textBorderColor、backgroundColor 和 borderColor 中，值 'auto' 已被弃用。请改用值 'inherit'。
  • hoverAnimation:
    • 配置项 series.hoverAnimation 已被弃用。请改用 series.emphasis.scale。
  • 折线图系列:
    • 配置项 series.clipOverflow 已被弃用。请改用 series.clip。
  • 自定义系列:
    • 在 renderItem 中，api.style(...) 和 api.styleEmphasis(...) 已被弃用。因为它们并非真正必要，并且难以确保向后兼容。用户可以通过 api.visual(...) 获取系统指定的视觉效果。
  • 旭日图系列:
    • 操作类型 sunburstHighlight 已被弃用。请改用 highlight。
    • 操作类型 sunburstUnhighlight 已被弃用。请改用 downplay。
    • 配置项 series.downplay 已被弃用。请改用 series.blur。
    • 配置项 series.highlightPolicy 已被弃用。请改用 series.emphasis.focus。
  • 饼图系列:
    • 下面左侧的操作类型已被弃用。请改用右侧的操作类型
      • 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。
  • 地图系列:
    • 下面左侧的操作类型已被弃用。请改用右侧的操作类型
      • mapToggleSelect => toggleSelect
      • mapSelect => select
      • mapUnSelect => unselect
    • 下面左侧的事件类型已被弃用。请改用右侧的事件类型
      • mapselectchanged => selectchanged
      • mapselected => selected
      • mapunselected => unselected
    • 配置项 series.mapType 已被弃用。请改用 series.map。
    • 配置项 series.mapLocation 已被弃用。
  • 关系图系列:
    • 配置项 series.focusNodeAdjacency 已被弃用。请改用 series.emphasis: { focus: 'adjacency'}。
  • 仪表盘系列:
    • 配置项 series.clockWise 已被弃用。请改用 series.clockwise。
    • 配置项 series.hoverOffset 已被弃用。请改用 series.emphasis.scaleSize。
  • dataZoom 组件:
    • 如果使用 SVGPath，配置项 dataZoom.handleIcon 需要添加前缀 path://。
  • 雷达图:
    • 配置项 radar.name 已被弃用。请改用 radar.axisName。
    • 配置项 radar.nameGap 已被弃用。请改用 radar.axisNameGap。
  • 解析和格式化
    • echarts.format.formatTime 已被弃用。请改用 echarts.time.format。
    • echarts.number.parseDate 已被弃用。请改用 echarts.time.parse。
    • echarts.format.getTextRect 已被弃用。

贡献者 在 GitHub 上编辑此页面

plainheart plainheartOvilia Oviliafuchunhui fuchunhuipissang pissang