@agions/taroviz 1.11.1 → 2.0.3

package/src/core/utils/performance/useDataZoom.ts

@@ -0,0 +1,324 @@
+/**
+ * useDataZoom - 数据缩放 Hook
+ * 控制图表的数据缩放区域（dataZoom），支持拖拽和滚轮缩放
+ */
+import { useRef, useCallback, useEffect, useMemo } from 'react';
+import type { RefObject } from 'react';
+import type { ChartInstance, DataZoomType, ZoomRange, EventHandler } from '../../../hooks/types';
+
+// ============================================================================
+// Hook 实现
+// ============================================================================
+
+/**
+ * 使用图表数据缩放
+ * @param options 配置选项
+ * @returns dataZoom 操作接口
+ */
+export function useDataZoom(
+  options: {
+    type?: DataZoomType;
+    start?: number;
+    end?: number;
+    minSpan?: number;
+    maxSpan?: number;
+    zoomLock?: boolean;
+    throttle?: number;
+    disabled?: boolean;
+    brushSelect?: boolean;
+    zoomMode?: 'scale' | 'mix';
+    resetOnUnmount?: boolean;
+    onZoomChange?: (range: { start: number; end: number }) => void;
+  } = {}
+): {
+  bindDataZoom: (chartInstance: ChartInstance) => void;
+  setZoomRange: (start: number, end: number) => void;
+  resetZoom: () => void;
+  getZoomRange: () => ZoomRange;
+  startValue: RefObject<number | string | Date | undefined>;
+  endValue: RefObject<number | string | Date | undefined>;
+  bindEvents: (chartInstance: ChartInstance) => void;
+} {
+  const {
+    type = 'inside',
+    start = 0,
+    end = 100,
+    minSpan,
+    maxSpan,
+    zoomLock = false,
+    throttle = 16,
+    disabled = false,
+    brushSelect = false,
+    zoomMode = 'scale',
+    resetOnUnmount = false,
+    onZoomChange,
+  } = options;
+
+  // Refs
+  const chartRef = useRef<ChartInstance | null>(null);
+  const startValueRef = useRef<number | string | Date | undefined>(undefined);
+  const endValueRef = useRef<number | string | Date | undefined>(undefined);
+  const isBindingRef = useRef(false);
+
+  // 稳定的配置 refs（避免闭包陷阱）
+  const configRef = useRef({
+    type,
+    start,
+    end,
+    minSpan,
+    maxSpan,
+    zoomLock,
+    disabled,
+    brushSelect,
+    zoomMode,
+    throttle,
+  });
+  configRef.current = {
+    type,
+    start,
+    end,
+    minSpan,
+    maxSpan,
+    zoomLock,
+    disabled,
+    brushSelect,
+    zoomMode,
+    throttle,
+  };
+
+  // 事件处理 refs（避免重复绑定）
+  const onZoomChangeRef = useRef(onZoomChange);
+  onZoomChangeRef.current = onZoomChange;
+
+  // 节流处理器 ref
+  const throttledHandlerRef = useRef<EventHandler | null>(null);
+  const lastCallRef = useRef(0);
+
+  // 构建 dataZoom 配置
+  const buildDataZoomConfig = useCallback(() => {
+    const {
+      type: cfgType,
+      start: cfgStart,
+      end: cfgEnd,
+      minSpan: cfgMinSpan,
+      maxSpan: cfgMaxSpan,
+      zoomLock: cfgZoomLock,
+      disabled: cfgDisabled,
+      brushSelect: cfgBrushSelect,
+      zoomMode: cfgZoomMode,
+    } = configRef.current;
+
+    const config: Record<string, unknown>[] = [];
+
+    // 内置型 dataZoom
+    if (cfgType === 'inside' || cfgZoomMode === 'mix') {
+      config.push({
+        type: 'inside',
+        start: cfgStart,
+        end: cfgEnd,
+        zoomLock: cfgZoomLock,
+        disabled: cfgDisabled,
+        zoomOnMouseWheel: true,
+        moveOnMouseMove: false,
+        moveOnMouseWheel: false,
+        preventDefaultMouseMove: true,
+      });
+    }
+
+    // 滑块型 dataZoom
+    if (cfgType === 'slider' || cfgZoomMode === 'mix') {
+      config.push({
+        type: 'slider',
+        start: cfgStart,
+        end: cfgEnd,
+        minSpan: cfgMinSpan,
+        maxSpan: cfgMaxSpan,
+        zoomLock: cfgZoomLock,
+        disabled: cfgDisabled,
+        show: true,
+        brushSelect: cfgBrushSelect,
+        throttle: configRef.current.throttle,
+      });
+    }
+
+    return config;
+  }, []);
+
+  // 绑定 dataZoom 到图表
+  const bindDataZoom = useCallback(
+    (chartInstance: ChartInstance) => {
+      if (!chartInstance || isBindingRef.current) return;
+
+      isBindingRef.current = true;
+      chartRef.current = chartInstance;
+
+      try {
+        const dataZoomConfig = buildDataZoomConfig();
+        chartInstance.setOption({ dataZoom: dataZoomConfig }, false, true);
+      } catch (e) {
+        console.warn('[useDataZoom] Failed to bind dataZoom:', e);
+      }
+
+      isBindingRef.current = false;
+    },
+    [buildDataZoomConfig]
+  );
+
+  // 解绑 dataZoom
+  const unbindDataZoom = useCallback((chartInstance: ChartInstance) => {
+    if (!chartInstance) return;
+    try {
+      chartInstance.dispatchAction?.({
+        type: 'dataZoom',
+        start: 0,
+        end: 100,
+      });
+    } catch (e) {
+      console.warn('[useDataZoom] Failed to unbind dataZoom:', e);
+    }
+  }, []);
+
+  // 设置缩放范围
+  const setZoomRange = useCallback((newStart: number, newEnd: number) => {
+    const chart = chartRef.current;
+    if (!chart) return;
+
+    const clampedStart = Math.max(0, Math.min(100, newStart));
+    const clampedEnd = Math.max(0, Math.min(100, newEnd));
+
+    try {
+      chart.dispatchAction?.({
+        type: 'dataZoom',
+        start: clampedStart,
+        end: clampedEnd,
+      });
+    } catch (e) {
+      console.warn('[useDataZoom] Failed to set zoom range:', e);
+    }
+  }, []);
+
+  // 重置缩放
+  const resetZoom = useCallback(() => {
+    const { start: s, end: e } = configRef.current;
+    setZoomRange(s, e);
+  }, [setZoomRange]);
+
+  // 获取当前缩放范围
+  const getZoomRange = useCallback((): ZoomRange => {
+    const chart = chartRef.current;
+    if (!chart) {
+      const { start: s, end: e } = configRef.current;
+      return { start: s, end: e };
+    }
+
+    try {
+      const option = chart.getOption?.();
+      const dataZoom = option?.dataZoom as
+        | Array<{ type: string; start?: number; end?: number }>
+        | undefined;
+      if (Array.isArray(dataZoom) && dataZoom.length > 0) {
+        const insideZoom = dataZoom.find((dz) => dz.type === 'inside');
+        const sliderZoom = dataZoom.find((dz) => dz.type === 'slider');
+        const zoom = insideZoom || sliderZoom || dataZoom[0];
+        return {
+          start: zoom.start ?? configRef.current.start,
+          end: zoom.end ?? configRef.current.end,
+        };
+      }
+    } catch (e) {
+      console.warn('[useDataZoom] Failed to get zoom range:', e);
+    }
+
+    return { start: configRef.current.start, end: configRef.current.end };
+  }, []);
+
+  // 绑定事件
+  const bindEvents = useCallback((chartInstance: ChartInstance) => {
+    if (!chartInstance) return;
+
+    // 创建节流后的缩放变化处理器（使用稳定的 throttle 值）
+    const handleZoomChange: EventHandler = (params: unknown) => {
+      // disabled 通过 configRef 读取，保证实时性
+      if (configRef.current.disabled) return;
+
+      const p = params as { start?: number; end?: number } | undefined;
+      const { start: newStart, end: newEnd } = p || {};
+      if (newStart !== undefined) startValueRef.current = newStart;
+      if (newEnd !== undefined) endValueRef.current = newEnd;
+
+      // 使用 ref 读取 onZoomChange，避免闭包捕获旧值
+      onZoomChangeRef.current?.({
+        start: newStart ?? configRef.current.start,
+        end: newEnd ?? configRef.current.end,
+      });
+    };
+
+    // 节流包装
+    const { throttle: throttleVal } = configRef.current;
+    const throttledHandler: EventHandler = (params: unknown) => {
+      const now = Date.now();
+      if (now - lastCallRef.current >= throttleVal) {
+        lastCallRef.current = now;
+        handleZoomChange(params);
+      }
+    };
+
+    throttledHandlerRef.current = throttledHandler;
+
+    try {
+      chartInstance.on('datazoom', throttledHandler);
+    } catch (e) {
+      console.warn('[useDataZoom] Failed to bind events:', e);
+    }
+  }, []);
+
+  // 解绑事件
+  const unbindEvents = useCallback((chartInstance: ChartInstance) => {
+    if (!chartInstance || !throttledHandlerRef.current) return;
+    try {
+      chartInstance.off('datazoom', throttledHandlerRef.current);
+    } catch (e) {
+      console.warn('[useDataZoom] Failed to unbind events:', e);
+    }
+  }, []);
+
+  // 清理：组件卸载时
+  useEffect(() => {
+    return () => {
+      const chart = chartRef.current;
+      if (chart) {
+        if (resetOnUnmount) {
+          unbindDataZoom(chart);
+        }
+        unbindEvents(chart);
+      }
+    };
+  }, [resetOnUnmount, unbindDataZoom, unbindEvents]);
+
+  return {
+    bindDataZoom,
+    setZoomRange,
+    resetZoom,
+    getZoomRange,
+    startValue: startValueRef,
+    endValue: endValueRef,
+    bindEvents,
+  };
+}
+
+// ============================================================================
+// 类型导出
+// ============================================================================
+
+export type {
+  UseDataZoomOptions,
+  UseDataZoomReturn,
+  DataZoomType,
+  ZoomRange,
+} from '../../../hooks/types';
+
+// ============================================================================
+// 导出
+// ============================================================================
+
+// useDataZoom 已在函数声明时导出

package/src/{hooks → core/utils/performance}/usePerformance.ts

@@ -3,12 +3,11 @@
  * 提供实时性能指标监控和报告功能
  */
 import { useState, useEffect, useCallback, useRef } from 'react';
-import { PerformanceAnalyzer, PerformanceMetricType, PerformanceMetric } from '../core/utils/performance';
 
 /**
  * 性能监控配置
  */
-export interface UsePerformanceOptions {
+export interface UseFpsMonitorOptions {
   /** 是否启用监控 */
   enabled?: boolean;
   /** 采样间隔 (ms) */
@@ -43,10 +42,20 @@ export interface PerformanceState {
   isMonitoring: boolean;
 }
 
+/**
+ * 性能报告条目
+ */
+export interface PerformanceReportEntry {
+  type: string;
+  value: number;
+  unit: string;
+  timestamp: number;
+}
+
 /**
  * 性能监控返回值
  */
-export interface UsePerformanceReturn {
+export interface UseFpsMonitorReturn {
   /** 性能状态 */
   state: PerformanceState;
   /** 开始监控 */
@@ -56,7 +65,7 @@ export interface UsePerformanceReturn {
   /** 重置统计数据 */
   reset: () => void;
   /** 获取性能报告 */
-  getReport: () => PerformanceMetric[];
+  getReport: () => PerformanceReportEntry[];
   /** FPS 告警回调 */
   onFpsWarning?: (fps: number) => void;
 }
@@ -66,7 +75,13 @@ export interface UsePerformanceReturn {
  * @param options 配置选项
  * @returns 性能监控接口
  */
-export function usePerformance(options: UsePerformanceOptions = {}): UsePerformanceReturn {
+/** @deprecated Use `UseFpsMonitorOptions` instead */
+export type UsePerformanceOptions = UseFpsMonitorOptions;
+
+/** @deprecated Use `UseFpsMonitorReturn` instead */
+export type UsePerformanceReturn = UseFpsMonitorReturn;
+
+export function useFpsMonitor(options: UseFpsMonitorOptions = {}): UseFpsMonitorReturn {
   const {
     enabled = true,
     sampleInterval = 1000,
@@ -77,11 +92,14 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
   } = 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 });
+  const fpsAccumulatorRef = useRef<{ frames: number; lastTime: number }>({
+    frames: 0,
+    lastTime: 0,
+  });
+  const reportHistoryRef = useRef<PerformanceReportEntry[]>([]);
 
   // State
   const [state, setState] = useState<PerformanceState>({
@@ -121,7 +139,9 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
 
     // 每秒计算一次 FPS
     if (now - fpsAccumulatorRef.current.lastTime >= 1000) {
-      const fps = Math.round((fpsAccumulatorRef.current.frames * 1000) / (now - fpsAccumulatorRef.current.lastTime));
+      const fps = Math.round(
+        (fpsAccumulatorRef.current.frames * 1000) / (now - fpsAccumulatorRef.current.lastTime)
+      );
       const history = fpsHistoryRef.current;
 
       // 更新历史
@@ -135,7 +155,7 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
       const minFps = Math.min(...history);
       const maxFps = Math.max(...history);
 
-      setState(prev => ({
+      setState((prev) => ({
         ...prev,
         fps,
         avgFps,
@@ -145,6 +165,14 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
         fpsHistory: [...history],
       }));
 
+      // 记录性能报告
+      reportHistoryRef.current.push({
+        type: 'fps',
+        value: fps,
+        unit: 'fps',
+        timestamp: now,
+      });
+
       // 重置计数器
       fpsAccumulatorRef.current.frames = 0;
       fpsAccumulatorRef.current.lastTime = now;
@@ -163,27 +191,17 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
     // 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 = [];
+    reportHistoryRef.current = [];
 
     // 开始 FPS 监控循环
     animationFrameRef.current = requestAnimationFrame(updateFps);
 
-    setState(prev => ({ ...prev, isMonitoring: true }));
-  }, [enabled, sampleInterval, updateFps]);
+    setState((prev) => ({ ...prev, isMonitoring: true }));
+  }, [enabled, updateFps]);
 
   /**
    * 停止监控
@@ -195,19 +213,16 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
       animationFrameRef.current = null;
     }
 
-    // 停止分析器
-    analyzerRef.current?.stop();
-
-    setState(prev => ({ ...prev, isMonitoring: false }));
+    setState((prev) => ({ ...prev, isMonitoring: false }));
   }, []);
 
   /**
    * 重置统计数据
    */
   const reset = useCallback(() => {
-    PerformanceAnalyzer.resetInstance();
     fpsHistoryRef.current = [];
-    setState(prev => ({
+    reportHistoryRef.current = [];
+    setState((prev) => ({
       ...prev,
       fps: 60,
       avgFps: 60,
@@ -221,16 +236,8 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
   /**
    * 获取性能报告
    */
-  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 [];
-    }
+  const getReport = useCallback((): PerformanceReportEntry[] => {
+    return reportHistoryRef.current.slice(-100); // 返回最近 100 条记录
   }, []);
 
   // 自动启动
@@ -254,10 +261,10 @@ export function usePerformance(options: UsePerformanceOptions = {}): UsePerforma
 }
 
 /**
- * 轻量级 FPS 监控 Hook
+ * 轻量级 FPS 计数器 Hook
  * 用于实时显示图表 FPS
  */
-export function useFpsMonitor(): number {
+export function useFpsCounter(): number {
   const [fps, setFps] = useState(60);
   const frameCountRef = useRef(0);
   const lastTimeRef = useRef(performance.now());
@@ -288,4 +295,5 @@ export function useFpsMonitor(): number {
   return fps;
 }
 
-export default usePerformance;
+/** @deprecated Use `useFpsMonitor` instead */
+export const usePerformance = useFpsMonitor;