README-zh_CN.md

echarts for react hook

English | 中文

在 react 中使用 echarts，使用函数式组件进行封装， 并提供 hook 供使用者消费。

有了echart-for-react，为什么还要编写该组件

echarts-for-react在组件上提供 setOption 相关的参数进行图表的更新，这让人感到不适、别扭。
echarts 内部的任何变化与 react 实际上是没有关系的，在props中保持使用静态的参数，通过 chart 实例进行图表更新是比较好的实现方式。
该组件的 props 仅用于对图表的初始化，任何图表的更新通过 ref 获取 echarts 的 instance 进行 setOption。通过内置的 useChart，用户无需考虑图表是否已经准备好，直接 setOption 即可，更新时机在 hook 里决定。

与 echart-for-react 的区别

1. 该组件使用 hook 编写，支持 16.8.0 之后 react。
2. 该组件仅在 echarts v5 中开发、使用，其他 echarts 版本兼容性未知。

hooks

useChart

使用方式：
见下方 例子。
用途：
通过内置的 useChart，用户无需考虑图表是否已经准备好，直接 setOption 即可，更新时机在 hook 里决定。

useTooltip

使用方式：
见下方 一个完整的例子。
用途：
让react接管echarts tooltip 内的渲染。

使用

简单的使用方式，使用内部提供的useChart，无需考虑任何时机，通过 ref 获取 echarts instance，直接 setOption ，渲染的时机让 hook 来考虑。或者 你提供 一个用于获取 echarts Instance 的 ref、echarts、onChartReady 函数，即可使用。

一个简单的例子。

import { useEffect } from 'react';

import * as echarts from 'echarts/core';
import { GridComponent } from 'echarts/components';
import { LineChart } from 'echarts/charts';
import { CanvasRenderer } from 'echarts/renderers';

import EChartsReact, { useChart } from 'echarts-for-react-fc';

echarts.use([GridComponent, LineChart, CanvasRenderer]);

const style = {
  width: '100%',
  height: 300,
};

const Simple = () => {
  const { chartRef, setChartOption, handleListenChartReady } = useChart();

  useEffect(() => {
    setChartOption({
      xAxis: {
        type: 'category',
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
      },
      yAxis: {
        type: 'value',
      },
      series: [
        {
          id: 1,
          data: [150, 230, 224, 218, 135, 147, 260],
          type: 'line',
        },
      ],
    });

    setTimeout(() => {
      setChartOption({
        series: [
          {
            id: 2,
            data: [400, 130, 224, 118, 35, 47, 260],
            type: 'line',
          },
        ],
      });
    }, 2000);
  }, []);

  return (
    <EChartsReact
      style={style}
      ref={chartRef}
      echarts={echarts}
      onChartReady={handleListenChartReady}
    />
  );
};

export default Simple;

一个完整的例子。

import { FC, useCallback, useEffect, useMemo, useState } from 'react';
import * as echarts from 'echarts/core';
import { GridComponent, TooltipComponent } from 'echarts/components';
import { LineChart } from 'echarts/charts';
import { UniversalTransition } from 'echarts/features';
import { CanvasRenderer, SVGRenderer } from 'echarts/renderers';

import EChartsReact, { useChart, useTooltip ,CreateTooltipFn } from 'echarts-for-react-fc';

echarts.use([
  GridComponent,
  TooltipComponent,
  LineChart,
  CanvasRenderer,
  SVGRenderer,
  UniversalTransition,
]);

const style = {
  width: '100%',
  height: 300,
};

const createTooltipFn: CreateTooltipFn = ({ params }) => {
  if (Array.isArray(params)) {
    return (
      <div>
        {params.map((item) => (
          <div>{item.name}</div>
        ))}
      </div>
    );
  } else {
    return <div>{params.name}</div>;
  }
};

const Complete: FC = () => {
  const { chartRef, setChartOption, handleListenChartReady } = useChart();

  const { tooltipDom, tooltipRender, createTooltip } = useTooltip({
    component: createTooltipFn,
  });

  const [renderer, setRenderer] = useState<'canvas' | 'svg'>('canvas');

  useEffect(() => {
    setChartOption({
      tooltip: {
        formatter: (params) => {
          setTimeout(() => {
            createTooltip({ params });
          }, 100);
          return tooltipDom;
        },
      },
      xAxis: {
        type: 'category',
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
      },
      yAxis: {
        type: 'value',
      },
      series: [
        {
          data: [150, 230, 224, 218, 135, 147, 260],
          type: 'line',
        },
      ],
    });
  }, []);

  const handleClickToggleRenderer = useCallback(() => {
    setRenderer((oldRenderer) => (oldRenderer === 'canvas' ? 'svg' : 'canvas'));
  }, []);

  const initOpts = useMemo(() => {
    return {
      renderer: renderer,
    };
  }, [renderer]);

  return (
    <>
      <p> now renderer: {renderer}</p>
      <button onClick={handleClickToggleRenderer}>toggle theme</button>
      <EChartsReact
        ref={chartRef}
        initOpts={initOpts}
        style={style}
        echarts={echarts}
        onChartReady={handleListenChartReady}
      ></EChartsReact>
      {tooltipRender}
    </>
  );
};

export default Complete;

参数

参数名	说明	类型	是否必填
echarts	echarts	typeof echarts	Y
theme	init fn 参数: 主题	string | object	N
initOpts	init fn 参数: 初始化配置	EChartsInitOpts	N
onChartReady	chart 准备事件	(ready: boolean) => void;	Y
onEvents	注册事件	Record<string, EChartsEventInfo | EChartsEventInfo[]>	N
autoResize	监听窗口，resize 图表	boolean | echarts.ResizeOpts	N
style	DOM style	CSSProperties	N
classname	DOM classname	string	N

提示

1. 请务必给图表设置尺寸。
2. 建议按照import * as echarts from "echarts/core";导出 echarts，按模块注册并使用。减少包的体积所需。

LICENSE

MIT@mmmml-zhao.

感谢

本组件参考 echarts-for-react，感谢该组件贡献者。