Apache ECharts 6 升级指南

本指南适用于希望从 echarts 5.x（以下简称 v5）升级到 echarts 6.x（以下简称 v6）的用户。您可以在 ECharts 6 新特性 中了解 v6 带来的新特性。在大多数情况下，开发者不需要为这次升级做任何额外的工作，因为 echarts 一直试图保持 API 的稳定和向后兼容。然而，v6 确实引入了一些需要特别注意的破坏性变更（breaking changes）。此外，在某些情况下，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: {/* ... */},
        }
    }
}