@agions/taroviz 1.11.1 → 2.0.3

package/src/hooks/useChartPerformance.ts

@@ -0,0 +1,109 @@
+/**
+ * useChartPerformance - 图表性能相关 Hooks
+ * 提供数据轮询等功能
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+/**
+ * 使用数据轮询
+ * @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 abortRef = useRef<{ cancelled: boolean }>({ cancelled: false });
+
+  const fetchData = useCallback(async () => {
+    // 取消之前的请求
+    abortRef.current.cancelled = true;
+    // 创建新的取消标记
+    abortRef.current = { cancelled: false };
+    const currentAbort = abortRef.current;
+
+    let retries = retryCount;
+    setLoading(true);
+    setError(null);
+
+    // retryCount < 0 表示不重试，直接一次请求
+    if (retryCount < 0) {
+      try {
+        const result = await fetchFn();
+        if (!currentAbort.cancelled) {
+          setData(result);
+          setLoading(false);
+        }
+      } catch (e) {
+        if (!currentAbort.cancelled) {
+          setError(e as Error);
+          setLoading(false);
+        }
+      }
+      return;
+    }
+
+    // retryCount >= 0：循环重试
+    while (retries > 0 && !currentAbort.cancelled) {
+      try {
+        const result = await fetchFn();
+        if (!currentAbort.cancelled) {
+          setData(result);
+          setLoading(false);
+        }
+        return;
+      } catch (e) {
+        retries--;
+        if (retries <= 0 || currentAbort.cancelled) {
+          if (!currentAbort.cancelled) {
+            setError(e as Error);
+          }
+          setLoading(false);
+          return;
+        }
+        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);
+        abortRef.current.cancelled = true;
+      };
+    }
+
+    return () => {
+      abortRef.current.cancelled = true;
+    };
+  }, [interval, autoStart, fetchData]);
+
+  const refresh = useCallback(() => {
+    fetchData();
+  }, [fetchData]);
+
+  return { data, loading, error, refresh };
+}

package/src/hooks/useChartSelection.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * useChartSelection - 图表数据点选择/高亮 Hook
  * 支持单个/批量选择、反选、清除选择，配合 ECharts select 事件
@@ -10,7 +11,7 @@
  * - 自动绑定图表 select/unselect 事件
  */
 import { useEffect, useRef, useCallback, useState } from 'react';
-import type { ChartInstance } from './index';
+import type { ChartInstance } from './types';
 
 // ============================================================================
 // 类型定义
@@ -44,7 +45,7 @@ export interface UseChartSelectionOptions {
   /** 是否启用 Shift+Click 范围选择，默认 true */
   enableShiftRangeSelect?: boolean;
   /** 选择变化时的回调 */
-  onSelectionChange?: (event: SelectionEvent) => void;
+  onSelectionChange?: (_event: SelectionEvent) => void;
 }
 
 /** 选择返回值 */
@@ -118,9 +119,6 @@ export function useChartSelection(
   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;
@@ -130,16 +128,6 @@ export function useChartSelection(
     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 {
@@ -185,18 +173,15 @@ export function useChartSelection(
   );
 
   /** 执行 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,
-      });
-    },
-    []
-  );
+  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 ───────────────────────────────────────────────────────────
 
@@ -230,21 +215,34 @@ export function useChartSelection(
   const toggle = useCallback(
     (key: DataPointKey) => {
       const str = keyToString(key);
-      if (selectedPoints.some((p) => keyToString(p) === str)) {
-        deselect(key);
-      } else {
-        select(key);
-      }
+      let isCurrentlySelected = false;
+      setSelectedPoints((prev) => {
+        isCurrentlySelected = prev.some((p) => keyToString(p) === str);
+        if (isCurrentlySelected) {
+          dispatchSelect(key, false);
+          notifyChange([], [key]);
+          return prev.filter((p) => keyToString(p) !== str);
+        } else {
+          dispatchSelect(key, true);
+          const next = mode === 'single' ? [key] : [...prev, key];
+          notifyChange(next, []);
+          return next;
+        }
+      });
     },
-    [selectedPoints, select, deselect]
+    [mode, notifyChange, dispatchSelect]
   );
 
   const selectMultiple = useCallback(
     (keys: DataPointKey[]) => {
       setSelectedPoints((prev) => {
-        const newPoints = mode === 'single' ? keys : [...prev, ...keys.filter(
-          (k) => !prev.some((p) => keyToString(p) === keyToString(k))
-        )];
+        const newPoints =
+          mode === 'single'
+            ? keys
+            : [
+                ...prev,
+                ...keys.filter((k) => !prev.some((p) => keyToString(p) === keyToString(k))),
+              ];
         notifyChange(newPoints, []);
         return newPoints;
       });
@@ -270,7 +268,9 @@ export function useChartSelection(
   const invertSelection = useCallback(
     (seriesIndex: number, dataIndices: number[]) => {
       setSelectedPoints((prev) => {
-        const selectedSet = new Set(prev.filter((p) => p.seriesIndex === seriesIndex).map((p) => p.dataIndex));
+        const selectedSet = new Set(
+          prev.filter((p) => p.seriesIndex === seriesIndex).map((p) => p.dataIndex)
+        );
         const toSelect: DataPointKey[] = [];
         const toDeselect: DataPointKey[] = [];
 
@@ -287,9 +287,9 @@ export function useChartSelection(
         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);
+        const newSelected = prev
+          .filter((p) => !(p.seriesIndex === seriesIndex && selectedSet.has(p.dataIndex)))
+          .concat(toSelect);
 
         notifyChange(toSelect, toDeselect);
         return newSelected;
@@ -302,9 +302,13 @@ export function useChartSelection(
     (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))
-        )];
+        const newPoints =
+          mode === 'single'
+            ? keys
+            : [
+                ...prev,
+                ...keys.filter((k) => !prev.some((p) => keyToString(p) === keyToString(k))),
+              ];
         notifyChange(newPoints, []);
         return newPoints;
       });
@@ -318,10 +322,11 @@ export function useChartSelection(
     if (chart?.dispatchAction) {
       chart.dispatchAction({ type: 'unselect' });
     }
-    const prev = selectedPoints;
-    setSelectedPoints([]);
-    notifyChange([], prev);
-  }, [selectedPoints, notifyChange]);
+    setSelectedPoints((prev) => {
+      notifyChange([], prev);
+      return [];
+    });
+  }, [notifyChange]);
 
   const isSelected = useCallback(
     (key: DataPointKey) => {
@@ -346,5 +351,3 @@ export function useChartSelection(
     isSelected,
   };
 }
-
-export default useChartSelection;

package/src/hooks/useChartTheme.ts

@@ -0,0 +1,51 @@
+/**
+ * useChartTheme - 图表主题相关 Hooks
+ * 提供主题解析和主题切换功能
+ */
+import { useState, useMemo, useCallback } from 'react';
+import { getThemeByName } from '../themes';
+
+/**
+ * 使用图表主题
+ * @param theme 主题名称或配置
+ * @param darkMode 是否为暗色模式
+ * @returns 处理后的主题
+ */
+export function useChartTheme(theme: string | Record<string, unknown>, darkMode = false) {
+  return useMemo(() => {
+    if (typeof theme === 'string') {
+      // 如果是字符串，尝试获取内置主题配置
+      try {
+        const builtinTheme = getThemeByName(theme);
+        return builtinTheme || (darkMode ? 'dark' : theme);
+      } catch {
+        return darkMode ? 'dark' : theme;
+      }
+    }
+    return theme;
+  }, [theme, darkMode]);
+}
+
+/**
+ * 使用主题切换
+ * @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 };
+}

package/src/hooks/useDataTransform.ts

@@ -63,7 +63,7 @@ export interface TransformOptions {
     order: 'asc' | 'desc';
   };
   /** 过滤配置 */
-  filter?: (item: Record<string, unknown>) => boolean;
+  filter?: (_item: Record<string, unknown>) => boolean;
   /** 转换后的额外配置 */
   extraConfig?: Partial<EChartsOption>;
 }
@@ -109,6 +109,21 @@ export interface TimeSeriesTransformOptions {
 // 数据转换 Hook
 // ============================================================================
 
+/**
+ * 使用图表数据变更
+ * @param data 数据源
+ * @param transformer 数据转换函数
+ * @returns 转换后的图表选项
+ */
+export function useChartData<T = unknown>(data: T | null, transformer: (data: T) => EChartsOption) {
+  return useMemo(() => {
+    if (!data || (Array.isArray(data) && data.length === 0)) {
+      return {};
+    }
+    return transformer(data);
+  }, [data, transformer]);
+}
+
 /**
  * 使用数据转换
  * @param options 转换选项
@@ -174,7 +189,7 @@ export function useTableTransform(options: TableTransformOptions): EChartsOption
         name: colConfig?.label || key,
         type: 'bar' as const,
         data: values,
-        itemStyle: colConfig?.color ? { color: colConfig.color } : undefined,
+        _itemStyle: colConfig?.color ? { color: colConfig.color } : undefined,
       };
     });
 
@@ -217,8 +232,8 @@ export function useTimeSeriesTransform(options: TimeSeriesTransformOptions): ECh
       const groups = new Set(data.map((d) => String(d[groupField])));
       const series = Array.from(groups).map((group) => {
         const groupValues = categories.map((date) => {
-          const items = groupedData[date]?.filter((d) => String(d[groupField]) === group) || [];
-          return aggregateValues(items, valueField, aggregation, fillMissing);
+          const _items = groupedData[date]?.filter((d) => String(d[groupField]) === group) || [];
+          return aggregateValues(_items, valueField, aggregation, fillMissing);
         });
         return { name: group, type: 'line', data: groupValues, smooth: true };
       });

package/src/hooks/utils/chartDownloadUtils.ts

@@ -1,55 +1,19 @@
 /**
  * Chart Download Utilities
  * 图表下载工具函数
+ * 使用公共下载工具模块
  */
 
-/**
- * 生成默认文件名
- */
-export function generateFilename(prefix: string = 'chart'): string {
-  const timestamp = new Date().toISOString().slice(0, 19).replace(/[:-]/g, '');
-  return `${prefix}_${timestamp}`;
-}
-
-/**
- * 下载 Blob 对象
- */
-export function downloadBlob(blob: Blob, filename: string): void {
-  const url = URL.createObjectURL(blob);
-  const link = document.createElement('a');
-  link.href = url;
-  link.download = filename;
-  document.body.appendChild(link);
-  link.click();
-  document.body.removeChild(link);
-  URL.revokeObjectURL(url);
-}
+import {
+  generateFilename,
+  downloadBlob,
+  downloadDataUrl,
+  csvToBlob,
+  jsonToBlob,
+} from '../../core/utils/download';
 
-/**
- * 下载数据 URL
- */
-export function downloadDataUrl(dataUrl: string, filename: string): void {
-  const link = document.createElement('a');
-  link.href = dataUrl;
-  link.download = filename;
-  document.body.appendChild(link);
-  link.click();
-  document.body.removeChild(link);
-}
-
-/**
- * CSV 转 Blob
- */
-export function csvToBlob(csv: string, _filename: string): Blob {
-  return new Blob([csv], { type: 'text/csv;charset=utf-8;' });
-}
-
-/**
- * JSON 转 Blob
- */
-export function jsonToBlob(json: string, _filename: string): Blob {
-  return new Blob([json], { type: 'application/json;charset=utf-8;' });
-}
+// 重新导出公共函数
+export { generateFilename, downloadBlob, downloadDataUrl, csvToBlob, jsonToBlob };
 
 /**
  * 将数据转换为 CSV 格式
@@ -59,7 +23,14 @@ export function convertToCSV(data: unknown, options?: { includeLabels?: boolean
 
   // 处理 ECharts 格式的数据
   if (typeof data === 'object' && (data as { series?: unknown }).series) {
-    return convertSeriesToCSV(data as { series?: unknown[]; xAxis?: { data?: unknown[] }; dataset?: { dimensions?: string[]; source?: unknown[][] } }, options);
+    return convertSeriesToCSV(
+      data as {
+        series?: unknown[];
+        xAxis?: { data?: unknown[] };
+        dataset?: { dimensions?: string[]; source?: unknown[][] };
+      },
+      options
+    );
   }
 
   // 处理数组数据
@@ -79,7 +50,11 @@ export function convertToCSV(data: unknown, options?: { includeLabels?: boolean
  * 将 ECharts series 数据转换为 CSV
  */
 function convertSeriesToCSV(
-  chartData: { series?: unknown[]; xAxis?: { data?: unknown[] }; dataset?: { dimensions?: string[]; source?: unknown[][] } },
+  chartData: {
+    series?: unknown[];
+    xAxis?: { data?: unknown[] };
+    dataset?: { dimensions?: string[]; source?: unknown[][] };
+  },
   options?: { includeLabels?: boolean }
 ): string {
   const { series = [], xAxis, dataset } = chartData;
@@ -102,7 +77,14 @@ function convertSeriesToCSV(
 
   // 构建 CSV 头
   const headers = includeLabels
-    ? ['Category', ...series.map((s: unknown) => (s as { name?: string; seriesIndex?: number }).name || (s as { seriesIndex?: number }).seriesIndex)]
+    ? [
+        'Category',
+        ...series.map(
+          (s: unknown) =>
+            (s as { name?: string; seriesIndex?: number }).name ||
+            (s as { seriesIndex?: number }).seriesIndex
+        ),
+      ]
     : [];
 
   // 构建 CSV 行
@@ -175,7 +157,12 @@ function convertObjectToCSV(data: Record<string, unknown>): string {
 export function convertToJSON(data: unknown): string {
   if (!data) return '{}';
 
-  const dataObj = data as { series?: unknown[]; title?: { text?: string }; legend?: { data?: unknown }; xAxis?: { data?: unknown[] } };
+  const dataObj = data as {
+    series?: unknown[];
+    title?: { text?: string };
+    legend?: { data?: unknown };
+    xAxis?: { data?: unknown[] };
+  };
 
   // 如果是 ECharts 格式，简化数据
   if (dataObj.series) {
@@ -234,7 +221,7 @@ export async function createPdfFromImage(
         // 计算图片位置和尺寸（居中）
         const imgRatio = img.width / img.height;
         const canvasRatio = pdfWidth / pdfHeight;
-        let drawWidth: number, drawHeight: number, offsetX: number, offsetY: number;
+        let drawWidth: number, drawHeight: number;
 
         if (imgRatio > canvasRatio) {
           drawWidth = pdfWidth * 0.8;
@@ -244,8 +231,8 @@ export async function createPdfFromImage(
           drawWidth = drawHeight * imgRatio;
         }
 
-        offsetX = (pdfWidth - drawWidth) / 2;
-        offsetY = (pdfHeight - drawHeight) / 2;
+        const offsetX = (pdfWidth - drawWidth) / 2;
+        const offsetY = (pdfHeight - drawHeight) / 2;
 
         // 绘制图片
         ctx.drawImage(img, offsetX, offsetY, drawWidth, drawHeight);

package/src/hooks/utils/dataTransformUtils.ts

@@ -44,6 +44,14 @@ export interface TransformMapping {
 // 转换函数
 // ============================================================================
 
+/**
+ * 将数据转换为折线图或柱状图配置
+ * @param data 数据源
+ * @param chartType 图表类型 (line 或 bar)
+ * @param mapping 字段映射
+ * @param extraConfig 额外配置
+ * @returns ECharts 配置
+ */
 export function transformLineOrBar(
   data: DataSource,
   chartType: 'line' | 'bar',
@@ -90,6 +98,13 @@ export function transformLineOrBar(
   };
 }
 
+/**
+ * 将数据转换为饼图配置
+ * @param data 数据源
+ * @param mapping 字段映射
+ * @param extraConfig 额外配置
+ * @returns ECharts 配置
+ */
 export function transformPie(
   data: DataSource,
   mapping: TransformMapping,
@@ -110,6 +125,13 @@ export function transformPie(
   };
 }
 
+/**
+ * 将数据转换为散点图配置
+ * @param data 数据源
+ * @param mapping 字段映射
+ * @param extraConfig 额外配置
+ * @returns ECharts 配置
+ */
 export function transformScatter(
   data: DataSource,
   mapping: TransformMapping,

package/src/index.ts

@@ -35,38 +35,54 @@ export {
   prefixedId,
 } from './core/utils';
 
-// 图表组件
-export { default as LineChart } from './charts/line';
-export { default as BarChart } from './charts/bar';
-export { default as PieChart } from './charts/pie';
-export { default as ScatterChart } from './charts/scatter';
-export { default as RadarChart } from './charts/radar';
-export { default as HeatmapChart } from './charts/heatmap';
-export { default as GaugeChart } from './charts/gauge';
-export { default as FunnelChart } from './charts/funnel';
-
-// 扩展图表组件
-export { default as TreeMapChart } from './charts/treemap';
-export { default as SunburstChart } from './charts/sunburst';
-export { default as SankeyChart } from './charts/sankey';
-
-// 新增图表组件
-export { default as GraphChart } from './charts/graph';
-export { default as CandlestickChart } from './charts/candlestick';
-export { default as WordCloudChart } from './charts/wordcloud';
-
-// v1.6.0 新增图表组件
-export { default as BoxplotChart } from './charts/boxplot';
-export { default as ParallelChart } from './charts/parallel';
+// 图表组件（统一从 charts/index.ts 导入）
+export {
+  // 基础图表
+  LineChart,
+  BarChart,
+  PieChart,
+  ScatterChart,
+  RadarChartCustom as RadarChart,
+  HeatmapChart,
+  FunnelChart,
+  // 扩展图表
+  TreeMapChart,
+  SunburstChart,
+  SankeyChart,
+  GraphChart,
+  WordCloudChart,
+  // 特殊图表
+  BoxplotChart,
+  ParallelChart,
+  TreeChart,
+  // 类型
+  type BaseChartProps,
+  type LineChartProps,
+  type BarChartProps,
+  type PieChartProps,
+  type ScatterChartProps,
+  type RadarChartProps,
+  type FunnelChartProps,
+  type HeatmapChartProps,
+  type SunburstChartProps,
+  type TreeMapChartProps,
+  type SankeyChartProps,
+  type GraphChartProps,
+  type WordCloudChartProps,
+  type BoxplotChartProps,
+  type ParallelChartProps,
+  type TreeChartProps,
+} from './charts';
 
 // v1.7.0 新增组件
-export { DataFilter, type DataFilterProps, type FilterField, type FilterValues } from './components/DataFilter';
+export {
+  DataFilter,
+  type DataFilterProps,
+  type FilterField,
+  type FilterValues,
+} from './components/DataFilter';
 export {
   createDrillDown,
-  canDrillDown,
-  buildHierarchy,
-  createRegionDrillDown,
-  createCategoryDrillDown,
   type DrillDownConfig,
   type DrillDownSource,
   type DrillDownReturn,
@@ -74,15 +90,15 @@ export {
   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';
 export { default as WeappAdapter } from './adapters/weapp';
 
+// 统一运行时检测
+export { detectRuntime, resetRuntimeCache } from './core/utils/runtime';
+export type { RuntimeInfo, MiniAppType } from './core/utils/runtime';
+
 // 主题系统
 export type { BuiltinTheme, ThemeOptions } from './themes';
 export {
@@ -172,7 +188,6 @@ export {
   useTableTransform,
   useTimeSeriesTransform,
   // v1.7.0 新增 Hooks
-  useDataZoom,
   useChartConnect,
   useChartDownload,
 } from './hooks';
@@ -181,4 +196,3 @@ export {
  * 库信息
  */
 export const name = 'taroviz';
-export const version = '1.7.0';