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: {/* ... */},
}
}
}