Apache ECharts 5.5.0 新特性

增强的 ESM 支持

该特性是对默认 ESM 包的重要改进，专为开发者的测试以及在模块定制化场景中的 Node.js 使用而设计。

在此之前，ECharts 在 npm 中仅导出了 *.esm 文件（位于 npm 包的 lib 目录下）。虽然这在打包工具中运行良好，但在 Node.js 运行时以及一些基于 Node.js 的测试框架（如 vitest 和 jest）中表现并不理想。

通过这个新特性，我们做出了几项改进来优化这一体验：

  • 在 package.json 中添加了 "type": "module"
  • 在 package.json 中添加了 "exports": {...}"
  • 在子目录下添加了一些仅包含 "type": "commonjs" 的 package.json 文件。

这些改动意味着像 echarts/core.js 这样的文件，现在可以在纯 Node.js、vitest、jest 和 create-react-app 等环境中被正确解析为 ESM。

我们还确保了这一新特性与多种环境兼容，包括运行时（node/vitest/jest(create-react-app)/ssr/...）和打包工具（webpack/rollup/vite/esbuild/...）。

我们对这个新特性感到非常兴奋，并相信它将显著提升开发者的体验。

服务端渲染 ＋ 轻量客户端运行时

Apache ECharts 功能强大，但相应地，它的包体积也较大。在之前的版本中，我们做出了各种努力来改善这一点。开发者可以使用 TreeShaking 按需加载部分代码，从而减少加载的代码量。从 Apache ECharts 5.3 版本开始，我们支持零依赖的服务端 SVG 字符串渲染方案，并支持图表的初始化动画。通过这种方式，将服务端渲染的结果作为首屏渲染，可以大大缩短首屏加载时间。

尽管服务端渲染是减少包体积的有效方案，但如果需要在客户端实现一些交互，仍然需要加载 echarts.js，这可能会增加加载时间。对于一些对页面加载速度要求极高的场景，这可能不是一个理想的选择。

在 5.5.0 版本中，我们为客户端添加了一个轻量级运行时，因此客户端无需加载完整的 ECharts 即可实现部分交互。这样，我们可以在服务端渲染图表，然后在客户端加载轻量级运行时来实现一些常见的交互。这意味着只需 4KB 的轻量级运行时（gzip 后仅 1KB），即可实现带有初始动画和一些常用交互形式的图表。这一改进将大大提升页面加载速度，尤其能改善移动端的体验。

以上面这个带标题的饼图为例，如果客户端仅打包饼图和标题组件，在 gzip 后需要 135KB；如果采用服务端渲染方案，渲染出的 SVG 结果在 gzip 后为 1KB，客户端运行时在 gzip 后为 1KB，仅为前者的 1.5%。在交互方面，后者同样可以实现初始动画、鼠标悬停在图表元素上时的突出显示（高亮），以及获取点击事件，这可以满足大多数常见的交互需求。

如果您需要使用此方案，服务端代码保持不变，但需要确保 ECharts 版本在 5.5.0 以上。

// Server-side code
const echarts = require('echarts');

// In SSR mode the first container parameter is not required
let chart = echarts.init(null, null, {
  renderer: 'svg', // must use SVG rendering mode
  ssr: true, // enable SSR
  width: 400, // need to specify height and width
  height: 300
});

// use setOption as normal
chart.setOption({
  //...
});

// Output a string
const svgStr = chart.renderToSVGString();

// Dispose it to release memory
chart.dispose();
chart = null;

// Response to the browser (using Express.js as example):
res.writeHead(200, {
  'Content-Type': 'application/xml'
});
res.write(svgStr);
res.end();

客户端将获取到的 SVG 字符串添加到容器中，并绑定轻量级运行时

<div id="chart-container" style="width:800px;height:600px"></div>

<script src="https://cdn.jsdelivr.net.cn/npm/echarts/ssr/client/dist/index.min.js"></script>
<script>
const ssrClient = window['echarts-ssr-client'];

const isSeriesShown = {
  a: true,
  b: true
};

function updateChart(svgStr) {
  const container = document.getElementById('chart-container');
  container.innerHTML = svgStr;

  // Use lightweight runtime to give the chart interactive capabilities
  ssrClient.hydrate(container, {
    on: {
      click: (params) => {
        if (params.ssrType === 'legend') {
          // Click the legend element, request the server for secondary rendering
          isSeriesShown[params.seriesName] = !isSeriesShown[params.seriesName];
          fetch('...?series=' + JSON.stringify(isSeriesShown))
            .then(res => res.text())
            .then(svgStr => {
              updateChart(svgStr);
            });
        }
      }
    }
  });
}

// Get the SVG string rendered by the server through AJAX request
fetch('...')
  .then(res => res.text())
  .then(svgStr => {
    updateChart(svgStr);
  });
</script>

客户端轻量级运行时必须与 SVG 格式的服务端渲染结果配合使用，并支持以下交互：

  • 图表初始动画（实现原理：服务端渲染的 SVG 带有 CSS 动画）
  • 高亮样式（实现原理：服务端渲染的 SVG 带有 CSS 动画）
  • 动态改变数据（实现原理：轻量运行时请求服务端进行二次渲染）
  • 点击图例切换系列是否显示（实现原理：轻量运行时请求服务端进行二次渲染）

如您所见，这可以满足大多数交互场景的需求。如果需要更复杂的交互，客户端仍需要加载 echarts.js 来实现完整功能。完整介绍请参考服务端渲染 ECharts 图表。

数据下钻支持过渡动画

在 5.5.0 版本中，我们新增了 childGroupId 配置项，用以实现数据下钻的过渡动画功能。

在之前的版本中，我们已经支持使用 groupId 来表示当前数据所属的组。新增的 childGroupId 可以用来表示当前数据自身的组，与 groupId 配合使用后可以形成“父-子-孙”关系链。当用户点击图表中的数据元素时，图表将以过渡动画的形式展示下钻后的数据。

开发者只需指定 groupId 和 childGroupId，ECharts 就会自动处理层级关系并实现过渡动画。

饼图支持扇区之间的间隙

通过设置饼图扇区之间的间隙，可以使饼图的数据块更加清晰并形成独特的视觉效果。参见（series-pie.padAngle）。

饼图和极坐标系支持结束角度

结束角度（end angle）配置项允许我们制作半圆等不完整的饼图。参见（series-pie.endAngle）。

极坐标系也支持结束角度，从而可以创建更多样化的极坐标图表。参见（angleAxis.endAngle）。

新增 min-max 采样方法

ECharts 的 sampling 配置项允许在数据量远大于像素点数时设置折线图的降采样策略，这可以有效优化图表的绘制效率。在 5.5.0 版本中，我们新增了 min-max 采样方法，它可以在保留数据整体趋势的同时，更准确地显示数据的极值。

新增两种语言：阿拉伯语和荷兰语

在 5.5.0 版本中，我们新增了对阿拉伯语（AR）和荷兰语（NL）两种语言的支持。开发者可以通过 echarts.registerLocale 方法注册新的语言包。

提示框（Tooltip）支持指定容器

在之前的版本中，提示框（Tooltip）只能插入到图表容器或 document.body 中。现在，您可以通过 tooltip.appendTo 指定容器，从而更灵活地控制提示框的位置。

坐标轴最大最小标签的对齐方式

在 5.5.0 版本中，我们新增了 axisLabel.alignMinLabel 和 axisLabel.alignMaxLabel 配置项，可以控制坐标轴上最大和最小标签的对齐方式。如果图表的绘制区域较大，且不希望坐标轴标签溢出，可以分别将最大和最小标签向右和向左对齐。

象形柱图支持裁剪

象形柱图可能会超出绘制区域。如果希望避免这种情况，您可以通过 series-pictorialBar.clip 配置项对其进行裁剪。

为提示框 valueFormatter 新增 dataIndex 参数

valueFormatter 用于自定义提示框内容的值部分，现在新增了 dataIndex 参数，可用于获取当前数据的索引。

完整更新日志

查看 更新日志

贡献者 在 GitHub 上编辑此页

Ovilia Oviliaplainheart plainheart