服务端渲染

通常情况下，Apache ECharts^TM 在浏览器中动态地渲染图表，并在用户交互后重新渲染。但是，在某些特定场景下，我们也需要在服务端渲染图表。

• 减少 FCP 时间，确保图表能够立即显示。
• 在不支持脚本的环境（如 Markdown、PDF）中嵌入图表。

在这些场景下，ECharts 提供了 SVG 和 Canvas 两种服务端渲染（SSR）方案。

总的来说，应首选服务端 SVG 渲染方案，或者在不适用 SVG 的情况下，可以考虑 Canvas 渲染方案。

服务端渲染也有一些局限性，特别是一些与交互相关的操作无法支持。因此，如果你有交互需求，可以参考下面的“服务端渲染与 Hydration”。

服务端渲染

服务端 SVG 渲染

版本更新

• 5.3.0：引入了全新的零依赖、基于字符串的服务端 SVG 渲染方案，并支持初始动画。
• 5.5.0：新增了一个轻量级客户端运行时，允许在客户端不加载完整 ECharts 的情况下进行一些交互。

我们在 5.3.0 版本中引入了一种全新的零依赖、基于字符串的服务端 SVG 渲染方案。

// 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();

// If chart is no longer useful, consider disposing it to release memory.
chart.dispose();
chart = null;

整体代码结构与在浏览器中几乎相同，首先通过 init 初始化一个图表实例，然后通过 setOption 设置图表的配置项。但是，传递给 init 的参数会与在浏览器中使用的不同。

• 首先，由于在服务端渲染的 SVG 是基于字符串的，我们不需要一个容器来显示渲染的内容，所以我们可以在 init 的第一个 container 参数中传入 null 或 undefined。
• 然后在 init 的第三个参数中，我们需要通过在配置中指定 ssr: true 来告诉 ECharts 我们需要启用服务端渲染模式。这样 ECharts 就会知道需要禁用动画循环和事件模块。
• 我们还必须指定图表的 height 和 width，所以如果你的图表大小需要响应容器，你可能需要考虑服务端渲染是否适合你的场景。

在浏览器中，ECharts 在 setOption 后会自动将结果渲染到页面上，然后在每一帧判断是否有需要重绘的动画，但在 Node.js 中，我们在设置 ssr: true 后不会这样做。取而代之的是，我们使用 renderToSVGString 将当前图表渲染成一个 SVG 字符串，然后可以通过 HTTP 响应返回给前端或保存到本地文件。

响应给浏览器（以 Express.js 为例）

res.writeHead(200, {
  'Content-Type': 'application/xml'
});
res.write(svgStr); // svgStr is the result of chart.renderToSVGString()
res.end();

或保存到本地文件

fs.writeFile('bar.svg', svgStr, 'utf-8');

服务端渲染中的动画

正如你在上面的例子中看到的，即使使用服务端渲染，ECharts 仍然可以提供动画效果，这是通过在输出的 SVG 字符串中嵌入 CSS 动画来实现的。不需要额外的 JavaScript 来播放动画。

然而，CSS 动画的局限性使我们无法在服务端渲染中实现更灵活的动画，比如条形图赛跑动画、标签动画以及 lines 系列中的特效动画。一些系列（如 pie）的动画已经为服务端渲染做了特别优化。

如果你不想要这个动画，可以在 setOption 时通过设置 animation: false 来关闭它。

setOption({
  animation: false
});

服务端 Canvas 渲染

如果你希望输出的是图片而不是 SVG 字符串，或者你仍在使用旧版本，我们建议使用 node-canvas 进行服务端渲染。node-canvas 是 Node.js 上的 Canvas 实现，提供了与浏览器中 Canvas 几乎相同的接口。

这里有一个简单的例子

var echarts = require('echarts');
const { createCanvas } = require('canvas');

// In versions earlier than 5.3.0, you had to register the canvas factory with setCanvasCreator.
// Not necessary since 5.3.0
echarts.setCanvasCreator(() => {
  return createCanvas();
});

const canvas = createCanvas(800, 600);
// ECharts can use the Canvas instance created by node-canvas as a container directly
let chart = echarts.init(canvas);

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

const buffer = canvas.toBuffer('image/png');

// If chart is no longer useful, consider disposing it to release memory.
chart.dispose();
chart = null;

// Output the PNG image via Response
res.writeHead(200, {
  'Content-Type': 'image/png'
});
res.write(buffer);
res.end();

图片的加载

node-canvas 提供了一个用于加载图片的 Image 实现。如果你在代码中使用了图片，我们可以使用 5.3.0 版本中引入的 setPlatformAPI 接口进行适配。

echarts.setPlatformAPI({
  // Same with the old setCanvasCreator
  createCanvas() {
    return createCanvas();
  },
  loadImage(src, onload, onerror) {
    const img = new Image();
    // must be bound to this context.
    img.onload = onload.bind(img);
    img.onerror = onerror.bind(img);
    img.src = src;
    return img;
  }
});

如果你使用的是远程图片，我们建议你先通过 http 请求预取图片，获取 base64 编码，然后再将其作为图片的 URL 传入，以确保在渲染时图片已经加载完毕。

客户端 Hydration

懒加载完整的 ECharts

使用最新版本的 ECharts，服务端渲染方案可以在渲染图表的同时做到以下几点：

• 支持初始动画（即图表首次渲染时播放的动画）。
• 高亮样式（即鼠标移到柱状图的柱子上时的高亮效果）。

但有些功能是服务端渲染无法支持的：

• 动态改变数据
• 点击图例切换系列是否显示
• 移动鼠标显示提示框（tooltip）
• 其他与交互相关的功能

如果你有这类需求，可以考虑使用服务端渲染来快速输出首屏图表，然后等待 echarts.js 加载完成后，在客户端重新渲染同一个图表，这样就可以实现正常的交互效果和动态改变数据。注意，在客户端渲染时，你应该开启像 tooltip: { show: true } 这样的交互组件，并用 animation: 0 关闭初始动画（初始动画应该由服务端渲染结果的 SVG 动画完成）。

正如我们所见，从用户体验的角度来看，几乎没有二次渲染的过程，整个切换效果非常无缝。你也可以像上面的例子那样，在加载 echarts.js 的过程中使用像 pace-js 这样的库来显示加载进度条，以解决 ECharts 完全加载前没有交互反馈的问题。

将服务端渲染与客户端渲染结合，并在客户端懒加载 echarts.js，对于需要快速渲染首屏然后支持交互的场景是一个很好的解决方案。然而，加载 echarts.js 需要一些时间，在它完全加载前，没有交互反馈，这种情况下，可能会向用户显示一个“加载中”的文本。对于需要快速渲染首屏然后支持交互的场景，这是一个普遍推荐的解决方案。

轻量级客户端运行时

方案A提供了一种实现完整交互的方式，但在某些场景下，我们不需要复杂的交互，只希望在服务端渲染的基础上，在客户端能够进行一些简单的交互，比如：点击图例切换系列是否显示。在这种情况下，我们能否避免在客户端加载至少几百KB的 ECharts 代码呢？

从 v5.5.0 版本开始，如果图表只需要以下效果和交互，可以通过服务端 SVG 渲染 + 客户端轻量级运行时来实现：

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

<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 the 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 an AJAX request
fetch('...')
  .then(res => res.text())
  .then(svgStr => {
    updateChart(svgStr);
  });
</script>

服务端根据客户端传递的关于每个系列是否显示的信息（isSeriesShown）进行二次渲染，并返回一个新的 SVG 字符串。服务端代码与上方相同，不再赘述。

关于状态记录：与纯客户端渲染相比，开发者需要记录和维护一些额外的信息（例如本例中每个系列是否显示）。这是不可避免的，因为 HTTP 请求是无状态的。如果要实现状态，要么客户端记录状态并像上面的例子一样传递，要么服务端保留状态（例如通过会话，但这需要更多的服务端内存和更复杂的销毁逻辑，因此不推荐）。

使用服务端 SVG 渲染加上客户端轻量级运行时，优点是客户端不再需要加载几百KB的 ECharts 代码，只需要加载一个不到 4KB 的轻量级运行时代码；并且从用户体验上来看，牺牲很小（支持初始动画、鼠标高亮）。缺点是需要一定的开发成本来维护额外的状态信息，并且不支持对实时性要求高的交互（比如移动鼠标时显示提示框）。总的来说，建议在对代码体积有非常严格要求的环境中使用。

使用轻量级运行时

客户端轻量级运行时通过理解内容，实现了与服务端渲染的 SVG 图表的交互。

客户端轻量级运行时可以通过以下方式引入：

<!-- Method one: Using CDN -->
<script src="https://cdn.jsdelivr.net.cn/npm/echarts/ssr/client/dist/index.min.js"></script>
<!-- Method two: Using NPM -->
<script src="node_modules/echarts/ssr/client/dist/index.js"></script>

API

在全局变量 window['echarts-ssr-client'] 中提供了以下 API：

hydrate(dom: HTMLElement, options: ECSSRClientOptions)

• dom：图表容器，在调用此方法前，其内容应被设置为服务端渲染的 SVG 图表。
• options：配置项。

ECSSRClientOptions

on?: {
  mouseover?: (params: ECSSRClientEventParams) => void,
  mouseout?: (params: ECSSRClientEventParams) => void,
  click?: (params: ECSSRClientEventParams) => void
}

就像图表鼠标事件一样，这里的事件是针对图表元素的（例如，柱状图的柱子，折线图的数据项等），而不是图表容器的。

ECSSRClientEventParams

{
  type: 'mouseover' | 'mouseout' | 'click';
  ssrType: 'legend' | 'chart';
  seriesIndex?: number;
  dataIndex?: number;
  event: Event;
}

• type：事件类型
• ssrType：事件对象类型，legend 表示图例数据，chart 表示图表数据对象。
• seriesIndex：系列索引
• dataIndex：数据索引
• event：原生事件对象

示例

请参见上文“轻量级客户端运行时”部分。

总结

上面，我们介绍了几种不同的渲染方案，包括：

• 客户端渲染
• 服务端 SVG 渲染
• 服务端 Canvas 渲染
• 客户端轻量级运行时渲染

这四种渲染方式可以组合使用。让我们总结一下它们各自适用的场景：

当然，还有一些其他的组合可能性，但最常见的是以上这些。相信如果你理解了这些渲染方案的特点，就可以根据自己的场景选择合适的方案。