@agions/taroviz 1.11.1 → 2.0.3

package/src/hooks/types.ts

@@ -0,0 +1,189 @@
+/**
+ * Hooks 共享类型定义
+ */
+import type { EChartsOption } from 'echarts';
+
+// ============================================================================
+// 事件参数类型
+// ============================================================================
+
+/** click/hover 事件参数 */
+export interface ChartPointerEventParams {
+  seriesIndex?: number;
+  dataIndex?: number;
+  name?: string | number;
+  value?: unknown;
+  [key: string]: unknown;
+}
+
+/** select 事件参数 */
+export interface ChartSelectEventParams {
+  seriesIndex?: number;
+  dataIndex?: number;
+  [key: string]: unknown;
+}
+
+/** dataZoom 事件参数 */
+export interface ChartDataZoomEventParams {
+  start?: number;
+  end?: number;
+  dataZoomIndex?: number;
+  dataZoomIndexs?: number[];
+  [key: string]: unknown;
+}
+
+/** 事件处理器 */
+export type EventHandler = (params?: unknown) => void;
+
+// ============================================================================
+// useChartConnect 类型
+// ============================================================================
+
+/** 联动事件类型 */
+export type ConnectEventType = 'click' | 'hover' | 'select' | 'dataZoom';
+
+/** 联动事件参数（联合类型） */
+export type ConnectEventParams =
+  | ({ eventType: 'click' } & ChartPointerEventParams)
+  | ({ eventType: 'hover' } & ChartPointerEventParams)
+  | ({ eventType: 'select' } & ChartSelectEventParams)
+  | ({ eventType: 'dataZoom' } & ChartDataZoomEventParams);
+
+/** 联动配置选项 */
+export interface UseChartConnectOptions {
+  chartIds?: string[];
+  events?: ConnectEventType[];
+  autoBind?: boolean;
+  groupName?: string;
+  disabled?: boolean;
+  onConnect?: (
+    sourceId: string,
+    targetId: string,
+    payload: { eventType: ConnectEventType; params: unknown }
+  ) => void;
+  eventFilter?: (event: string, params: unknown) => boolean;
+}
+
+/** 联动返回值 */
+export interface UseChartConnectReturn {
+  connect: (chartInstance: ChartInstance, chartId?: string) => void;
+  disconnect: (chartInstance: ChartInstance, chartId?: string) => void;
+  dispatchConnect: (
+    sourceId: string,
+    payload: {
+      eventType: ConnectEventType;
+      params: ChartPointerEventParams | ChartSelectEventParams | ChartDataZoomEventParams;
+    }
+  ) => void;
+  connectAll: (charts: Array<{ instance: ChartInstance; id: string }>) => void;
+  disconnectAll: () => void;
+  isConnected: boolean;
+}
+
+// ============================================================================
+// useDataZoom 类型
+// ============================================================================
+
+/** dataZoom 类型 */
+export type DataZoomType = 'inside' | 'slider';
+
+/** dataZoom 配置选项 */
+export interface UseDataZoomOptions {
+  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;
+}
+
+/** 缩放范围 */
+export interface ZoomRange {
+  start: number;
+  end: number;
+}
+
+/** dataZoom 返回值 */
+export interface UseDataZoomReturn {
+  bindDataZoom: (chartInstance: ChartInstance) => void;
+  setZoomRange: (start: number, end: number) => void;
+  resetZoom: () => void;
+  getZoomRange: () => ZoomRange;
+  startValue: import('react').RefObject<number | string | Date | undefined>;
+  endValue: import('react').RefObject<number | string | Date | undefined>;
+  bindEvents: (chartInstance: ChartInstance) => void;
+  onZoomChange?: (range: ZoomRange) => void;
+}
+
+// ============================================================================
+// ChartInstance
+// ============================================================================
+
+/** 图表实例类型 */
+export interface ChartInstance {
+  setOption: (option: EChartsOption, notMerge?: boolean, lazyUpdate?: boolean) => void;
+  getOption: () => EChartsOption;
+  resize: (option?: { width?: number | string; height?: number | string }) => void;
+  on: (event: string, handler: EventHandler) => void;
+  off: (event: string, handler?: EventHandler) => void;
+  showLoading: (opts?: LoadingOptions) => void;
+  hideLoading: () => void;
+  dispose: () => void;
+  isDisposed: () => boolean;
+  getWidth: () => number;
+  getHeight: () => number;
+  getDom: () => HTMLElement;
+  getDataURL?: (options?: {
+    type?: string;
+    pixelRatio?: number;
+    backgroundColor?: string;
+  }) => string;
+  getSvgData?: () => string;
+  getCompressedDataURL?: (options?: { seriesIndex?: number; dimension?: number }) => string;
+  clear?: () => void;
+  dispatchAction?: (action: { type: string; [key: string]: unknown }) => void;
+  group?: string;
+  [key: string]: unknown;
+}
+
+/** 加载选项 */
+export interface LoadingOptions {
+  text?: string;
+  color?: string;
+  textColor?: string;
+  maskColor?: string;
+  zlevel?: number;
+}
+
+// ============================================================================
+// 图表配置类型
+// ============================================================================
+
+/** 图表配置 */
+export interface ChartConfig {
+  width?: number | string;
+  height?: number | string;
+  renderer?: 'canvas' | 'svg';
+  theme?: string | Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/** 数据转换器 */
+export type DataTransformer<T = unknown> = (data: T) => EChartsOption;
+
+/** 响应式断点 */
+export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+/** 断点配置 */
+export interface BreakpointConfig {
+  width: number;
+}
+
+/** 主题切换回调 */
+export type ThemeChangeCallback = (theme: string | Record<string, unknown>) => void;

package/src/hooks/useChartAutoResize.ts

@@ -0,0 +1,73 @@
+/**
+ * useChartAutoResize - 图表自适应 Hook
+ * 监听容器尺寸变化并自动调整图表大小
+ */
+import { useEffect, useRef } from 'react';
+import type { ChartInstance } from './types';
+
+/**
+ * 图表自适应 Hook
+ * @param instance 图表实例
+ * @param options 配置选项
+ */
+export function useResize(
+  instance: ChartInstance | null,
+  options?: {
+    /** 延迟时间 (ms) */
+    delay?: number;
+    /** 最小宽度 */
+    minWidth?: number;
+    /** 最小高度 */
+    minHeight?: number;
+    /** 是否启用 */
+    enabled?: boolean;
+  }
+) {
+  const { delay = 300, minWidth, minHeight, enabled = true } = options || {};
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>();
+
+  useEffect(() => {
+    if (!instance || !enabled) {
+      return;
+    }
+
+    const handleResize = () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      timeoutRef.current = setTimeout(() => {
+        try {
+          const dom = instance.getDom?.();
+          if (dom) {
+            const { clientWidth, clientHeight } = dom;
+            if (minWidth && clientWidth < minWidth) return;
+            if (minHeight && clientHeight < minHeight) return;
+          }
+          instance.resize?.();
+        } catch (e) {
+          console.warn('Failed to resize chart:', e);
+        }
+      }, delay);
+    };
+
+    window.addEventListener('resize', handleResize);
+
+    // 创建一个 ResizeObserver 来监听容器大小变化
+    const dom = instance.getDom?.();
+    if (dom && typeof ResizeObserver !== 'undefined') {
+      const observer = new ResizeObserver(handleResize);
+      observer.observe(dom);
+      return () => {
+        observer.disconnect();
+        window.removeEventListener('resize', handleResize);
+        if (timeoutRef.current) clearTimeout(timeoutRef.current);
+      };
+    }
+
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      if (timeoutRef.current) clearTimeout(timeoutRef.current);
+    };
+  }, [instance, delay, minWidth, minHeight, enabled]);
+}

package/src/hooks/useChartConnect.ts

@@ -1,57 +1,36 @@
 /**
  * useChartConnect - 图表联动 Hook
  * 实现多个图表之间的联动（chartConnect），当一个图表被操作时，其他联动图表同步变化
+ *
+ * @refactor 已拆分为多个辅助函数，详见 chartConnectHelpers.ts
  */
-import { useRef, useCallback, useEffect } from 'react';
-import type { ChartInstance } from './index';
+import { useRef, useCallback, useEffect, useMemo } from 'react';
+import type {
+  ChartInstance,
+  UseChartConnectOptions,
+  UseChartConnectReturn,
+  ConnectEventType,
+} from './types';
+import {
+  createConnectHandler,
+  dispatchToOthers,
+  bindChartEvents,
+  unbindChartEvents,
+  connectChart,
+  disconnectChart,
+  connectAllCharts,
+  disconnectAllCharts,
+  dispatchConnectEvent,
+  type ChartConnectItem,
+  type EventHandlersMap,
+} from './chartConnectHelpers';
 
 // ============================================================================
-// 类型定义
+// 导出共享类型（从 types.ts re-export）
 // ============================================================================
 
-/** 联动事件类型 */
-export type ConnectEventType = 'click' | 'hover' | 'select' | 'dataZoom';
-
-/** 联动配置选项 */
-export interface UseChartConnectOptions {
-  /** 要绑定的图表 ID 列表 */
-  chartIds: string[];
-  /** 联动触发的事件类型 */
-  events?: ConnectEventType[];
-  /** 是否自动绑定/解绑 */
-  autoBind?: boolean;
-  /** 联动组名称 */
-  groupName?: string;
-  /** 是否禁用 */
-  disabled?: boolean;
-  /** 联动回调 */
-  onConnect?: (sourceId: string, targetId: string, payload: any) => void;
-  /** 事件过滤函数 */
-  eventFilter?: (event: string, params: any) => boolean;
-}
-
-/** 图表联动项 */
-interface ChartConnectItem {
-  instance: ChartInstance;
-  id: string;
-  handlers: Map<string, any>;
-}
-
-/** 联动返回值 */
-export interface UseChartConnectReturn {
-  /** 绑定图表到联动组 */
-  connect: (chartInstance: ChartInstance, chartId?: string) => void;
-  /** 解除图表联动 */
-  disconnect: (chartInstance: ChartInstance, chartId?: string) => void;
-  /** 触发联动事件 */
-  dispatchConnect: (sourceId: string, payload: any) => void;
-  /** 批量连接图表 */
-  connectAll: (charts: Array<{ instance: ChartInstance; id: string }>) => void;
-  /** 批量断开图表 */
-  disconnectAll: () => void;
-  /** 联动组是否已连接 */
-  isConnected: boolean;
-}
+/** 联动配置选项（从 types.ts 导出） */
+export type { UseChartConnectOptions, UseChartConnectReturn } from './types';
 
 // ============================================================================
 // Hook 实现
@@ -63,9 +42,13 @@ export interface UseChartConnectReturn {
  * @returns 图表联动操作接口
  */
 export function useChartConnect(options: UseChartConnectOptions): UseChartConnectReturn {
+  const defaultEvents = useMemo<ConnectEventType[]>(
+    () => ['click', 'hover', 'select', 'dataZoom'],
+    []
+  );
   const {
     chartIds = [],
-    events = ['click', 'hover', 'select', 'dataZoom'],
+    events = defaultEvents,
     autoBind = false,
     groupName,
     disabled = false,
@@ -74,180 +57,93 @@ export function useChartConnect(options: UseChartConnectOptions): UseChartConnec
   } = options;
 
   // Refs
-  const chartsRef = useRef<Map<string, ChartConnectItem>>(new Map());
+  // 使用 useMemo 缓存初始值，避免每次渲染都创建新 Map
+  const chartsRef = useRef<Map<string, ChartConnectItem>>(
+    (() => {
+      const initialMap = new Map();
+      return initialMap;
+    })()
+  );
   const connectedRef = useRef(false);
   const optionsRef = useRef(options);
   optionsRef.current = options;
 
-  // 存储事件处理器的映射
-  const eventHandlersRef = useRef<Map<string, Map<string, any>>>(new Map());
+  const eventHandlersRef = useRef<EventHandlersMap>(
+    (() => {
+      const initialMap = new Map();
+      return initialMap;
+    })()
+  );
 
   /**
    * 创建联动事件处理器
    */
-  const createConnectHandler = useCallback(
+  const createConnectHandlerCallback = useCallback(
     (sourceId: string, eventType: ConnectEventType) => {
-      return (params: any) => {
-        if (disabled) return;
-
-        // 应用事件过滤器
-        if (eventFilter && !eventFilter(eventType, params)) {
-          return;
-        }
-
-        // 分发联动事件到所有其他图表
-        dispatchToOthers(sourceId, eventType, params);
-
-        // 触发回调
-        const currentOptions = optionsRef.current;
-                if (currentOptions.onConnect) {
-          chartsRef.current.forEach((item, targetId) => {
-            if (targetId !== sourceId) {
-              currentOptions.onConnect?.(sourceId, targetId, { eventType, params });
-            }
-          });
-        }
-      };
+      return createConnectHandler(
+        sourceId,
+        eventType,
+        disabled,
+        eventFilter,
+        chartsRef,
+        optionsRef
+      );
     },
-    [disabled, eventFilter]
+    [disabled, eventFilter, chartsRef, optionsRef]
   );
 
   /**
    * 分发事件到其他图表
    */
-  const dispatchToOthers = useCallback(
-    (sourceId: string, eventType: ConnectEventType, params: any) => {
-      chartsRef.current.forEach((item, targetId) => {
-        if (targetId === sourceId) return;
-
-        try {
-          switch (eventType) {
-            case 'click':
-              item.instance.dispatchAction?.({
-                type: 'showTip',
-                seriesIndex: params?.seriesIndex,
-                dataIndex: params?.dataIndex,
-              });
-              break;
-
-            case 'hover':
-              item.instance.dispatchAction?.({
-                type: 'showTip',
-                seriesIndex: params?.seriesIndex,
-                dataIndex: params?.dataIndex,
-              });
-              break;
-
-            case 'select':
-              item.instance.dispatchAction?.({
-                type: 'toggleSelect',
-                seriesIndex: params?.seriesIndex,
-                dataIndex: params?.dataIndex,
-              });
-              break;
-
-            case 'dataZoom':
-              item.instance.dispatchAction?.({
-                type: 'dataZoom',
-                start: params?.start,
-                end: params?.end,
-                dataZoomIndex: params?.dataZoomIndex,
-                dataZoomIndexs: params?.dataZoomIndexs,
-              });
-              break;
-
-            default:
-              break;
-          }
-        } catch (e) {
-          console.warn(`[useChartConnect] Failed to dispatch ${eventType} to ${targetId}:`, e);
-        }
-      });
+  const dispatchToOthersCallback = useCallback(
+    (sourceId: string, eventType: ConnectEventType, params: unknown) => {
+      dispatchToOthers(sourceId, eventType, params, chartsRef);
     },
-    []
+    [chartsRef]
   );
 
   /**
    * 绑定单个图表的联动事件
    */
-  const bindChartEvents = useCallback(
+  const bindChartEventsCallback = useCallback(
     (chartInstance: ChartInstance, chartId: string) => {
-      if (!chartInstance) return;
-
-      const handlers = new Map<string, any>();
-
-      // 为每个事件类型创建并绑定处理器
-      events.forEach((eventType) => {
-        const handler = createConnectHandler(chartId, eventType);
-        handlers.set(eventType, handler);
-
-        try {
-          chartInstance.on(eventType, handler);
-        } catch (e) {
-          console.warn(`[useChartConnect] Failed to bind ${eventType} event:`, e);
-        }
-      });
-
-      eventHandlersRef.current.set(chartId, handlers);
+      bindChartEvents(
+        chartInstance,
+        chartId,
+        events,
+        createConnectHandlerCallback,
+        eventHandlersRef
+      );
     },
-    [events, createConnectHandler]
+    [events, createConnectHandlerCallback, eventHandlersRef]
   );
 
   /**
    * 解绑单个图表的联动事件
    */
-  const unbindChartEvents = useCallback((chartId: string) => {
-    const handlers = eventHandlersRef.current.get(chartId);
-    if (!handlers) return;
-
-    const chartItem = chartsRef.current.get(chartId);
-    if (!chartItem) return;
-
-    handlers.forEach((handler, eventType) => {
-      try {
-        chartItem.instance.off(eventType, handler);
-      } catch (e) {
-        console.warn(`[useChartConnect] Failed to unbind ${eventType} event:`, e);
-      }
-    });
-
-    eventHandlersRef.current.delete(chartId);
-  }, []);
+  const unbindChartEventsCallback = useCallback(
+    (chartId: string) => {
+      unbindChartEvents(chartId, eventHandlersRef, chartsRef);
+    },
+    [eventHandlersRef, chartsRef]
+  );
 
   /**
    * 绑定图表到联动组
    */
   const connect = useCallback(
     (chartInstance: ChartInstance, chartId?: string) => {
-      const id = chartId || `chart_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-
-      // 检查是否已连接
-      if (chartsRef.current.has(id)) {
-        console.warn(`[useChartConnect] Chart ${id} is already connected`);
-        return;
-      }
-
-      // 存储图表实例
-      chartsRef.current.set(id, {
-        instance: chartInstance,
-        id,
-        handlers: new Map(),
-      });
-
-      // 绑定事件
-      bindChartEvents(chartInstance, id);
-      connectedRef.current = true;
-
-      // 如果有 groupName，设置图表组
-      if (groupName && chartInstance.group !== undefined) {
-        try {
-          (chartInstance as any).group = groupName;
-        } catch (e) {
-          console.warn('[useChartConnect] Failed to set chart group:', e);
-        }
-      }
+      connectChart(
+        chartInstance,
+        chartId,
+        groupName,
+        chartsRef,
+        connectedRef,
+        eventHandlersRef,
+        bindChartEventsCallback
+      );
     },
-    [bindChartEvents, groupName]
+    [groupName, chartsRef, connectedRef, eventHandlersRef, bindChartEventsCallback]
   );
 
   /**
@@ -255,56 +151,19 @@ export function useChartConnect(options: UseChartConnectOptions): UseChartConnec
    */
   const disconnect = useCallback(
     (chartInstance: ChartInstance, chartId?: string) => {
-      // 查找图表 ID
-      let targetId = chartId;
-      if (!targetId) {
-        chartsRef.current.forEach((item, id) => {
-          if (item.instance === chartInstance) {
-            targetId = id;
-          }
-        });
-      }
-
-      if (!targetId || !chartsRef.current.has(targetId)) {
-        console.warn(`[useChartConnect] Chart ${targetId} not found in connection group`);
-        return;
-      }
-
-      // 解绑事件
-      unbindChartEvents(targetId);
-
-      // 移除图表
-      chartsRef.current.delete(targetId);
-
-      // 更新连接状态
-      connectedRef.current = chartsRef.current.size > 0;
+      disconnectChart(chartInstance, chartId, chartsRef, connectedRef, unbindChartEventsCallback);
     },
-    [unbindChartEvents]
+    [chartsRef, connectedRef, unbindChartEventsCallback]
   );
 
   /**
    * 触发联动事件
    */
   const dispatchConnect = useCallback(
-    (sourceId: string, payload: any) => {
-      if (disabled) return;
-
-      const chartItem = chartsRef.current.get(sourceId);
-      if (!chartItem) {
-        console.warn(`[useChartConnect] Source chart ${sourceId} not found`);
-        return;
-      }
-
-      const { eventType, params } = payload || {};
-      if (!eventType) {
-        console.warn('[useChartConnect] Payload must include eventType');
-        return;
-      }
-
-      // 分发事件到其他图表
-      dispatchToOthers(sourceId, eventType, params);
+    (sourceId: string, payload: { eventType: ConnectEventType; params: unknown }) => {
+      dispatchConnectEvent(sourceId, payload, disabled, chartsRef, dispatchToOthersCallback);
     },
-    [disabled, dispatchToOthers]
+    [disabled, chartsRef, dispatchToOthersCallback]
   );
 
   /**
@@ -312,9 +171,7 @@ export function useChartConnect(options: UseChartConnectOptions): UseChartConnec
    */
   const connectAll = useCallback(
     (charts: Array<{ instance: ChartInstance; id: string }>) => {
-      charts.forEach(({ instance, id }) => {
-        connect(instance, id);
-      });
+      connectAllCharts(charts, connect);
     },
     [connect]
   );
@@ -323,12 +180,8 @@ export function useChartConnect(options: UseChartConnectOptions): UseChartConnec
    * 批量断开所有图表
    */
   const disconnectAll = useCallback(() => {
-    chartsRef.current.forEach((item, id) => {
-      unbindChartEvents(id);
-    });
-    chartsRef.current.clear();
-    connectedRef.current = false;
-  }, [unbindChartEvents]);
+    disconnectAllCharts(chartsRef, connectedRef, unbindChartEventsCallback);
+  }, [chartsRef, connectedRef, unbindChartEventsCallback]);
 
   // 自动绑定
   useEffect(() => {
@@ -359,4 +212,5 @@ export function useChartConnect(options: UseChartConnectOptions): UseChartConnec
 // 导出
 // ============================================================================
 
-export default useChartConnect;
+/** 导出共享事件类型 */
+export type { ConnectEventType, ChartConnectItem, EventHandlersMap } from './chartConnectHelpers';