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 上編輯此頁

plainheart Ovilia fuchunhui pissang