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": {...}"
在子目錄中添加了一些 package.json 檔案，這些檔案只包含 "type": "commonjs"。

這些更改意味著像 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 後為 1 KB，客戶端執行時在 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/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)。

餅圖和極座標系支援結束角度

結束角度配置項使我們可以製作不完整的餅圖，如半圓形。參見 (series-pie.endAngle)。

極座標系也支援結束角度，可以建立更多樣化的極座標圖。參見 (angleAxis.endAngle)。

新增 `min-max` 取樣方法

ECharts 的 sampling 配置項允許在資料量遠大於畫素數時為折線圖設定降取樣策略，這能有效最佳化圖表的繪製效率。在 5.5.0 版本中，我們新增了 min-max 取樣方法，它可以在保留資料整體趨勢的同時，更精確地顯示資料的極值。

新增阿拉伯語和荷蘭語兩種語言

在 5.5.0 版本中，我們新增了對阿拉伯語（AR）和荷蘭語（NL）兩種語言的支援。開發者可以透過 echarts.registerLocale 方法註冊新的語言包。

在之前的版本中，Tooltip 只能插入到圖表容器或 document.body 中。現在，您可以透過 tooltip.appendTo 指定容器，從而可以更靈活地控制提示框的位置。

座標軸上最大和最小標籤的對齊方式

在 5.5.0 版本中，我們新增了 axisLabel.alignMinLabel 和 axisLabel.alignMaxLabel 配置項，可以控制座標軸上最大和最小標籤的對齊方式。如果圖表的繪製區域較大，且不希望座標軸標籤溢位，可以將最大和最小標籤分別向右和向左對齊。

象形柱圖支援裁剪

象形柱圖可能會超出繪製區域。如果您想避免這種情況，可以透過 series-pictorialBar.clip 配置項進行裁剪。

為 Tooltip 的 `valueFormatter` 新增 `dataIndex` 引數

valueFormatter 可用於自定義提示框內容的值部分，現在新增了一個 dataIndex 引數，可用於獲取當前資料的索引。

完整更新日誌

檢視更新日誌

貢獻者在 GitHub 上編輯此頁

Ovilia plainheart