ECharts for React 使用指南

echarts-for-react 是一个简单而强大的 ECharts React 封装库。本指南基于项目中的 BaseChart 组件进行说明。

1. 核心概念

获取实例与生命周期

虽然 React 是声明式的，但有时我们需要直接操作 ECharts 实例（例如：导出图片、手动触发 tooltip、缩放等）。

• onChartReady: 图表初始化渲染完成后的回调。这是最主要的“生命周期钩子”。
• shouldSetOption: 控制图表是否需要重新渲染的钩子（性能优化）。

事件监听

通过 onEvents 属性，可以监听 ECharts 支持的所有事件。

2. API 详解

2.1 生命周期钩子

onChartReady(echartsInstance)

• 时机: 图表首次渲染完毕后触发。
• 参数: echartsInstance (ECharts 实例对象)。
• 用途: 绑定原生事件、执行一次性的初始化逻辑、保存实例引用。

const onChartReady = (instance) => {
  console.log("图表已就绪", instance);
  // 保存实例 ref
  chartRef.current = instance;
};

shouldSetOption(prevProps, nextProps)

• 时机: 组件 props 更新，准备调用 block setOption 之前。
• 返回值: boolean。返回 true 更新图表，false 阻止更新。
• 用途: 类似于 shouldComponentUpdate，用于阻止不必要的图表重绘，提升性能。

const shouldSetOption = (prevProps, nextProps) => {
  // 只有当 options 的 series 发生变化时才更新
  return (
    JSON.stringify(prevProps.option.series) !==
    JSON.stringify(nextProps.option.series)
  );
};

2.2 常用 Props

属性名	类型	默认值	说明
option	Object	required	ECharts 的配置对象
notMerge	Boolean	false	是否不跟之前设置的 option 进行合并
lazyUpdate	Boolean	false	在设置完 option 后是否不立即更新图表
theme	String/Object	null	主题，项目中默认为 'dark'
showLoading	Boolean	false	是否显示加载动画
onEvents	Object	-	事件绑定对象 { eventName: handler }
opts	Object	-	初始化附加参数 { renderer: 'canvas', locale: 'ZH', ... }

3. 完整使用示例

import React, { useRef, useState } from "react";
import BaseChart from "@/components/BaseChart";

const MyChartComponent = () => {
  const chartRef = useRef(null);
  const [loading, setLoading] = useState(false);

  // 1. 图表配置
  const option = {
    title: { text: "示例图表" },
    tooltip: {},
    xAxis: { data: ["A", "B", "C"] },
    yAxis: {},
    series: [{ type: "bar", data: [5, 20, 36] }],
  };

  // 2. 准备阶段钩子
  const handleChartReady = (instance) => {
    chartRef.current = instance;
    console.log("Chart instance saved");
  };

  // 3. 事件监听
  const handleEvents = {
    click: (params) => {
      console.log("点击了柱子:", params.name, params.value);
    },
    legendselectchanged: (params) => {
      console.log("图例切换:", params.selected);
    },
  };

  // 4. 性能优化钩子（可选）
  const handleShouldSetOption = (prevProps, nextProps) => {
    // 自定义判断逻辑，如果不写这个，默认每次 props 变都会更新
    return true;
  };

  return (
    <div style={{ height: "400px" }}>
      <BaseChart
        option={option}
        loading={loading}
        onChartReady={handleChartReady}
        onEvents={handleEvents}
        shouldSetOption={handleShouldSetOption}
      />

      <button
        onClick={() => {
          // 使用保存的实例调用原生方法
          if (chartRef.current) {
            const img = chartRef.current.getDataURL();
            console.log(img);
          }
        }}
      >
        导出图片
      </button>
    </div>
  );
};

export default MyChartComponent;

4. 部分导入echarts减小包大小

check the below links:

https://www.npmjs.com/package/echarts-for-react

https://git.hust.cc/echarts-for-react/