@agions/taroviz 1.11.1 → 2.0.3

package/src/hooks/useChartDownload.ts

@@ -2,8 +2,8 @@
  * useChartDownload - 图表下载 Hook
  * 支持下载图表为图片（PNG/JPEG/SVG/PDF）或原始数据（CSV/JSON）
  */
-import { useRef, useCallback } from 'react';
-import type { ChartInstance } from './index';
+import { useCallback, useRef } from 'react';
+import type { ChartInstance } from './types';
 import {
   generateFilename,
   downloadBlob,
@@ -114,7 +114,7 @@ export function useChartDownload(
       try {
         beforeExport(chart);
       } catch (e) {
-        console.warn('[useChartDownload] beforeExport error:', e);
+        console.error('[useChartDownload] beforeExport error:', e);
       }
     }
   }, [beforeExport]);
@@ -128,7 +128,7 @@ export function useChartDownload(
         try {
           afterExport(result);
         } catch (e) {
-          console.warn('[useChartDownload] afterExport error:', e);
+          console.error('[useChartDownload] afterExport error:', e);
         }
       }
     },
@@ -164,10 +164,9 @@ export function useChartDownload(
           });
         }
 
-        console.warn('[useChartDownload] getDataURL not supported');
         return undefined;
       } catch (e) {
-        console.warn('[useChartDownload] Failed to get image data URL:', e);
+        console.error('[useChartDownload] getImageDataUrl error:', e);
         return undefined;
       }
     },
@@ -183,7 +182,6 @@ export function useChartDownload(
 
       const chart = chartRef.current;
       if (!chart) {
-        console.warn('[useChartDownload] No chart instance available');
         return;
       }
 
@@ -219,10 +217,10 @@ export function useChartDownload(
           downloadDataUrl(dataUrl, `${name}.${fmt}`);
           executeAfterExport(dataUrl);
         } else {
-          console.warn('[useChartDownload] Failed to generate image data URL');
+          console.warn('[useChartDownload] No data URL available for format:', fmt);
         }
       } catch (e) {
-        console.warn('[useChartDownload] Failed to download image:', e);
+        console.error('[useChartDownload] downloadImage error:', e);
       }
     },
     [format, pixelRatio, backgroundColor, filename, executeBeforeExport, executeAfterExport]
@@ -238,7 +236,6 @@ export function useChartDownload(
 
       const chart = chartRef.current;
       if (!chart) {
-        console.warn('[useChartDownload] No chart instance available');
         return;
       }
 
@@ -261,7 +258,6 @@ export function useChartDownload(
         });
 
         if (!dataUrl) {
-          console.warn('[useChartDownload] Failed to get image data for PDF');
           return;
         }
 
@@ -273,7 +269,7 @@ export function useChartDownload(
           executeAfterExport(pdfDataUrl);
         }
       } catch (e) {
-        console.warn('[useChartDownload] Failed to download PDF:', e);
+        console.error('[useChartDownload] downloadPDF error:', e);
       }
     },
     [filename, pixelRatio, backgroundColor, executeBeforeExport, executeAfterExport]
@@ -289,7 +285,7 @@ export function useChartDownload(
     try {
       return chart.getOption?.() || null;
     } catch (e) {
-      console.warn('[useChartDownload] Failed to get chart data:', e);
+      console.error('[useChartDownload] getChartData error:', e);
       return null;
     }
   }, []);
@@ -304,7 +300,7 @@ export function useChartDownload(
     try {
       return chart.getSvgData?.();
     } catch (e) {
-      console.warn('[useChartDownload] Failed to get SVG data:', e);
+      console.error('[useChartDownload] getSvgData error:', e);
       return undefined;
     }
   }, []);
@@ -318,7 +314,6 @@ export function useChartDownload(
 
       const chart = chartRef.current;
       if (!chart) {
-        console.warn('[useChartDownload] No chart instance available');
         return;
       }
 
@@ -328,7 +323,6 @@ export function useChartDownload(
       try {
         const option = chart.getOption?.();
         if (!option) {
-          console.warn('[useChartDownload] No chart data available');
           return;
         }
 
@@ -342,12 +336,12 @@ export function useChartDownload(
         const csv = convertToCSV(data, { includeLabels });
 
         if (csv) {
-          const blob = csvToBlob(csv, `${name}.csv`);
+          const blob = csvToBlob(csv);
           downloadBlob(blob, `${name}.csv`);
           executeAfterExport(blob);
         }
       } catch (e) {
-        console.warn('[useChartDownload] Failed to download CSV:', e);
+        console.error('[useChartDownload] downloadCSV error:', e);
       }
     },
     [filename, executeBeforeExport, executeAfterExport]
@@ -362,7 +356,6 @@ export function useChartDownload(
 
       const chart = chartRef.current;
       if (!chart) {
-        console.warn('[useChartDownload] No chart instance available');
         return;
       }
 
@@ -372,7 +365,6 @@ export function useChartDownload(
       try {
         const option = chart.getOption?.();
         if (!option) {
-          console.warn('[useChartDownload] No chart data available');
           return;
         }
 
@@ -386,12 +378,12 @@ export function useChartDownload(
         const json = convertToJSON(data);
 
         if (json) {
-          const blob = jsonToBlob(json, `${name}.json`);
+          const blob = jsonToBlob(json);
           downloadBlob(blob, `${name}.json`);
           executeAfterExport(blob);
         }
       } catch (e) {
-        console.warn('[useChartDownload] Failed to download JSON:', e);
+        console.error('[useChartDownload] downloadJSON error:', e);
       }
     },
     [filename, executeBeforeExport, executeAfterExport]
@@ -414,16 +406,24 @@ export function useChartDownload(
       switch (fmt) {
         case 'png':
         case 'jpeg':
-          await downloadImage({ format: fmt, filename: exportFilename, pixelRatio: exportRatio, backgroundColor: exportBg });
+          await downloadImage({
+            format: fmt,
+            filename: exportFilename,
+            pixelRatio: exportRatio,
+            backgroundColor: exportBg,
+          });
           break;
         case 'svg':
           await downloadImage({ format: 'svg', filename: exportFilename });
           break;
         case 'pdf':
-          await downloadPDF({ filename: exportFilename, pixelRatio: exportRatio, backgroundColor: exportBg });
+          await downloadPDF({
+            filename: exportFilename,
+            pixelRatio: exportRatio,
+            backgroundColor: exportBg,
+          });
           break;
         default:
-          console.warn(`[useChartDownload] Unsupported format: ${fmt}`);
       }
     },
     [format, downloadImage, downloadPDF]
@@ -444,5 +444,3 @@ export function useChartDownload(
 // ============================================================================
 // 导出
 // ============================================================================
-
-export default useChartDownload;

package/src/hooks/useChartHistory.ts

@@ -9,7 +9,7 @@
  * - 暴露 canUndo / canRedo 状态
  */
 import { useEffect, useRef, useCallback, useState } from 'react';
-import type { ChartInstance } from './index';
+import type { ChartInstance } from './types';
 import type { EChartsOption } from 'echarts';
 
 // ============================================================================
@@ -53,11 +53,7 @@ export interface UseChartHistoryReturn {
 // ============================================================================
 
 /** 深度省略指定键后比较两个配置是否相等 */
-function omitAndCompare(
-  a: unknown,
-  b: unknown,
-  ignoreKeys: Set<string>
-): boolean {
+function omitAndCompare(a: unknown, b: unknown, ignoreKeys: Set<string>): boolean {
   if (a === b) return true;
   if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
     return a === b;
@@ -71,7 +67,7 @@ function omitAndCompare(
   if (aKeys.length !== bKeys.length) return false;
 
   for (const key of aKeys) {
-    if (!bObj.hasOwnProperty(key)) return false;
+    if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;
     if (!omitAndCompare(aObj[key], bObj[key], ignoreKeys)) return false;
   }
 
@@ -94,12 +90,7 @@ export function useChartHistory(
 ): UseChartHistoryReturn {
   const {
     maxHistorySize = 50,
-    ignoreKeys = [
-      'animation',
-      'animationDuration',
-      'animationEasing',
-      'animationFrame',
-    ],
+    ignoreKeys = ['animation', 'animationDuration', 'animationEasing', 'animationFrame'],
     enableKeyboard = true,
     clearOnUnmount = false,
   } = options;
@@ -120,58 +111,51 @@ export function useChartHistory(
   // 是否正在执行 undo/redo（避免 push 时重复记录）
   const isApplyingRef = useRef(false);
 
-  // 拦截 chart.setOption，记录历史
+  // Undo/Redo function holders — populated after function declarations via a deferred effect
+  const undoHolderRef = useRef<{ fn: (() => void) | null }>({ fn: null });
+  const redoHolderRef = useRef<{ fn: (() => void) | null }>({ fn: null });
+
+  // Deferred effect: bind undo/redo to refs once they are in scope
+  useEffect(() => {
+    undoHolderRef.current.fn = () => undo();
+    redoHolderRef.current.fn = () => redo();
+  });
+
   useEffect(() => {
     const chart = chartRef.current;
     if (!chart) return;
 
     const originalSetOption = chart.setOption.bind(chart);
 
-    chart.setOption = (
-      option: EChartsOption,
-      notMerge?: boolean,
-      lazyUpdate?: boolean
-    ) => {
-      // 如果正在执行 undo/redo，跳过历史记录
+    chart.setOption = (option: EChartsOption, notMerge?: boolean, lazyUpdate?: boolean) => {
       if (isApplyingRef.current) {
         return originalSetOption(option, notMerge, lazyUpdate);
       }
 
       const stack = historyStack.current;
       const idx = currentIndex;
-
-      // 如果当前索引不在栈顶，丢弃redo历史（类似 Git 行为）
       const newStack = idx < stack.length - 1 ? stack.slice(0, idx + 1) : [...stack];
 
-      // 检查是否与上一次配置相同（忽略动画字段）
       const lastOption = newStack[newStack.length - 1];
       if (lastOption && omitAndCompare(lastOption, option, ignoreKeySet.current)) {
-        // 配置没变，直接应用
         return originalSetOption(option, notMerge, lazyUpdate);
       }
 
-      // 入栈
       newStack.push(option);
-
-      // 裁剪超出 maxHistorySize
       if (newStack.length > maxHistorySize) {
         newStack.shift();
-      } else {
-        // 更新索引
-        setCurrentIndex(newStack.length - 1);
       }
-
       historyStack.current = newStack;
+      setCurrentIndex(newStack.length - 1);
       return originalSetOption(option, notMerge, lazyUpdate);
     };
 
     return () => {
-      // 恢复原始 setOption
       chart.setOption = originalSetOption;
     };
   }, [chartInstance, currentIndex, maxHistorySize]);
 
-  // 键盘快捷键：Ctrl+Z 撤销，Ctrl+Y / Ctrl+Shift+Z 重做
+  // Keyboard shortcuts
   useEffect(() => {
     if (!enableKeyboard) return;
 
@@ -181,16 +165,16 @@ export function useChartHistory(
 
       if (e.key === 'z' && !e.shiftKey) {
         e.preventDefault();
-        undo();
+        undoHolderRef.current.fn?.();
       } else if (e.key === 'y' || (e.key === 'z' && e.shiftKey)) {
         e.preventDefault();
-        redo();
+        redoHolderRef.current.fn?.();
       }
     };
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [enableKeyboard]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [enableKeyboard]);
 
   // 组件卸载时清空
   useEffect(() => {
@@ -213,7 +197,7 @@ export function useChartHistory(
     chart.setOption(historyStack.current[idx], true, true);
     isApplyingRef.current = false;
     setCurrentIndex(idx);
-  }, [currentIndex]);
+  }, [chartRef, currentIndex]);
 
   const redo = useCallback(() => {
     const chart = chartRef.current;
@@ -224,7 +208,7 @@ export function useChartHistory(
     chart.setOption(historyStack.current[idx], true, true);
     isApplyingRef.current = false;
     setCurrentIndex(idx);
-  }, [currentIndex]);
+  }, [chartRef, currentIndex]);
 
   const goTo = useCallback(
     (index: number) => {
@@ -241,16 +225,19 @@ export function useChartHistory(
     [currentIndex]
   );
 
-  const push = useCallback((option: EChartsOption) => {
-    const stack = historyStack.current;
-    const idx = currentIndex;
+  const push = useCallback(
+    (option: EChartsOption) => {
+      const stack = historyStack.current;
+      const idx = currentIndex;
 
-    const newStack = idx < stack.length - 1 ? stack.slice(0, idx + 1) : [...stack];
-    newStack.push(option);
-    if (newStack.length > maxHistorySize) newStack.shift();
-    historyStack.current = newStack;
-    setCurrentIndex(newStack.length - 1);
-  }, [currentIndex, maxHistorySize]);
+      const newStack = idx < stack.length - 1 ? stack.slice(0, idx + 1) : [...stack];
+      newStack.push(option);
+      if (newStack.length > maxHistorySize) newStack.shift();
+      historyStack.current = newStack;
+      setCurrentIndex(newStack.length - 1);
+    },
+    [currentIndex, maxHistorySize]
+  );
 
   const clear = useCallback(() => {
     historyStack.current = [];
@@ -269,5 +256,3 @@ export function useChartHistory(
     clear,
   };
 }
-
-export default useChartHistory;

package/src/hooks/useChartInit.ts

@@ -0,0 +1,59 @@
+/**
+ * useChartInit - 图表初始化 Hook
+ * 负责初始化 ECharts 图表实例
+ */
+import { useState, useEffect, useRef } from 'react';
+import { getAdapter } from '../adapters';
+import type { ChartInstance, ChartConfig } from './types';
+
+/**
+ * 使用图表 Hook
+ * @param chartRef 图表容器的引用
+ * @param config 图表配置
+ * @returns [图表实例, 设置实例函数, 是否已初始化]
+ */
+export function useChart(
+  chartRef: React.RefObject<HTMLElement>,
+  config?: ChartConfig
+): [ChartInstance | null, React.Dispatch<React.SetStateAction<ChartInstance | null>>, boolean] {
+  const [instance, setInstance] = useState<ChartInstance | null>(null);
+  const [initialized, setInitialized] = useState(false);
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  useEffect(() => {
+    if (!chartRef.current || instance) {
+      return;
+    }
+
+    const initAdapter = async () => {
+      try {
+        const adapter = await getAdapter(configRef.current || {});
+        const chartInstance = adapter as unknown as ChartInstance;
+        setInstance(chartInstance);
+        setInitialized(true);
+      } catch (error) {
+        console.error('Failed to initialize chart:', error);
+      }
+    };
+
+    initAdapter();
+
+    return () => {
+      if (instance) {
+        try {
+          const inst = instance as ChartInstance;
+          if (!inst.isDisposed?.()) {
+            inst.dispose();
+          }
+        } catch (e) {
+          console.warn('Failed to dispose chart instance:', e);
+        }
+        setInstance(null);
+        setInitialized(false);
+      }
+    };
+  }, [chartRef]);
+
+  return [instance, setInstance, initialized];
+}

package/src/hooks/useChartOptions.ts

@@ -0,0 +1,259 @@
+/**
+ * useChartOptions - 图表选项与工具相关 Hooks
+ * 提供图表选项设置、事件绑定、加载状态、响应式配置、全屏、导出、工具等
+ */
+import { useState, useEffect, useMemo, useCallback } from 'react';
+import type { EChartsOption } from 'echarts';
+import type { ChartInstance, EventHandler, LoadingOptions, Breakpoint } from './types';
+
+/**
+ * 设置图表选项 Hook
+ * @param instance 图表实例
+ * @param option 图表选项
+ * @param options 配置选项
+ */
+export function useOption(
+  instance: ChartInstance | null,
+  option: EChartsOption | null,
+  options?: {
+    /** 是否不合并 */
+    notMerge?: boolean;
+    /** 是否延迟更新 */
+    lazyUpdate?: boolean;
+    /** 是否在数据变化时替换 */
+    replaceMerge?: string[];
+    /** 依赖数组 */
+    deps?: unknown[];
+  }
+) {
+  const { notMerge = false, lazyUpdate = false, replaceMerge, deps = [] } = options || {};
+
+  useEffect(() => {
+    if (instance && option) {
+      try {
+        instance.setOption(option, notMerge, lazyUpdate);
+      } catch (e) {
+        console.warn('Failed to set chart option:', e);
+      }
+    }
+  }, [instance, option, notMerge, lazyUpdate, replaceMerge, ...deps]);
+}
+
+/**
+ * 图表事件 Hook
+ * @param instance 图表实例
+ * @param events 事件对象
+ */
+export function useEvents(instance: ChartInstance | null, events: Record<string, EventHandler>) {
+  useEffect(() => {
+    if (!instance || !events) {
+      return;
+    }
+
+    const eventEntries = Object.entries(events);
+
+    // 绑定事件
+    eventEntries.forEach(([eventName, handler]) => {
+      try {
+        instance.on(eventName, handler);
+      } catch (e) {
+        console.warn(`Failed to bind event ${eventName}:`, e);
+      }
+    });
+
+    // 清理事件
+    return () => {
+      eventEntries.forEach(([eventName, handler]) => {
+        try {
+          instance.off(eventName, handler);
+        } catch (e) {
+          console.warn(`Failed to unbind event ${eventName}:`, e);
+        }
+      });
+    };
+  }, [instance, events]);
+}
+
+/**
+ * 图表加载状态 Hook
+ * @param instance 图表实例
+ * @param loading 是否加载中
+ * @param options 加载选项
+ */
+export function useLoading(
+  instance: ChartInstance | null,
+  loading: boolean,
+  options?: LoadingOptions
+) {
+  useEffect(() => {
+    if (!instance) {
+      return;
+    }
+
+    try {
+      if (loading) {
+        instance.showLoading(options);
+      } else {
+        instance.hideLoading();
+      }
+    } catch (e) {
+      console.warn('Failed to set chart loading state:', e);
+    }
+  }, [instance, loading, options]);
+}
+
+/**
+ * 使用响应式图表配置
+ * @param config 响应式配置
+ * @returns 当前断点和配置
+ */
+export function useResponsive(config?: {
+  /** 断点配置 */
+  breakpoints?: Record<Breakpoint, number>;
+  /** 默认断点 */
+  defaultBreakpoint?: Breakpoint;
+}) {
+  const { breakpoints = { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 }, defaultBreakpoint = 'md' } =
+    config || {};
+
+  const [breakpoint, setBreakpoint] = useState<Breakpoint>(defaultBreakpoint);
+  const [windowSize, setWindowSize] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    const handleResize = () => {
+      const width = window.innerWidth;
+      setWindowSize({ width, height: window.innerHeight });
+
+      // 确定当前断点
+      let current: Breakpoint = 'xs';
+      if (width >= breakpoints.xl) current = 'xl';
+      else if (width >= breakpoints.lg) current = 'lg';
+      else if (width >= breakpoints.md) current = 'md';
+      else if (width >= breakpoints.sm) current = 'sm';
+
+      setBreakpoint(current);
+    };
+
+    handleResize();
+    window.addEventListener('resize', handleResize);
+
+    return () => window.removeEventListener('resize', handleResize);
+  }, [breakpoints]);
+
+  return { breakpoint, windowSize };
+}
+
+/**
+ * 使用图表全屏
+ * @param chartRef 图表容器引用
+ * @returns [是否全屏, 进入/退出全屏函数]
+ */
+export function useFullscreen(chartRef: React.RefObject<HTMLElement>) {
+  const [isFullscreen, setIsFullscreen] = useState(false);
+
+  const toggle = useCallback(() => {
+    if (!chartRef.current) return;
+
+    if (!isFullscreen) {
+      if (chartRef.current.requestFullscreen) {
+        chartRef.current.requestFullscreen();
+      }
+    } else {
+      if (document.exitFullscreen) {
+        document.exitFullscreen();
+      }
+    }
+  }, [chartRef, isFullscreen]);
+
+  useEffect(() => {
+    const handleChange = () => {
+      setIsFullscreen(!!document.fullscreenElement);
+    };
+
+    document.addEventListener('fullscreenchange', handleChange);
+    return () => document.removeEventListener('fullscreenchange', handleChange);
+  }, []);
+
+  return { isFullscreen, toggle };
+}
+
+/**
+ * 使用图表导出
+ * @param instance 图表实例
+ * @returns 导出函数
+ */
+export function useExport(instance: ChartInstance | null) {
+  const inst = instance as ChartInstance;
+  const exportImage = useCallback(
+    (options?: { type?: 'png' | 'jpeg'; pixelRatio?: number; backgroundColor?: string }) => {
+      if (!inst) return null;
+      const { type = 'png', pixelRatio = 2, backgroundColor } = options || {};
+      return inst.getDataURL?.({ type, pixelRatio, backgroundColor });
+    },
+    [inst]
+  );
+
+  const exportSVG = useCallback(() => {
+    if (!inst) return null;
+    return inst.getSvgData?.();
+  }, [inst]);
+
+  const exportCSV = useCallback(
+    (options?: { seriesIndex?: number; dimension?: number }) => {
+      if (!inst) return null;
+      return inst.getCompressedDataURL?.(options);
+    },
+    [inst]
+  );
+
+  return { exportImage, exportSVG, exportCSV };
+}
+
+/**
+ * 使用图表工具
+ * @param instance 图表实例
+ * @returns 工具函数
+ */
+export function useChartTools(instance: ChartInstance | null) {
+  const inst = instance as ChartInstance;
+  const getInstance = useCallback(() => instance, [instance]);
+
+  const clear = useCallback(() => {
+    inst?.clear?.();
+  }, [inst]);
+
+  const repaint = useCallback(() => {
+    inst?.resize?.();
+  }, [inst]);
+
+  const dispatchAction = useCallback(
+    (action: { type: string; [key: string]: unknown }) => {
+      inst?.dispatchAction?.(action);
+    },
+    [inst]
+  );
+
+  const showTip = useCallback(
+    (seriesIndex?: number, dataIndex?: number) => {
+      inst?.dispatchAction?.({ type: 'showTip', seriesIndex, dataIndex });
+    },
+    [inst]
+  );
+
+  const hideTip = useCallback(() => {
+    inst?.dispatchAction?.({ type: 'hideTip' });
+  }, [inst]);
+
+  const zoom = useCallback(
+    (start?: number, end?: number) => {
+      inst?.dispatchAction?.({
+        type: 'dataZoom',
+        start: start ?? 0,
+        end: end ?? 100,
+      });
+    },
+    [inst]
+  );
+
+  return { getInstance, clear, repaint, dispatchAction, showTip, hideTip, zoom };
+}