@agions/taroviz 1.6.0 → 1.9.0

package/src/hooks/useDataZoom.ts

@@ -0,0 +1,323 @@
+/**
+ * useDataZoom - 数据缩放 Hook
+ * 控制图表的数据缩放区域（dataZoom），支持拖拽和滚轮缩放
+ */
+import { useRef, useCallback, useEffect } from 'react';
+import type { RefObject } from 'react';
+import type { ChartInstance } from './index';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+/** dataZoom 类型 */
+export type DataZoomType = 'inside' | 'slider';
+
+/** dataZoom 配置选项 */
+export interface UseDataZoomOptions {
+  /** dataZoom 类型: inside=内置型(滚轮/双指), slider=滑块型 */
+  type?: DataZoomType;
+  /** 起始位置 (0-100) */
+  start?: number;
+  /** 结束位置 (0-100) */
+  end?: number;
+  /** 最小跨度 (0-100) */
+  minSpan?: number;
+  /** 最大跨度 (0-100) */
+  maxSpan?: number;
+  /** 是否锁定缩放 */
+  zoomLock?: boolean;
+  /** 节流时间 (ms) */
+  throttle?: number;
+  /** 是否禁用 */
+  disabled?: boolean;
+  /** 是否显示缩放痕迹 */
+  brushSelect?: boolean;
+  /** 缩放模式: 'scale' | 'mix' */
+  zoomMode?: 'scale' | 'mix';
+  /** 是否在组件卸载时重置缩放 */
+  resetOnUnmount?: boolean;
+  /** 缩放变化回调 */
+  onZoomChange?: (range: { start: number; end: number }) => void;
+}
+
+/** 缩放范围 */
+export interface ZoomRange {
+  start: number;
+  end: number;
+}
+
+/** dataZoom 返回值 */
+export interface UseDataZoomReturn {
+  /** 绑定 dataZoom 到图表实例 */
+  bindDataZoom: (chartInstance: ChartInstance) => void;
+  /** 设置缩放范围 */
+  setZoomRange: (start: number, end: number) => void;
+  /** 重置缩放到初始状态 */
+  resetZoom: () => void;
+  /** 获取当前缩放范围 */
+  getZoomRange: () => ZoomRange;
+  /** 起始位置的原始值 (Ref) */
+  startValue: RefObject<number | string | Date | undefined>;
+  /** 结束位置的原始值 (Ref) */
+  endValue: RefObject<number | string | Date | undefined>;
+  /** 绑定事件处理 */
+  bindEvents: (chartInstance: ChartInstance) => void;
+  /** 缩放变化回调 */
+  onZoomChange?: (range: ZoomRange) => void;
+}
+
+// ============================================================================
+// Hook 实现
+// ============================================================================
+
+/**
+ * 使用图表数据缩放
+ * @param options 配置选项
+ * @returns dataZoom 操作接口
+ */
+export function useDataZoom(options: UseDataZoomOptions = {}): UseDataZoomReturn {
+  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);
+  const throttledHandlerRef = useRef<((...args: any[]) => void) | null>(null);
+
+  // 节流处理
+  const throttledCallback = useCallback(
+    <T extends (...args: any[]) => void>(fn: T): T => {
+      let lastCall = 0;
+      return ((...args: any[]) => {
+        const now = Date.now();
+        if (now - lastCall >= throttle) {
+          lastCall = now;
+          fn(...args);
+        }
+      }) as T;
+    },
+    [throttle]
+  );
+
+  // 构建 dataZoom 配置
+  const buildDataZoomConfig = useCallback(() => {
+    const config: any[] = [];
+
+    // 内置型 dataZoom
+    if (type === 'inside' || zoomMode === 'mix') {
+      config.push({
+        type: 'inside',
+        start,
+        end,
+        zoomLock,
+        disabled,
+        zoomOnMouseWheel: true,
+        moveOnMouseMove: false,
+        moveOnMouseWheel: false,
+        preventDefaultMouseMove: true,
+      });
+    }
+
+    // 滑块型 dataZoom
+    if (type === 'slider' || zoomMode === 'mix') {
+      config.push({
+        type: 'slider',
+        start,
+        end,
+        minSpan,
+        maxSpan,
+        zoomLock,
+        disabled,
+        show: true,
+        brushSelect,
+        throttle,
+      });
+    }
+
+    return config;
+  }, [type, start, end, minSpan, maxSpan, zoomLock, disabled, brushSelect, throttle]);
+
+  // 绑定 dataZoom 到图表
+  const bindDataZoom = useCallback(
+    (chartInstance: ChartInstance) => {
+      if (!chartInstance || isBindingRef.current) return;
+
+      isBindingRef.current = true;
+      chartRef.current = chartInstance;
+
+      try {
+        // 设置 dataZoom 配置
+        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 {
+        // 通过 dispatchAction 关闭 dataZoom
+        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(() => {
+    setZoomRange(start, end);
+  }, [setZoomRange, start, end]);
+
+  // 获取当前缩放范围
+  const getZoomRange = useCallback((): ZoomRange => {
+    const chart = chartRef.current;
+    if (!chart) {
+      return { start, end };
+    }
+
+    try {
+      const option = chart.getOption?.();
+      const dataZoom = option?.dataZoom as any[];
+      if (Array.isArray(dataZoom) && dataZoom.length > 0) {
+        // 优先获取 inside 类型的范围
+        const insideZoom = dataZoom.find((dz: any) => dz.type === 'inside');
+        const sliderZoom = dataZoom.find((dz: any) => dz.type === 'slider');
+        const zoom = insideZoom || sliderZoom || dataZoom[0];
+        return {
+          start: zoom.start ?? start,
+          end: zoom.end ?? end,
+        };
+      }
+    } catch (e) {
+      console.warn('[useDataZoom] Failed to get zoom range:', e);
+    }
+
+    return { start, end };
+  }, [start, end]);
+
+  // 绑定事件
+  const bindEvents = useCallback(
+    (chartInstance: ChartInstance) => {
+      if (!chartInstance) return;
+
+      // 创建缩放变化处理器
+      const handleZoomChange = (params: any) => {
+        if (disabled) return;
+
+        const { start: newStart, end: newEnd } = params || {};
+        if (newStart !== undefined) startValueRef.current = newStart;
+        if (newEnd !== undefined) endValueRef.current = newEnd;
+
+        onZoomChange?.({ start: newStart ?? start, end: newEnd ?? end });
+      };
+
+      // 使用节流包装
+      throttledHandlerRef.current = throttledCallback(handleZoomChange);
+
+      try {
+        // 监听 dataZoom 事件
+        chartInstance.on('datazoom', throttledHandlerRef.current);
+      } catch (e) {
+        console.warn('[useDataZoom] Failed to bind events:', e);
+      }
+    },
+    [disabled, onZoomChange, throttledCallback]
+  );
+
+  // 解绑事件
+  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 default useDataZoom;

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;

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * TaroViz - 基于 Taro 和 ECharts 的多端图表组件库
- * @version 1.6.0
+ * @version 1.7.0
  */
 
 // 核心组件
@@ -59,6 +59,25 @@ export { default as WordCloudChart } from './charts/wordcloud';
 export { default as BoxplotChart } from './charts/boxplot';
 export { default as ParallelChart } from './charts/parallel';
 
+// v1.7.0 新增组件
+export { DataFilter, type DataFilterProps, type FilterField, type FilterValues } from './components/DataFilter';
+export {
+  createDrillDown,
+  canDrillDown,
+  buildHierarchy,
+  createRegionDrillDown,
+  createCategoryDrillDown,
+  type DrillDownConfig,
+  type DrillDownSource,
+  type DrillDownReturn,
+  type DrillDownEventParams,
+  type DrillUpEventParams,
+} from './core/utils/drillDown';
+
+// v1.7.0 新增图表组件
+export { default as LiquidChart } from './charts/liquid';
+export { default as TreeChart } from './charts/tree';
+
 // 适配器
 export { getAdapter, detectPlatform, getEnv } from './adapters';
 export { default as H5Adapter } from './adapters/h5';
@@ -152,10 +171,14 @@ export {
   useDataTransform,
   useTableTransform,
   useTimeSeriesTransform,
+  // v1.7.0 新增 Hooks
+  useDataZoom,
+  useChartConnect,
+  useChartDownload,
 } from './hooks';
 
 /**
  * 库信息
  */
 export const name = 'taroviz';
-export const version = '1.6.0';
+export const version = '1.7.0';

package/src/themes/__tests__/index.test.ts

@@ -1,4 +1,4 @@
-import { getTheme, registerTheme, defaultTheme, darkTheme } from '../index';
+import { getTheme, registerTheme, defaultTheme, darkTheme, getThemeByName } from '../index';
 
 describe('Theme System', () => {
   describe('getTheme', () => {
@@ -11,7 +11,7 @@ describe('Theme System', () => {
       const result = getTheme({ darkMode: true });
       expect(result.darkMode).toBe(true);
       expect(result.theme).toBe('dark');
-      expect(result.backgroundColor).toBe('#0f1117');
+      expect(result.backgroundColor).toBe('#1a1a2e');
     });
 
     it('should merge custom options with defaultTheme', () => {
@@ -50,16 +50,10 @@ describe('Theme System', () => {
   });
 
   describe('registerTheme', () => {
-    it('should log when registering a theme', () => {
-      // Mock console.log
-      const consoleSpy = jest.spyOn(console, 'log').mockImplementation();
-
+    it('should register a theme', () => {
       registerTheme('custom-theme', { backgroundColor: '#123' });
-
-      expect(consoleSpy).toHaveBeenCalledWith('Registering theme: custom-theme');
-
-      // Restore console.log
-      consoleSpy.mockRestore();
+      const result = getThemeByName('custom-theme');
+      expect(result?.backgroundColor).toBe('#123');
     });
   });
 
@@ -70,8 +64,8 @@ describe('Theme System', () => {
       expect(defaultTheme).toHaveProperty('colors');
       expect(Array.isArray(defaultTheme.colors)).toBe(true);
       expect(defaultTheme.colors).toHaveLength(9);
-      expect(defaultTheme).toHaveProperty('backgroundColor', 'transparent');
-      expect(defaultTheme).toHaveProperty('textColor', '#333');
+      expect(defaultTheme).toHaveProperty('backgroundColor', '#ffffff');
+      expect(defaultTheme).toHaveProperty('textColor', '#333333');
       expect(defaultTheme).toHaveProperty('fontFamily');
     });
   });

package/src/themes/index.ts

@@ -871,3 +871,6 @@ export default {
   getLightThemes,
   getDarkThemes,
 };
+
+export { useAutoTheme } from './useAutoTheme';
+export type { UseAutoThemeOptions } from './useAutoTheme';