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 僅提供 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 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-shakable 程式碼，您可以在範例頁面上查看「完整程式碼」標籤，以查看需要引入的模組和相關程式碼。

在大多數情況下，我們建議盡可能使用新的 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 渲染器，歡迎提交 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 => hight
        • 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:
    • 選項 series.clipOverflow 已被棄用。請改用 series.clip。
  • custom series:
    • 在 renderItem 中，api.style(...) 和 api.styleEmphasis(...) 已被棄用。因為它並非真的必要，且難以確保向後相容性。使用者可以使用 api.visual(...) 來取得系統指定的視覺效果。
  • sunburst series:
    • 動作類型 sunburstHighlight 已被棄用。請改用 highlight。
    • 動作類型 sunburstUnhighlight 已被棄用。請改用 downplay。
    • 選項 series.downplay 已被棄用。請改用 series.blur。
    • 選項 series.highlightPolicy 已被棄用。請改用 series.emphasis.focus。
  • pie series:
    • 下方左側的動作類型已被棄用。請改用右側的類型。
      • 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 series:
    • 下方左側的動作類型已被棄用。請改用右側的類型。
      • mapToggleSelect => toggleSelect
      • mapSelect => select
      • mapUnSelect => unselect
    • 下方左側的事件類型已被棄用。請改用右側的類型。
      • mapselectchanged => selectchanged
      • mapselected => selected
      • mapunselected => unselected
    • 選項 series.mapType 已被棄用。請改用 series.map。
    • 選項 series.mapLocation 已被棄用。
  • graph series:
    • 選項 series.focusNodeAdjacency 已被棄用。請改用 series.emphasis: { focus: 'adjacency'}。
  • gauge series:
    • 選項 series.clockWise 已被棄用。請改用 series.clockwise。
    • 選項 series.hoverOffset 已被棄用。請改用 series.emphasis.scaleSize。
  • dataZoom 元件:
    • 選項 dataZoom.handleIcon 如果使用 SVGPath，則需要加上前綴 path://。
  • radar:
    • 選項 radar.name 已被棄用。請改用 radar.axisName。
    • 選項 radar.nameGap 已被棄用。請改用 radar.axisNameGap。
  • Parse 和 format
    • echarts.format.formatTime 已被棄用。請改用 echarts.time.format。
    • echarts.number.parseDate 已被棄用。請改用 echarts.time.parse。
    • echarts.format.getTextRect 已被棄用。

貢獻者 在 GitHub 上編輯此頁面

plainheart plainheartOvilia Oviliafuchunhui fuchunhuipissang pissang