在Next.js中实现ApexCharts自定义侧边工具栏功能

核心问题排查 #

先确认chartRef是否正确获取了ApexCharts实例，Next.js的SSR/SSG特性可能导致ref绑定时机不对，函数组件里要特别注意useEffect的依赖配置。

正确实现步骤 #

1. 正确初始化chartRef #

通过useRef绑定图表组件，在渲染完成后获取原生ApexCharts实例：

import { useEffect, useRef, useState } from 'react';
import dynamic from 'next/dynamic';

// 避免SSR加载ApexCharts，防止客户端渲染异常
const ApexChart = dynamic(() => import('react-apexcharts'), { ssr: false });

const CustomChart = () => {
  const chartRef = useRef(null);
  const [chartInstance, setChartInstance] = useState(null);

  useEffect(() => {
    // 组件渲染完成后，从ref中提取原生图表实例
    if (chartRef.current) {
      setChartInstance(chartRef.current.chart);
    }
  }, []);

  // 放大功能
  const handleZoomIn = () => {
    chartInstance?.zoomIn();
  };

  // 缩小功能
  const handleZoomOut = () => {
    chartInstance?.zoomOut();
  };

  // 重置缩放
  const handleResetZoom = () => {
    chartInstance?.resetZoom();
  };

  const chartOptions = {
    // 禁用默认工具栏，避免功能冲突
    toolbar: {
      show: false
    },
    // 其他图表配置项
    xaxis: {
      type: 'datetime'
    }
  };

  const series = [/* 你的数据系列 */];

  return (
    <div className="flex">
      {/* 自定义侧边工具栏 */}
      <div className="side-toolbar flex flex-col gap-2 p-3 bg-gray-100">
        <button onClick={handleZoomIn} className="p-2 rounded">🔍 放大</button>
        <button onClick={handleZoomOut} className="p-2 rounded">🔍 缩小</button>
        <button onClick={handleResetZoom} className="p-2 rounded">↺ 重置</button>
      </div>
      <ApexChart ref={chartRef} options={chartOptions} series={series} type="line" width="100%" />
    </div>
  );
};

export default CustomChart;

2. 常见错误修正 #

• 默认工具栏冲突：必须在chartOptions里设置toolbar.show: false，避免默认工具栏和自定义工具栏的功能互斥。
• 实例获取时机错误：一定要在useEffect中获取实例，确保组件完全渲染后再操作，空依赖数组保证只执行一次初始化。
• 实例获取方式错误：react-apexcharts的ref不是直接指向原生实例，需要通过.chart属性提取。

3. 动态数据场景适配 #

如果图表数据是动态更新的，需要在数据变化时重新获取实例，将series加入useEffect的依赖数组：

useEffect(() => {
  if (chartRef.current) {
    setChartInstance(chartRef.current.chart);
  }
}, [series]);

内容的提问来源于stack exchange，提问作者Ammar Mohib