Apache ECharts 6 升級指南

本指南適用於希望從 echarts 5.x（以下簡稱 v5）升級到 echarts 6.x（以下簡稱 v6）的使用者。你可以在 ECharts 6 新特性 中瞭解 v6 帶來的新功能。在大多數情況下，開發者無需為此次升級做任何額外操作，因為 echarts 一直以來都致力於保持 API 的穩定和向後相容。但是，v6 確實引入了一些需要特別注意的破壞性改動。此外，在某些場景下，v6 提供了更好的 API 來替代之前的 API，這些被替代的 API 已不再推薦使用（當然，我們已儘量為這些改動保持了相容性）。我們將在本文件中詳細說明這些變化。

如何升級

您可以從官方下載頁面下載最新的原始碼和構建產物。如果您使用 npm，請透過以下方式升級：

npm install echarts@6

不相容改動

預設主題

首先，預設主題發生了變化。v6 在配色方案和主題設計上做了很多最佳化，以獲得更好的視覺效果。如果您想保留舊版本的顏色，可以使用 echarts/theme/v5.js 主題檔案，並像下面這樣初始化圖表：

import 'echarts/theme/v5';
const chart = echarts.init(document.getElementById('container'), 'v5');

請注意，v6 的新樣式不僅改變了主題顏色，還最佳化和調整了一些元件的預設位置和大小（例如，圖例的預設位置現在在畫布的底部）。使用 echarts/theme/v5.js 可以恢復之前元件的預設位置和大小。

如果您不介意其他變化，只想將預設調色盤恢復到 v5 的版本，您可以建立一個只定義 v5 預設顏色的主題：

const colorPaletteV5 = [
    '#5470c6',
    '#91cc75',
    '#fac858',
    '#ee6666',
    '#73c0de',
    '#3ba272',
    '#fc8452',
    '#9a60b4',
    '#ea7ccc'
];
echarts.registerTheme('myTheme', { color: colorPaletteV5 });
const chart = echarts.init(document.getElementById('container'), 'myTheme');

此外，v5 中的 echarts/src/theme/light.ts 檔案已移至 echarts/theme/rainbow.js。

標籤位置

在笛卡爾座標系（grid 元件）中，如果座標軸名稱（axisName）或標籤（axisLabel）之前超出了畫布或發生重疊，升級後坐標軸的位置可能會有輕微移動，因為防溢位和座標軸名稱/標籤防重疊功能現在預設是啟用的。在大多數情況下，這些變化幾乎不被察覺。但如果出現不合理的變動，您可以透過設定 grid.outerBoundsMode: 'none' 來停用防溢位，或透過設定 xAxis/yAxis.nameMoveOverlap: false 來停用防重疊。

富文字

在 v6 中，富文字標籤（label.rich / textStyle.rich）的以下樣式：fontStyle、fontWeight、fontSize、fontFamily、textShadowColor、textShadowBlur、textShadowOffsetX 和 textShadowOffsetY 將繼承自普通標籤（label / textStyle）中的同名樣式。要恢復舊的行為，您可以在 ECharts 配置項的根級別或在 label/textStyle 選項中設定 richInheritPlainLabel: false。

例如：

option = {
    richInheritPlainLabel: false, // Usually set here.
    xxx1: {
        // Or set here to only control this label.
        label: {
            richInheritPlainLabel: false,
            rich: {/* ... */},
        }
    },
    xxx2: {
        textStyle: {
            richInheritPlainLabel: false,
            rich: {/* ... */},
        }
    }
}