@agions/taroviz 1.9.0 → 1.11.1

package/src/hooks/useChartDownload.ts

@@ -4,6 +4,16 @@
  */
 import { useRef, useCallback } from 'react';
 import type { ChartInstance } from './index';
+import {
+  generateFilename,
+  downloadBlob,
+  downloadDataUrl,
+  csvToBlob,
+  jsonToBlob,
+  convertToCSV,
+  convertToJSON,
+  createPdfFromImage,
+} from './utils/chartDownloadUtils';
 
 // ============================================================================
 // 类型定义
@@ -60,198 +70,13 @@ export interface UseChartDownloadReturn {
   /** 获取图片 DataURL */
   getImageDataUrl: (format?: 'png' | 'jpeg' | 'svg') => string | undefined;
   /** 获取图表数据 */
-  getChartData: () => any;
+  getChartData: () => unknown;
   /** 获取 SVG 数据 */
   getSvgData: () => string | undefined;
   /** 直接导出（自动选择格式） */
   exportChart: (options?: Partial<UseChartDownloadOptions>) => Promise<void>;
 }
 
-// ============================================================================
-// 工具函数
-// ============================================================================
-
-/**
- * 生成默认文件名
- */
-function generateFilename(prefix: string = 'chart'): string {
-  const timestamp = new Date().toISOString().slice(0, 19).replace(/[:-]/g, '');
-  return `${prefix}_${timestamp}`;
-}
-
-/**
- * 下载 Blob 对象
- */
-function downloadBlob(blob: Blob, filename: string): void {
-  const url = URL.createObjectURL(blob);
-  const link = document.createElement('a');
-  link.href = url;
-  link.download = filename;
-  document.body.appendChild(link);
-  link.click();
-  document.body.removeChild(link);
-  URL.revokeObjectURL(url);
-}
-
-/**
- * 下载数据 URL
- */
-function downloadDataUrl(dataUrl: string, filename: string): void {
-  const link = document.createElement('a');
-  link.href = dataUrl;
-  link.download = filename;
-  document.body.appendChild(link);
-  link.click();
-  document.body.removeChild(link);
-}
-
-/**
- * CSV 转 Blob
- */
-function csvToBlob(csv: string, filename: string): Blob {
-  return new Blob([csv], { type: 'text/csv;charset=utf-8;' });
-}
-
-/**
- * JSON 转 Blob
- */
-function jsonToBlob(json: string, filename: string): Blob {
-  return new Blob([json], { type: 'application/json;charset=utf-8;' });
-}
-
-/**
- * 将数据转换为 CSV 格式
- */
-function convertToCSV(data: any, options?: { includeLabels?: boolean }): string {
-  if (!data) return '';
-
-  // 处理 ECharts 格式的数据
-  if (data.series) {
-    return convertSeriesToCSV(data, options);
-  }
-
-  // 处理数组数据
-  if (Array.isArray(data)) {
-    return convertArrayToCSV(data);
-  }
-
-  // 处理普通对象
-  if (typeof data === 'object') {
-    return convertObjectToCSV(data);
-  }
-
-  return String(data);
-}
-
-/**
- * 将 ECharts series 数据转换为 CSV
- */
-function convertSeriesToCSV(chartData: any, options?: { includeLabels?: boolean }): string {
-  const { series = [], xAxis, dataset } = chartData;
-  const includeLabels = options?.includeLabels ?? true;
-
-  if (series.length === 0) return '';
-
-  // 获取类别轴数据
-  let categories: any[] = [];
-  if (xAxis?.data) {
-    categories = xAxis.data;
-  } else if (dataset?.dimensions && dataset.source) {
-    categories = dataset.source.map((row: any[]) => row[0]);
-  } else if (series[0]?.data) {
-    categories = series[0].data.map((item: any, index: number) =>
-      typeof item === 'object' ? item[0] || index : index
-    );
-  }
-
-  // 构建 CSV 头
-  const headers = includeLabels ? ['Category', ...series.map((s: any) => s.name || s.seriesIndex)] : [];
-
-  // 构建 CSV 行
-  const rows: string[][] = [];
-
-  series.forEach((s: any, seriesIndex: number) => {
-    const seriesData = s.data || [];
-    seriesData.forEach((item: any, dataIndex: number) => {
-      const value = typeof item === 'object' ? item[1] : item;
-      const category = categories[dataIndex] || dataIndex;
-
-      if (includeLabels) {
-        if (seriesIndex === 0) {
-          rows[dataIndex] = [category, value];
-        } else {
-          rows[dataIndex] = rows[dataIndex] || [category];
-          rows[dataIndex].push(value);
-        }
-      } else {
-        if (seriesIndex === 0) {
-          rows[dataIndex] = [value];
-        } else {
-          rows[dataIndex] = rows[dataIndex] || [];
-          rows[dataIndex].push(value);
-        }
-      }
-    });
-  });
-
-  // 生成 CSV 字符串
-  const csvRows = includeLabels
-    ? [headers.join(','), ...rows.map((row) => row.join(','))]
-    : rows.map((row) => row.join(','));
-
-  return csvRows.join('\n');
-}
-
-/**
- * 将数组数据转换为 CSV
- */
-function convertArrayToCSV(data: any[]): string {
-  if (data.length === 0) return '';
-
-  // 检查是否为对象数组
-  if (typeof data[0] === 'object' && data[0] !== null) {
-    const keys = Object.keys(data[0]);
-    const headers = keys.join(',');
-    const rows = data.map((item) => keys.map((key) => JSON.stringify(item[key] ?? '')).join(','));
-    return [headers, ...rows].join('\n');
-  }
-
-  // 简单数组
-  return data.join('\n');
-}
-
-/**
- * 将对象数据转换为 CSV
- */
-function convertObjectToCSV(data: Record<string, any>): string {
-  const entries = Object.entries(data);
-  return entries.map(([key, value]) => `${key},${JSON.stringify(value)}`).join('\n');
-}
-
-/**
- * 将 ECharts 数据转换为 JSON
- */
-function convertToJSON(data: any): string {
-  if (!data) return '{}';
-
-  // 如果是 ECharts 格式，简化数据
-  if (data.series) {
-    const simplified: any = {
-      title: data.title?.text,
-      legend: data.legend?.data,
-      xAxis: data.xAxis?.data,
-      series: data.series.map((s: any) => ({
-        name: s.name,
-        type: s.type,
-        data: s.data?.map((item: any) => (typeof item === 'object' ? item[1] : item)),
-      })),
-    };
-    return JSON.stringify(simplified, null, 2);
-  }
-
-  return JSON.stringify(data, null, 2);
-}
-
 // ============================================================================
 // Hook 实现
 // ============================================================================
@@ -442,7 +267,7 @@ export function useChartDownload(
 
         // 创建 PDF（使用 canvas 转换）
         // 注意：在实际环境中，可能需要使用 jsPDF 或其他 PDF 库
-        const pdfDataUrl = await createPdfFromImage(dataUrl);
+        const pdfDataUrl = await createPdfFromImage(dataUrl, name);
         if (pdfDataUrl) {
           downloadDataUrl(pdfDataUrl, `${name}.pdf`);
           executeAfterExport(pdfDataUrl);
@@ -454,79 +279,10 @@ export function useChartDownload(
     [filename, pixelRatio, backgroundColor, executeBeforeExport, executeAfterExport]
   );
 
-  /**
-   * 从图片创建 PDF DataURL
-   */
-  const createPdfFromImage = async (imageDataUrl: string): Promise<string | null> => {
-    return new Promise((resolve) => {
-      try {
-        // 创建画布
-        const canvas = document.createElement('canvas');
-        const ctx = canvas.getContext('2d');
-        if (!ctx) {
-          resolve(null);
-          return;
-        }
-
-        // 加载图片
-        const img = new Image();
-        img.onload = () => {
-          // 设置 PDF 尺寸（A4 纵向）
-          const pdfWidth = 595.28; // A4 width in points
-          const pdfHeight = 841.89; // A4 height in points
-
-          canvas.width = pdfWidth;
-          canvas.height = pdfHeight;
-
-          // 填充背景
-          ctx.fillStyle = '#ffffff';
-          ctx.fillRect(0, 0, pdfWidth, pdfHeight);
-
-          // 计算图片位置和尺寸（居中）
-          const imgRatio = img.width / img.height;
-          const canvasRatio = pdfWidth / pdfHeight;
-          let drawWidth, drawHeight, offsetX, offsetY;
-
-          if (imgRatio > canvasRatio) {
-            drawWidth = pdfWidth * 0.8;
-            drawHeight = drawWidth / imgRatio;
-          } else {
-            drawHeight = pdfHeight * 0.6;
-            drawWidth = drawHeight * imgRatio;
-          }
-
-          offsetX = (pdfWidth - drawWidth) / 2;
-          offsetY = (pdfHeight - drawHeight) / 2;
-
-          // 绘制图片
-          ctx.drawImage(img, offsetX, offsetY, drawWidth, drawHeight);
-
-          // 添加标题
-          ctx.fillStyle = '#333333';
-          ctx.font = '16px Arial';
-          ctx.textAlign = 'center';
-          ctx.fillText(filename || 'Chart Export', pdfWidth / 2, offsetY - 20);
-
-          // 输出为 PNG（实际应用中应该使用 jsPDF 生成真正的 PDF）
-          resolve(canvas.toDataURL('image/png'));
-        };
-
-        img.onerror = () => {
-          resolve(null);
-        };
-
-        img.src = imageDataUrl;
-      } catch (e) {
-        console.warn('[useChartDownload] Failed to create PDF:', e);
-        resolve(null);
-      }
-    });
-  };
-
   /**
    * 获取图表数据
    */
-  const getChartData = useCallback((): any => {
+  const getChartData = useCallback((): unknown => {
     const chart = chartRef.current;
     if (!chart) return null;
 
@@ -577,9 +333,9 @@ export function useChartDownload(
         }
 
         // 提取数据
-        let data = option;
+        let data: unknown = option;
         if (dataKey && typeof data === 'object') {
-          data = (data as any)[dataKey] || data;
+          data = (data as Record<string, unknown>)[dataKey] || data;
         }
 
         // 转换为 CSV
@@ -621,9 +377,9 @@ export function useChartDownload(
         }
 
         // 提取数据
-        let data = option;
+        let data: unknown = option;
         if (dataKey && typeof data === 'object') {
-          data = (data as any)[dataKey] || data;
+          data = (data as Record<string, unknown>)[dataKey] || data;
         }
 
         // 转换为 JSON

package/src/hooks/useChartHistory.ts

@@ -0,0 +1,273 @@
+/**
+ * useChartHistory - 图表 Undo/Redo Hook
+ * 追踪图表配置历史，支持撤销/重做操作和键盘快捷键
+ *
+ * 特性：
+ * - 最多保存 50 条历史记录（可配置）
+ * - 自动绑定 Ctrl+Z / Ctrl+Y 键盘快捷键
+ * - 支持 ignoreKeys 忽略特定配置字段（如动画、时间戳）
+ * - 暴露 canUndo / canRedo 状态
+ */
+import { useEffect, useRef, useCallback, useState } from 'react';
+import type { ChartInstance } from './index';
+import type { EChartsOption } from 'echarts';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+export interface UseChartHistoryOptions {
+  /** 最大历史记录数，默认 50 */
+  maxHistorySize?: number;
+  /** 忽略的顶层配置键（不计入历史），默认 ['animation', 'animationDuration', 'animationEasing', 'animationFrame'] */
+  ignoreKeys?: string[];
+  /** 是否自动绑定键盘快捷键，默认 true */
+  enableKeyboard?: boolean;
+  /** 是否在组件卸载时自动清空历史，默认 false */
+  clearOnUnmount?: boolean;
+}
+
+export interface UseChartHistoryReturn {
+  /** 是否可撤销 */
+  canUndo: boolean;
+  /** 是否可重做 */
+  canRedo: boolean;
+  /** 当前历史索引 */
+  currentIndex: number;
+  /** 历史总数 */
+  historyCount: number;
+  /** 撤销一步 */
+  undo: () => void;
+  /** 重做一步 */
+  redo: () => void;
+  /** 跳转到指定历史索引 */
+  goTo: (index: number) => void;
+  /** 手动推送一条历史记录 */
+  push: (option: EChartsOption) => void;
+  /** 清空历史记录 */
+  clear: () => void;
+}
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+
+/** 深度省略指定键后比较两个配置是否相等 */
+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;
+  }
+
+  const aObj = a as Record<string, unknown>;
+  const bObj = b as Record<string, unknown>;
+  const aKeys = Object.keys(aObj).filter((k) => !ignoreKeys.has(k));
+  const bKeys = Object.keys(bObj).filter((k) => !ignoreKeys.has(k));
+
+  if (aKeys.length !== bKeys.length) return false;
+
+  for (const key of aKeys) {
+    if (!bObj.hasOwnProperty(key)) return false;
+    if (!omitAndCompare(aObj[key], bObj[key], ignoreKeys)) return false;
+  }
+
+  return true;
+}
+
+// ============================================================================
+// Hook 实现
+// ============================================================================
+
+/**
+ * 使用图表历史记录（Undo/Redo）
+ * @param chartInstance 图表实例
+ * @param options 配置选项
+ * @returns 历史记录控制接口
+ */
+export function useChartHistory(
+  chartInstance: ChartInstance | null,
+  options: UseChartHistoryOptions = {}
+): UseChartHistoryReturn {
+  const {
+    maxHistorySize = 50,
+    ignoreKeys = [
+      'animation',
+      'animationDuration',
+      'animationEasing',
+      'animationFrame',
+    ],
+    enableKeyboard = true,
+    clearOnUnmount = false,
+  } = options;
+
+  // 忽略键集合
+  const ignoreKeySet = useRef(new Set<string>(ignoreKeys));
+
+  // 历史栈（每次 setOption 快照）
+  const historyStack = useRef<EChartsOption[]>([]);
+
+  // 当前索引
+  const [currentIndex, setCurrentIndex] = useState(-1);
+
+  // Chart instance ref
+  const chartRef = useRef<ChartInstance | null>(null);
+  chartRef.current = chartInstance;
+
+  // 是否正在执行 undo/redo（避免 push 时重复记录）
+  const isApplyingRef = useRef(false);
+
+  // 拦截 chart.setOption，记录历史
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart) return;
+
+    const originalSetOption = chart.setOption.bind(chart);
+
+    chart.setOption = (
+      option: EChartsOption,
+      notMerge?: boolean,
+      lazyUpdate?: boolean
+    ) => {
+      // 如果正在执行 undo/redo，跳过历史记录
+      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;
+      return originalSetOption(option, notMerge, lazyUpdate);
+    };
+
+    return () => {
+      // 恢复原始 setOption
+      chart.setOption = originalSetOption;
+    };
+  }, [chartInstance, currentIndex, maxHistorySize]);
+
+  // 键盘快捷键：Ctrl+Z 撤销，Ctrl+Y / Ctrl+Shift+Z 重做
+  useEffect(() => {
+    if (!enableKeyboard) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const isMod = e.ctrlKey || e.metaKey;
+      if (!isMod) return;
+
+      if (e.key === 'z' && !e.shiftKey) {
+        e.preventDefault();
+        undo();
+      } else if (e.key === 'y' || (e.key === 'z' && e.shiftKey)) {
+        e.preventDefault();
+        redo();
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [enableKeyboard]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // 组件卸载时清空
+  useEffect(() => {
+    return () => {
+      if (clearOnUnmount) {
+        historyStack.current = [];
+        setCurrentIndex(-1);
+      }
+    };
+  }, [clearOnUnmount]);
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  const undo = useCallback(() => {
+    const chart = chartRef.current;
+    if (!chart || currentIndex <= 0) return;
+
+    const idx = currentIndex - 1;
+    isApplyingRef.current = true;
+    chart.setOption(historyStack.current[idx], true, true);
+    isApplyingRef.current = false;
+    setCurrentIndex(idx);
+  }, [currentIndex]);
+
+  const redo = useCallback(() => {
+    const chart = chartRef.current;
+    if (!chart || currentIndex >= historyStack.current.length - 1) return;
+
+    const idx = currentIndex + 1;
+    isApplyingRef.current = true;
+    chart.setOption(historyStack.current[idx], true, true);
+    isApplyingRef.current = false;
+    setCurrentIndex(idx);
+  }, [currentIndex]);
+
+  const goTo = useCallback(
+    (index: number) => {
+      const chart = chartRef.current;
+      if (!chart) return;
+      if (index < 0 || index >= historyStack.current.length) return;
+      if (index === currentIndex) return;
+
+      isApplyingRef.current = true;
+      chart.setOption(historyStack.current[index], true, true);
+      isApplyingRef.current = false;
+      setCurrentIndex(index);
+    },
+    [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 clear = useCallback(() => {
+    historyStack.current = [];
+    setCurrentIndex(-1);
+  }, []);
+
+  return {
+    canUndo: currentIndex > 0,
+    canRedo: currentIndex < historyStack.current.length - 1,
+    currentIndex,
+    historyCount: historyStack.current.length,
+    undo,
+    redo,
+    goTo,
+    push,
+    clear,
+  };
+}
+
+export default useChartHistory;