@agions/taroviz 1.7.0 → 1.9.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/usePerformance.ts

@@ -0,0 +1,291 @@
+/**
+ * usePerformance - 图表性能监控 Hook
+ * 提供实时性能指标监控和报告功能
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { PerformanceAnalyzer, PerformanceMetricType, PerformanceMetric } from '../core/utils/performance';
+
+/**
+ * 性能监控配置
+ */
+export interface UsePerformanceOptions {
+  /** 是否启用监控 */
+  enabled?: boolean;
+  /** 采样间隔 (ms) */
+  sampleInterval?: number;
+  /** 是否显示实时 FPS */
+  showFPS?: boolean;
+  /** FPS 告警阈值 */
+  fpsWarningThreshold?: number;
+  /** FPS 严重告警阈值 */
+  fpsCriticalThreshold?: number;
+  /** 自动启动 */
+  autoStart?: boolean;
+}
+
+/**
+ * 性能指标状态
+ */
+export interface PerformanceState {
+  /** 当前 FPS */
+  fps: number;
+  /** 平均 FPS */
+  avgFps: number;
+  /** 最低 FPS */
+  minFps: number;
+  /** 最高 FPS */
+  maxFps: number;
+  /** FPS 状态: normal | warning | critical */
+  fpsStatus: 'normal' | 'warning' | 'critical';
+  /** 帧率历史 */
+  fpsHistory: number[];
+  /** 是否正在监控 */
+  isMonitoring: boolean;
+}
+
+/**
+ * 性能监控返回值
+ */
+export interface UsePerformanceReturn {
+  /** 性能状态 */
+  state: PerformanceState;
+  /** 开始监控 */
+  start: () => void;
+  /** 停止监控 */
+  stop: () => void;
+  /** 重置统计数据 */
+  reset: () => void;
+  /** 获取性能报告 */
+  getReport: () => PerformanceMetric[];
+  /** FPS 告警回调 */
+  onFpsWarning?: (fps: number) => void;
+}
+
+/**
+ * 使用图表性能监控
+ * @param options 配置选项
+ * @returns 性能监控接口
+ */
+export function usePerformance(options: UsePerformanceOptions = {}): UsePerformanceReturn {
+  const {
+    enabled = true,
+    sampleInterval = 1000,
+    showFPS = true,
+    fpsWarningThreshold = 30,
+    fpsCriticalThreshold = 15,
+    autoStart = true,
+  } = options;
+
+  // Refs
+  const analyzerRef = useRef<PerformanceAnalyzer | null>(null);
+  const fpsHistoryRef = useRef<number[]>([]);
+  const animationFrameRef = useRef<number | null>(null);
+  const lastFrameTimeRef = useRef<number>(0);
+  const fpsAccumulatorRef = useRef<{ frames: number; lastTime: number }>({ frames: 0, lastTime: 0 });
+
+  // State
+  const [state, setState] = useState<PerformanceState>({
+    fps: 60,
+    avgFps: 60,
+    minFps: 60,
+    maxFps: 60,
+    fpsStatus: 'normal',
+    fpsHistory: [],
+    isMonitoring: false,
+  });
+
+  /**
+   * 计算 FPS 状态
+   */
+  const calculateFpsStatus = useCallback(
+    (fps: number): 'normal' | 'warning' | 'critical' => {
+      if (fps <= fpsCriticalThreshold) return 'critical';
+      if (fps <= fpsWarningThreshold) return 'warning';
+      return 'normal';
+    },
+    [fpsWarningThreshold, fpsCriticalThreshold]
+  );
+
+  /**
+   * 更新 FPS 计算
+   */
+  const updateFps = useCallback(() => {
+    if (!enabled) return;
+
+    const now = performance.now();
+    const delta = now - lastFrameTimeRef.current;
+    lastFrameTimeRef.current = now;
+
+    // 累积帧数
+    fpsAccumulatorRef.current.frames++;
+
+    // 每秒计算一次 FPS
+    if (now - fpsAccumulatorRef.current.lastTime >= 1000) {
+      const fps = Math.round((fpsAccumulatorRef.current.frames * 1000) / (now - fpsAccumulatorRef.current.lastTime));
+      const history = fpsHistoryRef.current;
+
+      // 更新历史
+      history.push(fps);
+      if (history.length > 60) {
+        history.shift();
+      }
+
+      // 计算统计数据
+      const avgFps = Math.round(history.reduce((a, b) => a + b, 0) / history.length);
+      const minFps = Math.min(...history);
+      const maxFps = Math.max(...history);
+
+      setState(prev => ({
+        ...prev,
+        fps,
+        avgFps,
+        minFps,
+        maxFps,
+        fpsStatus: calculateFpsStatus(fps),
+        fpsHistory: [...history],
+      }));
+
+      // 重置计数器
+      fpsAccumulatorRef.current.frames = 0;
+      fpsAccumulatorRef.current.lastTime = now;
+    }
+
+    // 继续下一帧
+    animationFrameRef.current = requestAnimationFrame(updateFps);
+  }, [enabled, calculateFpsStatus]);
+
+  /**
+   * 开始监控
+   */
+  const start = useCallback(() => {
+    if (!enabled) return;
+
+    // Prevent starting multiple RAF loops
+    if (animationFrameRef.current !== null) return;
+
+    // 初始化分析器
+    if (!analyzerRef.current) {
+      analyzerRef.current = PerformanceAnalyzer.getInstance({
+        enabled: true,
+        sampleInterval,
+        autoStart: false,
+      });
+    }
+
+    analyzerRef.current.start();
+
+    // 重置 FPS 计算
+    fpsAccumulatorRef.current = { frames: 0, lastTime: performance.now() };
+    lastFrameTimeRef.current = performance.now();
+    fpsHistoryRef.current = [];
+
+    // 开始 FPS 监控循环
+    animationFrameRef.current = requestAnimationFrame(updateFps);
+
+    setState(prev => ({ ...prev, isMonitoring: true }));
+  }, [enabled, sampleInterval, updateFps]);
+
+  /**
+   * 停止监控
+   */
+  const stop = useCallback(() => {
+    // 停止 FPS 监控
+    if (animationFrameRef.current !== null) {
+      cancelAnimationFrame(animationFrameRef.current);
+      animationFrameRef.current = null;
+    }
+
+    // 停止分析器
+    analyzerRef.current?.stop();
+
+    setState(prev => ({ ...prev, isMonitoring: false }));
+  }, []);
+
+  /**
+   * 重置统计数据
+   */
+  const reset = useCallback(() => {
+    PerformanceAnalyzer.resetInstance();
+    fpsHistoryRef.current = [];
+    setState(prev => ({
+      ...prev,
+      fps: 60,
+      avgFps: 60,
+      minFps: 60,
+      maxFps: 60,
+      fpsStatus: 'normal',
+      fpsHistory: [],
+    }));
+  }, []);
+
+  /**
+   * 获取性能报告
+   */
+  const getReport = useCallback((): PerformanceMetric[] => {
+    if (!analyzerRef.current) return [];
+
+    try {
+      const report = analyzerRef.current.getAllMetrics?.();
+      if (!report) return [];
+      return Array.from(report.values()).flat();
+    } catch {
+      return [];
+    }
+  }, []);
+
+  // 自动启动
+  useEffect(() => {
+    if (autoStart && enabled) {
+      start();
+    }
+
+    return () => {
+      stop();
+    };
+  }, [autoStart, enabled, start, stop]);
+
+  return {
+    state,
+    start,
+    stop,
+    reset,
+    getReport,
+  };
+}
+
+/**
+ * 轻量级 FPS 监控 Hook
+ * 用于实时显示图表 FPS
+ */
+export function useFpsMonitor(): number {
+  const [fps, setFps] = useState(60);
+  const frameCountRef = useRef(0);
+  const lastTimeRef = useRef(performance.now());
+
+  useEffect(() => {
+    let animationId: number;
+
+    const tick = () => {
+      frameCountRef.current++;
+      const now = performance.now();
+      const elapsed = now - lastTimeRef.current;
+
+      if (elapsed >= 1000) {
+        const currentFps = Math.round((frameCountRef.current * 1000) / elapsed);
+        setFps(currentFps);
+        frameCountRef.current = 0;
+        lastTimeRef.current = now;
+      }
+
+      animationId = requestAnimationFrame(tick);
+    };
+
+    animationId = requestAnimationFrame(tick);
+
+    return () => cancelAnimationFrame(animationId);
+  }, []);
+
+  return fps;
+}
+
+export default usePerformance;