@agions/taroviz 1.2.0 → 1.2.1

package/src/hooks/index.ts

@@ -1,119 +1,235 @@
 /**
- * TaroViz React Hooks
- * 提供与图表相关的React Hooks
+ * TaroViz React Hooks - 增强版
+ * 提供与图表相关的 React Hooks
  */
-import { useState, useEffect, useMemo } from 'react';
-
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
 import { getAdapter } from '../adapters';
-import { EventHandler } from '../core';
+import type { EChartsOption } from 'echarts';
 
-// 通用图表配置类型
-interface ChartOptions {
-  [key: string]: any;
-}
+// ============================================================================
+// 类型定义
+// ============================================================================
 
-// 通用图表实例类型
-interface ChartInstance {
-  setOption: (option: any, notMerge?: boolean) => void;
-  resize: () => void;
+/** 图表实例类型 */
+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?: any) => 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;
   [key: string]: any;
 }
 
+/** 事件处理器 */
+export type EventHandler = (params?: unknown) => void;
+
+/** 加载选项 */
+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>;
+}
+
+/** 数据转换器 */
+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;
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
 /**
- * 使用图表Hook
+ * 使用图表 Hook
  * @param chartRef 图表容器的引用
- * @returns [图表实例, setInstance]
+ * @param config 图表配置
+ * @returns [图表实例, 设置实例函数, 是否已初始化]
  */
-export function useChart(chartRef: React.RefObject<HTMLElement>) {
+export function useChart(
+  chartRef: React.RefObject<HTMLElement>,
+  config?: ChartConfig
+): [ChartInstance | null, React.Dispatch<React.SetStateAction<ChartInstance | null>>, boolean] {
   const [instance, setInstance] = useState<ChartInstance | null>(null);
+  const [initialized, setInitialized] = useState(false);
+  const configRef = useRef(config);
+  configRef.current = config;
 
   useEffect(() => {
-    if (chartRef.current && !instance) {
-      // 使用默认配置初始化适配器
-      const adapter = getAdapter({});
-
-      // 注意：Adapter接口可能没有直接定义setComponent方法
-      // 但多数适配器实现中都有这个方法，我们可以通过类型断言使用
-      if (typeof (adapter as any).setComponent === 'function') {
-        (adapter as any).setComponent(chartRef.current);
-      }
+    if (!chartRef.current || instance) {
+      return;
+    }
 
-      // 初始化并保存实例
+    try {
+      const adapter = getAdapter(configRef.current || {});
       const chartInstance = adapter as unknown as ChartInstance;
       setInstance(chartInstance);
+      setInitialized(true);
+    } catch (error) {
+      console.error('Failed to initialize chart:', error);
     }
 
     return () => {
       if (instance) {
         try {
-          instance.dispose();
+          const inst = instance as any;
+          if (!inst.isDisposed?.()) {
+            inst.dispose();
+          }
         } catch (e) {
           console.warn('Failed to dispose chart instance:', e);
         }
+        setInstance(null);
+        setInitialized(false);
       }
     };
-  }, [chartRef, instance]);
+  }, [chartRef]);
 
-  return [instance, setInstance] as const;
+  return [instance, setInstance, initialized];
 }
 
 /**
- * 设置图表选项Hook
+ * 设置图表选项 Hook
  * @param instance 图表实例
  * @param option 图表选项
- * @param deps 依赖数组
+ * @param options 配置选项
  */
-export function useOption(instance: ChartInstance | null, option: ChartOptions, deps: any[] = []) {
+export function useOption(
+  instance: ChartInstance | null,
+  option: EChartsOption | null,
+  options?: {
+    /** 是否不合并 */
+    notMerge?: boolean;
+    /** 是否延迟更新 */
+    lazyUpdate?: boolean;
+    /** 是否在数据变化时替换 */
+    replaceMerge?: string[];
+    /** 依赖数组 */
+    deps?: unknown[];
+  }
+) {
+  const { notMerge = false, lazyUpdate = false, replaceMerge, deps = [] } = options || {};
+
   useEffect(() => {
     if (instance && option) {
       try {
-        instance.setOption(option);
+        instance.setOption(option, notMerge, lazyUpdate);
       } catch (e) {
         console.warn('Failed to set chart option:', e);
       }
     }
-  }, [instance, option, ...deps]);
+  }, [instance, option, notMerge, lazyUpdate, replaceMerge, ...deps]);
 }
 
 /**
- * 图表自适应Hook
+ * 图表自适应 Hook
  * @param instance 图表实例
+ * @param options 配置选项
  */
-export function useResize(instance: ChartInstance | null) {
+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<NodeJS.Timeout>();
+
   useEffect(() => {
-    if (!instance) {
+    if (!instance || !enabled) {
       return;
     }
 
     const handleResize = () => {
-      try {
-        instance.resize();
-      } catch (e) {
-        console.warn('Failed to resize chart:', e);
+      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]);
+  }, [instance, delay, minWidth, minHeight, enabled]);
 }
 
 /**
- * 图表事件Hook
+ * 图表事件 Hook
  * @param instance 图表实例
  * @param events 事件对象
  */
 export function useEvents(instance: ChartInstance | null, events: Record<string, EventHandler>) {
   useEffect(() => {
-    if (!instance) {
+    if (!instance || !events) {
       return;
     }
 
@@ -142,11 +258,16 @@ export function useEvents(instance: ChartInstance | null, events: Record<string,
 }
 
 /**
- * 图表加载状态Hook
+ * 图表加载状态 Hook
  * @param instance 图表实例
  * @param loading 是否加载中
+ * @param options 加载选项
  */
-export function useLoading(instance: ChartInstance | null, loading: boolean) {
+export function useLoading(
+  instance: ChartInstance | null,
+  loading: boolean,
+  options?: LoadingOptions
+) {
   useEffect(() => {
     if (!instance) {
       return;
@@ -154,28 +275,33 @@ export function useLoading(instance: ChartInstance | null, loading: boolean) {
 
     try {
       if (loading) {
-        instance.showLoading();
+        instance.showLoading(options);
       } else {
         instance.hideLoading();
       }
     } catch (e) {
       console.warn('Failed to set chart loading state:', e);
     }
-  }, [instance, loading]);
+  }, [instance, loading, options]);
 }
 
 /**
  * 使用图表主题
  * @param theme 主题名称或配置
- * @param darkMode 是否为暗黑模式
+ * @param darkMode 是否为暗色模式
  * @returns 处理后的主题
  */
-export function useChartTheme(theme: string | Record<string, any>, darkMode = false) {
+export function useChartTheme(theme: string | Record<string, unknown>, darkMode = false) {
   return useMemo(() => {
     if (typeof theme === 'string') {
-      return darkMode ? 'dark' : theme;
+      // 如果是字符串，尝试获取内置主题
+      try {
+        const builtinTheme = getTheme(theme);
+        return builtinTheme || (darkMode ? 'dark' : theme);
+      } catch {
+        return darkMode ? 'dark' : theme;
+      }
     }
-
     return theme;
   }, [theme, darkMode]);
 }
@@ -186,20 +312,269 @@ export function useChartTheme(theme: string | Record<string, any>, darkMode = fa
  * @param transformer 数据转换函数
  * @returns 转换后的图表选项
  */
-export function useChartData<T = any>(data: T[] | null, transformer: (data: T[]) => ChartOptions) {
+export function useChartData<T = unknown>(data: T | null, transformer: DataTransformer<T>) {
   return useMemo(() => {
-    if (!data || data.length === 0) {
-      return { series: [] };
+    if (!data) {
+      return {};
     }
-
     return transformer(data);
   }, [data, transformer]);
 }
 
-// 导出版本号
-export const version = '1.1.1';
+/**
+ * 使用响应式图表配置
+ * @param config 响应式配置
+ * @returns 当前断点和配置
+ */
+export function useResponsive(config?: {
+  /** 断点配置 */
+  breakpoints?: Record<Breakpoint, number>;
+  /** 默认断点 */
+  defaultBreakpoint?: Breakpoint;
+}) {
+  const { breakpoints = { xs: 0, sm: 576, md: 768, lg: 992, xl: 1200 }, defaultBreakpoint = 'md' } =
+    config || {};
+
+  const [breakpoint, setBreakpoint] = useState<Breakpoint>(defaultBreakpoint);
+  const [windowSize, setWindowSize] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    const handleResize = () => {
+      const width = window.innerWidth;
+      setWindowSize({ width, height: window.innerHeight });
+
+      // 确定当前断点
+      let current: Breakpoint = 'xs';
+      if (width >= breakpoints.xl) current = 'xl';
+      else if (width >= breakpoints.lg) current = 'lg';
+      else if (width >= breakpoints.md) current = 'md';
+      else if (width >= breakpoints.sm) current = 'sm';
+
+      setBreakpoint(current);
+    };
+
+    handleResize();
+    window.addEventListener('resize', handleResize);
+
+    return () => window.removeEventListener('resize', handleResize);
+  }, [breakpoints]);
+
+  return { breakpoint, windowSize };
+}
+
+/**
+ * 使用主题切换
+ * @param initialTheme 初始主题
+ * @returns [当前主题, 切换主题函数]
+ */
+export function useThemeSwitcher(initialTheme = 'default') {
+  const [theme, setTheme] = useState<string | Record<string, unknown>>(initialTheme);
+  const [isDark, setIsDark] = useState(false);
+
+  const switchTheme = useCallback((newTheme: string | Record<string, unknown>) => {
+    setTheme(newTheme);
+    if (typeof newTheme === 'string') {
+      setIsDark(newTheme === 'dark' || newTheme.includes('dark'));
+    }
+  }, []);
+
+  const toggleDark = useCallback(() => {
+    setIsDark((prev) => !prev);
+    setTheme((prev) => (prev === 'dark' ? 'default' : 'dark'));
+  }, []);
+
+  return { theme, isDark, switchTheme, toggleDark, setTheme };
+}
+
+/**
+ * 使用数据轮询
+ * @param fetchFn 数据获取函数
+ * @param options 配置选项
+ * @returns [数据, 加载状态, 错误, 刷新函数]
+ */
+export function useDataPolling<T>(
+  fetchFn: () => Promise<T>,
+  options?: {
+    /** 轮询间隔 (ms) */
+    interval?: number;
+    /** 是否自动开始 */
+    autoStart?: boolean;
+    /** 错误重试次数 */
+    retryCount?: number;
+    /** 重试延迟 (ms) */
+    retryDelay?: number;
+  }
+) {
+  const { interval = 5000, autoStart = false, retryCount = 3, retryDelay = 1000 } = options || {};
+
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(autoStart);
+  const [error, setError] = useState<Error | null>(null);
+  const [refreshIndex, setRefreshIndex] = useState(0);
+
+  const fetchData = useCallback(async () => {
+    let retries = retryCount;
+    setLoading(true);
+    setError(null);
+
+    while (retries >= 0) {
+      try {
+        const result = await fetchFn();
+        setData(result);
+        setLoading(false);
+        return;
+      } catch (e) {
+        retries--;
+        if (retries < 0) {
+          setError(e as Error);
+          setLoading(false);
+        } else {
+          await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        }
+      }
+    }
+  }, [fetchFn, retryCount, retryDelay]);
+
+  useEffect(() => {
+    if (autoStart) {
+      fetchData();
+    }
+
+    if (interval > 0) {
+      const timer = setInterval(fetchData, interval);
+      return () => clearInterval(timer);
+    }
+  }, [interval, autoStart, fetchData, refreshIndex]);
+
+  const refresh = useCallback(() => {
+    setRefreshIndex((prev) => prev + 1);
+    fetchData();
+  }, [fetchData]);
+
+  return { data, loading, error, refresh };
+}
+
+/**
+ * 使用图表全屏
+ * @param chartRef 图表容器引用
+ * @returns [是否全屏, 进入/退出全屏函数]
+ */
+export function useFullscreen(chartRef: React.RefObject<HTMLElement>) {
+  const [isFullscreen, setIsFullscreen] = useState(false);
+
+  const toggle = useCallback(() => {
+    if (!chartRef.current) return;
+
+    if (!isFullscreen) {
+      if (chartRef.current.requestFullscreen) {
+        chartRef.current.requestFullscreen();
+      }
+    } else {
+      if (document.exitFullscreen) {
+        document.exitFullscreen();
+      }
+    }
+  }, [chartRef, isFullscreen]);
+
+  useEffect(() => {
+    const handleChange = () => {
+      setIsFullscreen(!!document.fullscreenElement);
+    };
+
+    document.addEventListener('fullscreenchange', handleChange);
+    return () => document.removeEventListener('fullscreenchange', handleChange);
+  }, []);
+
+  return { isFullscreen, toggle };
+}
+
+/**
+ * 使用图表导出
+ * @param instance 图表实例
+ * @returns 导出函数
+ */
+export function useExport(instance: ChartInstance | null) {
+  const inst = instance as any;
+  const exportImage = useCallback(
+    (options?: { type?: 'png' | 'jpeg'; pixelRatio?: number; backgroundColor?: string }) => {
+      if (!inst) return null;
+      const { type = 'png', pixelRatio = 2, backgroundColor } = options || {};
+      return inst.getDataURL?.({ type, pixelRatio, backgroundColor });
+    },
+    [inst]
+  );
+
+  const exportSVG = useCallback(() => {
+    if (!inst) return null;
+    return inst.getSvgData?.();
+  }, [inst]);
+
+  const exportCSV = useCallback(
+    (options?: { seriesIndex?: number; dimension?: number }) => {
+      if (!inst) return null;
+      return inst.getCompressedDataURL?.(options);
+    },
+    [inst]
+  );
+
+  return { exportImage, exportSVG, exportCSV };
+}
+
+/**
+ * 使用图表工具
+ * @param instance 图表实例
+ * @returns 工具函数
+ */
+export function useChartTools(instance: ChartInstance | null) {
+  const inst = instance as any;
+  const getInstance = useCallback(() => instance, [instance]);
+
+  const clear = useCallback(() => {
+    inst?.clear?.();
+  }, [inst]);
+
+  const repaint = useCallback(() => {
+    inst?.resize?.();
+  }, [inst]);
+
+  const dispatchAction = useCallback(
+    (action: { type: string; [key: string]: unknown }) => {
+      inst?.dispatchAction?.(action);
+    },
+    [inst]
+  );
+
+  const showTip = useCallback(
+    (seriesIndex?: number, dataIndex?: number) => {
+      inst?.dispatchAction?.({ type: 'showTip', seriesIndex, dataIndex });
+    },
+    [inst]
+  );
+
+  const hideTip = useCallback(() => {
+    inst?.dispatchAction?.({ type: 'hideTip' });
+  }, [inst]);
+
+  const zoom = useCallback(
+    (start?: number, end?: number) => {
+      inst?.dispatchAction?.({
+        type: 'dataZoom',
+        start: start ?? 0,
+        end: end ?? 100,
+      });
+    },
+    [inst]
+  );
+
+  return { getInstance, clear, repaint, dispatchAction, showTip, hideTip, zoom };
+}
+
+// ============================================================================
+// 导出
+// ============================================================================
+
+export const version = '1.2.0';
 
-// 导出所有hooks到默认导出对象
 const hooks = {
   useChart,
   useOption,
@@ -208,7 +583,12 @@ const hooks = {
   useLoading,
   useChartTheme,
   useChartData,
+  useResponsive,
+  useThemeSwitcher,
+  useDataPolling,
+  useFullscreen,
+  useExport,
+  useChartTools,
 };
 
-// 为了同时支持具名导入和默认导入
 export default hooks;

package/src/main.tsx

@@ -163,7 +163,7 @@ const TestApp = () => {
         <select
           id="theme"
           value={darkMode ? 'dark' : 'light'}
-          onChange={e => setDarkMode(e.target.value === 'dark')}
+          onChange={(e) => setDarkMode(e.target.value === 'dark')}
         >
           <option value="light">Light</option>
           <option value="dark">Dark</option>