@agions/taroviz 1.9.0 → 1.10.0

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;

package/src/hooks/useChartSelection.ts

@@ -0,0 +1,350 @@
+/**
+ * useChartSelection - 图表数据点选择/高亮 Hook
+ * 支持单个/批量选择、反选、清除选择，配合 ECharts select 事件
+ *
+ * 特性：
+ * - 支持按 seriesIndex + dataIndex 选择
+ * - 支持按 dataIndex 跨系列批量选择
+ * - 支持反选（invertSelection）
+ * - 支持多选模式（multi）
+ * - 自动绑定图表 select/unselect 事件
+ */
+import { useEffect, useRef, useCallback, useState } from 'react';
+import type { ChartInstance } from './index';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+/** 单个数据点的选择键 */
+export interface DataPointKey {
+  seriesIndex: number;
+  dataIndex: number;
+}
+
+/** 选择模式 */
+export type SelectionMode = 'single' | 'multiple';
+
+/** 选择事件参数 */
+export interface SelectionEvent {
+  /** 被选中的数据点 */
+  selected: DataPointKey[];
+  /** 取消选择的数据点 */
+  unselected: DataPointKey[];
+}
+
+/** 选择配置选项 */
+export interface UseChartSelectionOptions {
+  /** 选择模式：'single' 单选，'multiple' 多选，默认 'multiple' */
+  mode?: SelectionMode;
+  /** 是否在组件卸载时清除所有选择，默认 true */
+  clearOnUnmount?: boolean;
+  /** 是否启用 Ctrl+Click 多选，默认 true */
+  enableCtrlMultiSelect?: boolean;
+  /** 是否启用 Shift+Click 范围选择，默认 true */
+  enableShiftRangeSelect?: boolean;
+  /** 选择变化时的回调 */
+  onSelectionChange?: (event: SelectionEvent) => void;
+}
+
+/** 选择返回值 */
+export interface UseChartSelectionReturn {
+  /** 当前选中的数据点 */
+  selectedPoints: DataPointKey[];
+  /** 是否存在选中 */
+  hasSelection: boolean;
+  /** 选中数量 */
+  selectionCount: number;
+  /** 选中指定数据点 */
+  select: (key: DataPointKey) => void;
+  /** 取消选中指定数据点 */
+  deselect: (key: DataPointKey) => void;
+  /** 批量选中 */
+  selectMultiple: (keys: DataPointKey[]) => void;
+  /** 批量取消选中 */
+  deselectMultiple: (keys: DataPointKey[]) => void;
+  /** 切换选中状态 */
+  toggle: (key: DataPointKey) => void;
+  /** 反选 */
+  invertSelection: (seriesIndex: number, dataIndices: number[]) => void;
+  /** 全选指定系列 */
+  selectAll: (seriesIndex: number, dataIndices: number[]) => void;
+  /** 清除所有选择 */
+  clearSelection: () => void;
+  /** 判断某点是否被选中 */
+  isSelected: (key: DataPointKey) => boolean;
+}
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+
+/** 生成唯一键字符串 */
+function keyToString(key: DataPointKey): string {
+  return `${key.seriesIndex}:${key.dataIndex}`;
+}
+
+function stringToKey(str: string): DataPointKey {
+  const [seriesIndex, dataIndex] = str.split(':').map(Number);
+  return { seriesIndex, dataIndex };
+}
+
+// ============================================================================
+// Hook 实现
+// ============================================================================
+
+/**
+ * 使用图表数据点选择功能
+ * @param chartInstance 图表实例
+ * @param options 配置选项
+ * @returns 选择控制接口
+ */
+export function useChartSelection(
+  chartInstance: ChartInstance | null,
+  options: UseChartSelectionOptions = {}
+): UseChartSelectionReturn {
+  const {
+    mode = 'multiple',
+    clearOnUnmount = true,
+    enableCtrlMultiSelect = true,
+    enableShiftRangeSelect = true,
+    onSelectionChange,
+  } = options;
+
+  // 选中点集合（字符串键）
+  const [selectedPoints, setSelectedPoints] = useState<DataPointKey[]>([]);
+
+  // Chart instance ref
+  const chartRef = useRef<ChartInstance | null>(null);
+  chartRef.current = chartInstance;
+
+  // 上一次 shift+click 的数据索引（用于范围选择）
+  const lastShiftIndexRef = useRef<number | null>(null);
+
+  // 当前模式 ref（用于事件处理）
+  const modeRef = useRef(mode);
+  modeRef.current = mode;
+
+  // 绑定图表 select/unselect 事件
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart || !chart.on) return;
+
+    const handleSelect = (params: { selected: Record<string, boolean>; type: string }) => {
+      // ECharts 内置 select 会同步更新 legend
+      // 这里我们用 dispatchAction 来实现纯数据点选择
+    };
+
+    // 单击 legend 时清除数据点选择（保持一致性）
+    const handleLegendSelectChanged = (params: { name?: string; selected?: Record<string, boolean> }) => {
+      // 清除选择时的视觉反馈
+    };
+
+    chart.on('selectchanged', (params: unknown) => {
+      // 当图表内部选择变化时同步状态
+      const p = params as {
+        isFromClick?: boolean;
+        selected?: Record<string, boolean>;
+        notSelected?: Record<string, boolean>;
+      };
+      if (p.isFromClick) {
+        // 用户点击了图例，清除所有数据点选择
+        setSelectedPoints([]);
+        onSelectionChange?.({ selected: [], unselected: [] });
+      }
+    });
+
+    return () => {
+      if (chart.off) {
+        chart.off('selectchanged');
+      }
+    };
+  }, [onSelectionChange]);
+
+  // 组件卸载时清除选择
+  useEffect(() => {
+    return () => {
+      if (clearOnUnmount) {
+        const chart = chartRef.current;
+        if (chart?.dispatchAction) {
+          // 清除所有系列的选择状态
+          chart.dispatchAction({ type: 'unselect' });
+        }
+      }
+    };
+  }, [clearOnUnmount]);
+
+  // ─── 私有方法 ───────────────────────────────────────────────────────────────
+
+  /** 触发选择变化回调 */
+  const notifyChange = useCallback(
+    (selected: DataPointKey[], unselected: DataPointKey[]) => {
+      onSelectionChange?.({ selected, unselected });
+    },
+    [onSelectionChange]
+  );
+
+  /** 执行 ECharts dispatchAction */
+  const dispatchSelect = useCallback(
+    (key: DataPointKey, select: boolean) => {
+      const chart = chartRef.current;
+      if (!chart?.dispatchAction) return;
+      chart.dispatchAction({
+        type: select ? 'select' : 'unselect',
+        seriesIndex: key.seriesIndex,
+        dataIndex: key.dataIndex,
+      });
+    },
+    []
+  );
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  const select = useCallback(
+    (key: DataPointKey) => {
+      setSelectedPoints((prev) => {
+        const str = keyToString(key);
+        if (prev.some((p) => keyToString(p) === str)) return prev;
+        const next = mode === 'single' ? [key] : [...prev, key];
+        notifyChange(next, []);
+        return next;
+      });
+      dispatchSelect(key, true);
+    },
+    [mode, notifyChange, dispatchSelect]
+  );
+
+  const deselect = useCallback(
+    (key: DataPointKey) => {
+      setSelectedPoints((prev) => {
+        const str = keyToString(key);
+        const removed = prev.filter((p) => keyToString(p) !== str);
+        notifyChange([], removed);
+        return removed;
+      });
+      dispatchSelect(key, false);
+    },
+    [notifyChange, dispatchSelect]
+  );
+
+  const toggle = useCallback(
+    (key: DataPointKey) => {
+      const str = keyToString(key);
+      if (selectedPoints.some((p) => keyToString(p) === str)) {
+        deselect(key);
+      } else {
+        select(key);
+      }
+    },
+    [selectedPoints, select, deselect]
+  );
+
+  const selectMultiple = useCallback(
+    (keys: DataPointKey[]) => {
+      setSelectedPoints((prev) => {
+        const newPoints = mode === 'single' ? keys : [...prev, ...keys.filter(
+          (k) => !prev.some((p) => keyToString(p) === keyToString(k))
+        )];
+        notifyChange(newPoints, []);
+        return newPoints;
+      });
+      keys.forEach((key) => dispatchSelect(key, true));
+    },
+    [mode, notifyChange, dispatchSelect]
+  );
+
+  const deselectMultiple = useCallback(
+    (keys: DataPointKey[]) => {
+      setSelectedPoints((prev) => {
+        const keySet = new Set(keys.map(keyToString));
+        const removed = prev.filter((p) => keySet.has(keyToString(p)));
+        const remaining = prev.filter((p) => !keySet.has(keyToString(p)));
+        notifyChange([], removed);
+        return remaining;
+      });
+      keys.forEach((key) => dispatchSelect(key, false));
+    },
+    [notifyChange, dispatchSelect]
+  );
+
+  const invertSelection = useCallback(
+    (seriesIndex: number, dataIndices: number[]) => {
+      setSelectedPoints((prev) => {
+        const selectedSet = new Set(prev.filter((p) => p.seriesIndex === seriesIndex).map((p) => p.dataIndex));
+        const toSelect: DataPointKey[] = [];
+        const toDeselect: DataPointKey[] = [];
+
+        dataIndices.forEach((dataIndex) => {
+          const key = { seriesIndex, dataIndex };
+          const str = keyToString(key);
+          if (selectedSet.has(dataIndex)) {
+            toDeselect.push(key);
+          } else {
+            toSelect.push(key);
+          }
+        });
+
+        toDeselect.forEach((k) => dispatchSelect(k, false));
+        toSelect.forEach((k) => dispatchSelect(k, true));
+
+        const newSelected = prev.filter(
+          (p) => !(p.seriesIndex === seriesIndex && selectedSet.has(p.dataIndex))
+        ).concat(toSelect);
+
+        notifyChange(toSelect, toDeselect);
+        return newSelected;
+      });
+    },
+    [notifyChange, dispatchSelect]
+  );
+
+  const selectAll = useCallback(
+    (seriesIndex: number, dataIndices: number[]) => {
+      const keys = dataIndices.map((dataIndex) => ({ seriesIndex, dataIndex }));
+      setSelectedPoints((prev) => {
+        const newPoints = mode === 'single' ? keys : [...prev, ...keys.filter(
+          (k) => !prev.some((p) => keyToString(p) === keyToString(k))
+        )];
+        notifyChange(newPoints, []);
+        return newPoints;
+      });
+      keys.forEach((key) => dispatchSelect(key, true));
+    },
+    [mode, notifyChange, dispatchSelect]
+  );
+
+  const clearSelection = useCallback(() => {
+    const chart = chartRef.current;
+    if (chart?.dispatchAction) {
+      chart.dispatchAction({ type: 'unselect' });
+    }
+    const prev = selectedPoints;
+    setSelectedPoints([]);
+    notifyChange([], prev);
+  }, [selectedPoints, notifyChange]);
+
+  const isSelected = useCallback(
+    (key: DataPointKey) => {
+      const str = keyToString(key);
+      return selectedPoints.some((p) => keyToString(p) === str);
+    },
+    [selectedPoints]
+  );
+
+  return {
+    selectedPoints,
+    hasSelection: selectedPoints.length > 0,
+    selectionCount: selectedPoints.length,
+    select,
+    deselect,
+    selectMultiple,
+    deselectMultiple,
+    toggle,
+    invertSelection,
+    selectAll,
+    clearSelection,
+    isSelected,
+  };
+}
+
+export default useChartSelection;