@agions/taroviz 1.7.0 → 1.10.0

package/src/hooks/useAnimation.ts

@@ -0,0 +1,427 @@
+/**
+ * useAnimation - 图表动画控制 Hook
+ * 提供图表动画的播放、暂停、控制等功能
+ */
+import { useState, useCallback, useRef, useEffect } from 'react';
+import type { ChartInstance } from './index';
+
+/**
+ * 动画状态
+ */
+export type AnimationStatus = 'playing' | 'paused' | 'stopped';
+
+/**
+ * 动画配置选项
+ */
+export interface UseAnimationOptions {
+  /** 动画时长 (ms) */
+  duration?: number;
+  /** 动画缓动函数 */
+  easing?: 'cubicOut' | 'cubicIn' | 'cubicInOut' | 'linear' | 'sinusoidalIn' | 'sinusoidalOut';
+  /** 是否禁用动画 */
+  disabled?: boolean;
+  /** 动画延迟 (ms) */
+  delay?: number;
+  /** 是否循环 */
+  loop?: boolean;
+  /** 循环次数 (-1 表示无限) */
+  loopCount?: number;
+}
+
+/**
+ * 动画状态返回值
+ */
+export interface UseAnimationReturn {
+  /** 当前动画状态 */
+  status: AnimationStatus;
+  /** 当前动画帧 */
+  frame: number;
+  /** 总帧数 */
+  totalFrames: number;
+  /** 动画进度 (0-1) */
+  progress: number;
+  /** 播放动画 */
+  play: () => void;
+  /** 暂停动画 */
+  pause: () => void;
+  /** 停止动画并重置 */
+  stop: () => void;
+  /** 跳转到指定帧 */
+  seekTo: (frame: number) => void;
+  /** 跳转到指定进度 */
+  seekToProgress: (progress: number) => void;
+  /** 设置播放速度 */
+  setPlaybackSpeed: (speed: number) => void;
+  /** 播放速度 */
+  playbackSpeed: number;
+}
+
+/**
+ * 使用图表动画控制
+ * @param chartInstance 图表实例
+ * @param options 配置选项
+ * @returns 动画控制接口
+ */
+export function useAnimation(
+  chartInstance: ChartInstance | null,
+  options: UseAnimationOptions = {}
+): UseAnimationReturn {
+  const {
+    duration = 1000,
+    easing = 'cubicOut',
+    disabled = false,
+    delay = 0,
+    loop = false,
+    loopCount = -1,
+  } = options;
+
+  // State
+  const [status, setStatus] = useState<AnimationStatus>('stopped');
+  const [frame, setFrame] = useState(0);
+  const [playbackSpeed, setPlaybackSpeedState] = useState(1);
+
+  // Refs
+  const animationRef = useRef<{
+    startTime: number;
+    currentFrame: number;
+    loopCounter: number;
+    animationId: number | null;
+    isPaused: boolean;
+  }>({
+    startTime: 0,
+    currentFrame: 0,
+    loopCounter: 0,
+    animationId: null,
+    isPaused: false,
+  });
+
+  const chartRef = useRef<ChartInstance | null>(null);
+  chartRef.current = chartInstance;
+
+  // 计算总帧数（假设 60fps）
+  const totalFrames = Math.ceil((duration / 1000) * 60);
+
+  // 缓动函数
+  const easingFunctions: Record<string, (t: number) => number> = {
+    cubicOut: (t) => 1 - Math.pow(1 - t, 3),
+    cubicIn: (t) => t * t * t,
+    cubicInOut: (t) => t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2,
+    linear: (t) => t,
+    sinusoidalIn: (t) => 1 - Math.cos((t * Math.PI) / 2),
+    sinusoidalOut: (t) => Math.sin((t * Math.PI) / 2),
+  };
+
+  // 计算当前进度对应的帧
+  const calculateFrame = useCallback(
+    (progress: number) => {
+      return Math.floor(progress * totalFrames);
+    },
+    [totalFrames]
+  );
+
+  // 设置播放速度
+  const setPlaybackSpeed = useCallback((speed: number) => {
+    setPlaybackSpeedState(Math.max(0.1, Math.min(10, speed)));
+  }, []);
+
+  // 动画更新函数
+  const animate = useCallback(() => {
+    const anim = animationRef.current;
+    const chart = chartRef.current;
+
+    if (!chart || anim.isPaused || disabled) {
+      return;
+    }
+
+    const elapsed = performance.now() - anim.startTime;
+    const adjustedDuration = duration / playbackSpeed;
+    const effectiveElapsed = anim.isPaused ? 0 : elapsed - delay;
+
+    if (effectiveElapsed < 0) {
+      anim.animationId = requestAnimationFrame(animate);
+      return;
+    }
+
+    // 计算当前进度
+    let progress = Math.min(effectiveElapsed / adjustedDuration, 1);
+    progress = easingFunctions[easing](progress);
+
+    // 计算当前帧
+    const currentFrame = calculateFrame(progress);
+    anim.currentFrame = currentFrame;
+
+    setFrame(currentFrame);
+
+    // 更新图表配置以反映动画进度
+    try {
+      // ECharts 通过 setOption 配合 notMerge: false 更新动画
+      if (chart.setOption && !anim.isPaused) {
+        // 触发图表重新渲染
+        chart.setOption({}, false, true);
+      }
+    } catch (e) {
+      console.warn('[useAnimation] Failed to update chart:', e);
+    }
+
+    // 检查是否完成
+    if (effectiveElapsed >= adjustedDuration) {
+      if (loop && (loopCount === -1 || anim.loopCounter < loopCount)) {
+        // 继续循环
+        anim.loopCounter++;
+        anim.startTime = performance.now();
+        anim.isPaused = false;
+        setStatus('playing');
+      } else {
+        // 动画结束
+        setStatus('stopped');
+        anim.animationId = null;
+        return;
+      }
+    }
+
+    anim.animationId = requestAnimationFrame(animate);
+  }, [duration, easing, disabled, delay, loop, loopCount, playbackSpeed, easingFunctions, calculateFrame]);
+
+  // 播放动画
+  const play = useCallback(() => {
+    const chart = chartRef.current;
+    if (!chart || disabled) return;
+
+    const anim = animationRef.current;
+
+    if (status === 'paused') {
+      // 从暂停恢复
+      anim.isPaused = false;
+      anim.startTime = performance.now() - (anim.currentFrame / totalFrames) * duration;
+      setStatus('playing');
+    } else {
+      // 开始新动画
+      anim.startTime = performance.now();
+      anim.currentFrame = 0;
+      anim.loopCounter = 0;
+      anim.isPaused = false;
+      setStatus('playing');
+    }
+
+    if (anim.animationId === null) {
+      anim.animationId = requestAnimationFrame(animate);
+    }
+  }, [status, disabled, totalFrames, duration, animate]);
+
+  // 暂停动画
+  const pause = useCallback(() => {
+    const anim = animationRef.current;
+    anim.isPaused = true;
+    setStatus('paused');
+  }, []);
+
+  // 停止动画并重置
+  const stop = useCallback(() => {
+    const anim = animationRef.current;
+
+    if (anim.animationId !== null) {
+      cancelAnimationFrame(anim.animationId);
+      anim.animationId = null;
+    }
+
+    anim.isPaused = false;
+    anim.currentFrame = 0;
+    anim.loopCounter = 0;
+    setStatus('stopped');
+    setFrame(0);
+  }, []);
+
+  // 跳转到指定帧
+  const seekTo = useCallback(
+    (targetFrame: number) => {
+      const anim = animationRef.current;
+      const chart = chartRef.current;
+      if (!chart) return;
+
+      const clampedFrame = Math.max(0, Math.min(totalFrames, targetFrame));
+      anim.currentFrame = clampedFrame;
+      setFrame(clampedFrame);
+
+      // 更新图表状态
+      const progress = clampedFrame / totalFrames;
+      try {
+        if (chart.setOption) {
+          chart.setOption({}, false, true);
+        }
+      } catch (e) {
+        console.warn('[useAnimation] Failed to seek:', e);
+      }
+    },
+    [totalFrames]
+  );
+
+  // 跳转到指定进度
+  const seekToProgress = useCallback(
+    (progress: number) => {
+      const targetProgress = Math.max(0, Math.min(1, progress));
+      const targetFrame = calculateFrame(targetProgress);
+      seekTo(targetFrame);
+    },
+    [calculateFrame, seekTo]
+  );
+
+  // 进度
+  const progress = totalFrames > 0 ? frame / totalFrames : 0;
+
+  // 清理
+  useEffect(() => {
+    return () => {
+      const anim = animationRef.current;
+      if (anim.animationId !== null) {
+        cancelAnimationFrame(anim.animationId);
+      }
+    };
+  }, []);
+
+  // 组件卸载时停止动画
+  useEffect(() => {
+    if (!chartInstance) {
+      stop();
+    }
+  }, [chartInstance, stop]);
+
+  return {
+    status,
+    frame,
+    totalFrames,
+    progress,
+    play,
+    pause,
+    stop,
+    seekTo,
+    seekToProgress,
+    setPlaybackSpeed,
+    playbackSpeed,
+  };
+}
+
+/**
+ * 渐进式加载动画 Hook
+ * 用于大数据的分批次加载动画
+ */
+export interface UseProgressiveLoadingOptions {
+  /** 每批加载的数据量 */
+  batchSize?: number;
+  /** 批次间隔 (ms) */
+  interval?: number;
+  /** 是否自动开始 */
+  autoStart?: boolean;
+  /** 加载完成回调 */
+  onBatchLoaded?: (batchIndex: number, totalBatches: number) => void;
+  /** 全部加载完成回调 */
+  onComplete?: () => void;
+}
+
+export interface UseProgressiveLoadingReturn {
+  /** 当前批次 */
+  currentBatch: number;
+  /** 总批次数 */
+  totalBatches: number;
+  /** 加载进度 */
+  progress: number;
+  /** 是否正在加载 */
+  isLoading: boolean;
+  /** 开始加载 */
+  start: () => void;
+  /** 暂停加载 */
+  pause: () => void;
+  /** 停止加载 */
+  stop: () => void;
+  /** 重置 */
+  reset: () => void;
+}
+
+export function useProgressiveLoading(
+  totalCount: number,
+  options: UseProgressiveLoadingOptions = {}
+): UseProgressiveLoadingReturn {
+  const {
+    batchSize = 1000,
+    interval = 100,
+    autoStart = false,
+    onBatchLoaded,
+    onComplete,
+  } = options;
+
+  const totalBatches = Math.ceil(totalCount / batchSize);
+  const [currentBatch, setCurrentBatch] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const intervalRef = useRef<number | null>(null);
+
+  const progress = totalBatches > 0 ? currentBatch / totalBatches : 0;
+
+  const start = useCallback(() => {
+    if (isLoading) return;
+
+    setIsLoading(true);
+    setCurrentBatch(0);
+
+    intervalRef.current = window.setInterval(() => {
+      setCurrentBatch(prev => {
+        const next = prev + 1;
+        onBatchLoaded?.(next, totalBatches);
+
+        if (next >= totalBatches) {
+          if (intervalRef.current !== null) {
+            clearInterval(intervalRef.current);
+            intervalRef.current = null;
+          }
+          setIsLoading(false);
+          onComplete?.();
+          return totalBatches;
+        }
+
+        return next;
+      });
+    }, interval);
+  }, [isLoading, interval, totalBatches, onBatchLoaded, onComplete]);
+
+  const pause = useCallback(() => {
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current);
+      intervalRef.current = null;
+    }
+    setIsLoading(false);
+  }, []);
+
+  const stop = useCallback(() => {
+    pause();
+    setCurrentBatch(0);
+  }, [pause]);
+
+  const reset = useCallback(() => {
+    stop();
+  }, [stop]);
+
+  useEffect(() => {
+    if (autoStart) {
+      start();
+    }
+  }, [autoStart, start]);
+
+  useEffect(() => {
+    return () => {
+      if (intervalRef.current !== null) {
+        clearInterval(intervalRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    currentBatch,
+    totalBatches,
+    progress,
+    isLoading,
+    start,
+    pause,
+    stop,
+    reset,
+  };
+}
+
+export default useAnimation;

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;