@agions/taroviz 1.9.0 → 1.11.1

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;

package/src/hooks/useDataTransform.ts

@@ -4,32 +4,46 @@
  */
 import { useMemo } from 'react';
 import type { EChartsOption } from 'echarts';
+import {
+  DataItem,
+  DataSource,
+  AggregationType,
+  TimePeriod,
+  TransformMapping,
+  transformLineOrBar as utilsTransformLineOrBar,
+  transformPie as utilsTransformPie,
+  transformScatter as utilsTransformScatter,
+  transformRadar as utilsTransformRadar,
+  transformHeatmap as utilsTransformHeatmap,
+  groupByTime,
+  aggregateValues,
+} from './utils/dataTransformUtils';
+
+// Re-export types for external use
+export type { DataItem, DataSource, AggregationType, TimePeriod, TransformMapping };
 
 // ============================================================================
 // 类型定义
 // ============================================================================
 
-/** 原始数据条目 */
-export interface DataItem {
-  name?: string;
-  value?: number | number[];
-  [key: string]: unknown;
+/** 映射配置 */
+export interface MappingConfig {
+  /** 类别字段 (X轴) */
+  xField?: string;
+  /** 值字段 (Y轴) */
+  yField?: string;
+  /** 系列字段 */
+  seriesField?: string;
+  /** 大小字段 (用于散点图) */
+  sizeField?: string;
+  /** 颜色字段 */
+  colorField?: string;
+  /** 名称字段 (用于饼图等) */
+  nameField?: string;
+  /** 值字段 (用于饼图等) */
+  valueField?: string;
 }
 
-/** 数据源 */
-export interface DataSource {
-  categories?: (string | number)[];
-  series?: DataItem[];
-  rows?: Record<string, unknown>[];
-  columns?: string[];
-}
-
-/** 聚合方式 */
-export type AggregationType = 'sum' | 'average' | 'max' | 'min' | 'count' | 'first' | 'last';
-
-/** 时间周期 */
-export type TimePeriod = 'day' | 'week' | 'month' | 'quarter' | 'year';
-
 /** 转换选项 */
 export interface TransformOptions {
   /** 数据源 */
@@ -37,22 +51,7 @@ export interface TransformOptions {
   /** 图表类型 */
   chartType: 'line' | 'bar' | 'pie' | 'scatter' | 'radar' | 'heatmap';
   /** 映射配置 */
-  mapping?: {
-    /** 类别字段 (X轴) */
-    xField?: string;
-    /** 值字段 (Y轴) */
-    yField?: string;
-    /** 系列字段 */
-    seriesField?: string;
-    /** 大小字段 (用于散点图) */
-    sizeField?: string;
-    /** 颜色字段 */
-    colorField?: string;
-    /** 名称字段 (用于饼图等) */
-    nameField?: string;
-    /** 值字段 (用于饼图等) */
-    valueField?: string;
-  };
+  mapping?: MappingConfig;
   /** 聚合配置 */
   aggregation?: {
     field: string;
@@ -122,19 +121,19 @@ export function useDataTransform(options: TransformOptions): EChartsOption {
     switch (chartType) {
       case 'line':
       case 'bar':
-        return transformLineOrBar(data, chartType, mapping, extraConfig);
+        return utilsTransformLineOrBar(data, chartType, mapping, extraConfig);
 
       case 'pie':
-        return transformPie(data, mapping, extraConfig);
+        return utilsTransformPie(data, mapping, extraConfig);
 
       case 'scatter':
-        return transformScatter(data, mapping, extraConfig);
+        return utilsTransformScatter(data, mapping, extraConfig);
 
       case 'radar':
-        return transformRadar(data, mapping, extraConfig);
+        return utilsTransformRadar(data, mapping, extraConfig);
 
       case 'heatmap':
-        return transformHeatmap(data, mapping, extraConfig);
+        return utilsTransformHeatmap(data, mapping, extraConfig);
 
       default:
         return {};
@@ -244,252 +243,6 @@ export function useTimeSeriesTransform(options: TimeSeriesTransformOptions): ECh
   }, [data, dateField, valueField, groupField, period, aggregation, fillMissing, extraConfig]);
 }
 
-// ============================================================================
-// 辅助函数
-// ============================================================================
-
-function transformLineOrBar(
-  data: DataSource,
-  chartType: 'line' | 'bar',
-  mapping: TransformOptions['mapping'],
-  extraConfig: Partial<EChartsOption>
-): EChartsOption {
-  const { xField = 'name', yField = 'value', seriesField } = mapping || {};
-
-  const categories = data.categories || data.rows?.map((r) => String(r[xField])) || [];
-  const seriesData = data.series || data.rows || [];
-
-  if (seriesField) {
-    const groups = new Map<string, DataItem[]>();
-    seriesData.forEach((item) => {
-      const key = String((item as Record<string, unknown>)[seriesField] || 'default');
-      if (!groups.has(key)) groups.set(key, []);
-      groups.get(key)!.push(item);
-    });
-    const series = Array.from(groups.entries()).map(([name, items]) => ({
-      name,
-      type: chartType,
-      data: items.map((item) => (item as Record<string, unknown>)[yField] ?? 0),
-    }));
-    return {
-      xAxis: { type: 'category', data: categories },
-      yAxis: { type: 'value' },
-      series,
-      ...extraConfig,
-    };
-  }
-
-  const series = [
-    {
-      type: chartType as 'line' | 'bar',
-      data: seriesData.map((item) => (item as Record<string, unknown>)[yField] ?? 0),
-    },
-  ];
-
-  return {
-    xAxis: { type: 'category', data: categories },
-    yAxis: { type: 'value' },
-    series,
-    ...extraConfig,
-  };
-}
-
-function transformPie(
-  data: DataSource,
-  mapping: TransformOptions['mapping'],
-  extraConfig: Partial<EChartsOption>
-): EChartsOption {
-  const { nameField = 'name', valueField = 'value' } = mapping || {};
-
-  const seriesData: Array<{ name: string; value: number }> = (data.series || data.rows || []).map(
-    (item) => ({
-      name: String((item as Record<string, unknown>)[nameField] || ''),
-      value: Number((item as Record<string, unknown>)[valueField]) || 0,
-    })
-  );
-
-  return {
-    series: [{ type: 'pie', radius: '60%', data: seriesData }],
-    ...extraConfig,
-  };
-}
-
-function transformScatter(
-  data: DataSource,
-  mapping: TransformOptions['mapping'],
-  extraConfig: Partial<EChartsOption>
-): EChartsOption {
-  const { xField = 'x', yField = 'y', sizeField } = mapping || {};
-
-  const seriesData = (data.series || data.rows || []).map((item) => {
-    const record = item as Record<string, unknown>;
-    const point: (number | string)[] = [Number(record[xField]) || 0, Number(record[yField]) || 0];
-    if (sizeField) point.push(Number(record[sizeField]) || 1);
-    return point;
-  });
-
-  return {
-    xAxis: { type: 'value', scale: true },
-    yAxis: { type: 'value', scale: true },
-    series: [{ type: 'scatter', data: seriesData }],
-    ...extraConfig,
-  };
-}
-
-function transformRadar(
-  data: DataSource,
-  mapping: TransformOptions['mapping'],
-  extraConfig: Partial<EChartsOption>
-): EChartsOption {
-  const { nameField = 'name', valueField = 'value' } = mapping || {};
-
-  const indicators = (data.series || data.rows || []).map((item) => {
-    const record = item as Record<string, unknown>;
-    return {
-      name: String(record[nameField] || ''),
-      max: Math.max(Number(record[valueField]) || 100, 100),
-    };
-  });
-
-  const values = (data.series || data.rows || []).map(
-    (item) => Number((item as Record<string, unknown>)[valueField]) || 0
-  );
-
-  return {
-    radar: { indicator: indicators },
-    series: [{ type: 'radar', data: [{ value: values }] }],
-    ...extraConfig,
-  };
-}
-
-function transformHeatmap(
-  data: DataSource,
-  mapping: TransformOptions['mapping'],
-  extraConfig: Partial<EChartsOption>
-): EChartsOption {
-  const { xField = 'x', yField = 'y', valueField = 'value' } = mapping || {};
-
-  const xCategories = [
-    ...new Set(
-      (data.series || data.rows || []).map((d) => String((d as Record<string, unknown>)[xField]))
-    ),
-  ];
-  const yCategories = [
-    ...new Set(
-      (data.series || data.rows || []).map((d) => String((d as Record<string, unknown>)[yField]))
-    ),
-  ];
-
-  const seriesData = (data.series || data.rows || []).map((item) => {
-    const record = item as Record<string, unknown>;
-    const xIndex = xCategories.indexOf(String(record[xField]));
-    const yIndex = yCategories.indexOf(String(record[yField]));
-    return [xIndex, yIndex, Number(record[valueField]) || 0];
-  });
-
-  return {
-    xAxis: { type: 'category', data: xCategories },
-    yAxis: { type: 'category', data: yCategories },
-    visualMap: { min: 0, calculable: true },
-    series: [{ type: 'heatmap', data: seriesData }],
-    ...extraConfig,
-  };
-}
-
-function groupByTime(
-  data: DataItem[],
-  dateField: string,
-  period: TimePeriod
-): Record<string, DataItem[]> {
-  return data.reduce(
-    (acc, item) => {
-      const date = new Date(String((item as Record<string, unknown>)[dateField]));
-      let key: string;
-
-      switch (period) {
-        case 'day':
-          key = date.toISOString().split('T')[0];
-          break;
-        case 'week': {
-          const week = getWeekNumber(date);
-          key = `${date.getFullYear()}-W${week}`;
-          break;
-        }
-        case 'month':
-          key = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
-          break;
-        case 'quarter':
-          key = `${date.getFullYear()}-Q${Math.ceil((date.getMonth() + 1) / 3)}`;
-          break;
-        case 'year':
-          key = String(date.getFullYear());
-          break;
-        default:
-          key = date.toISOString().split('T')[0];
-      }
-
-      if (!acc[key]) acc[key] = [];
-      acc[key].push(item);
-      return acc;
-    },
-    {} as Record<string, DataItem[]>
-  );
-}
-
-function getWeekNumber(date: Date): number {
-  const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
-  const dayNum = d.getUTCDay() || 7;
-  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
-  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
-  return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
-}
-
-function aggregateValues(
-  items: DataItem[],
-  field: string,
-  method: AggregationType,
-  fillMissing?: 'zero' | 'forward' | 'interpolate'
-): number {
-  if (items.length === 0) {
-    if (fillMissing === 'zero') return 0;
-    return NaN;
-  }
-
-  const values = items.map((item) => Number((item as Record<string, unknown>)[field]) || 0);
-
-  switch (method) {
-    case 'sum': {
-      let sum = 0;
-      for (let i = 0; i < values.length; i++) sum += values[i];
-      return sum;
-    }
-    case 'average': {
-      if (values.length === 0) return 0;
-      let sum = 0;
-      for (let i = 0; i < values.length; i++) sum += values[i];
-      return sum / values.length;
-    }
-    case 'max': {
-      let max = values[0];
-      for (let i = 1; i < values.length; i++) if (values[i] > max) max = values[i];
-      return max;
-    }
-    case 'min': {
-      let min = values[0];
-      for (let i = 1; i < values.length; i++) if (values[i] < min) min = values[i];
-      return min;
-    }
-    case 'count':
-      return values.length;
-    case 'first':
-      return values[0];
-    case 'last':
-      return values[values.length - 1];
-    default:
-      return values[0];
-  }
-}
-
 // ============================================================================
 // 导出
 // ============================================================================