@agions/taroviz 1.3.1 → 1.6.0

package/src/core/components/ErrorBoundary.tsx

@@ -145,7 +145,10 @@ export function withErrorBoundary<Props extends object>(
     </ErrorBoundary>
   );
 
-  WrappedChart.displayName = `withErrorBoundary(${ChartComponent.displayName || ChartComponent.name || 'Chart'})`;
+  const componentName = ChartComponent.displayName || ChartComponent.name;
+  WrappedChart.displayName = componentName
+    ? `withErrorBoundary(${componentName})`
+    : 'withErrorBoundary(WrappedChart)';
 
   return WrappedChart;
 }

package/src/core/components/LazyChart.tsx

@@ -17,15 +17,22 @@ const LazyTreeMapChart = lazy(() => import('../../charts/treemap'));
 const LazySunburstChart = lazy(() => import('../../charts/sunburst'));
 const LazySankeyChart = lazy(() => import('../../charts/sankey'));
 
-/**
- * 懒加载图表包装器
- */
-interface LazyChartWrapperProps {
-  children?: React.ReactNode;
-  fallback?: React.ReactNode;
-  loading?: boolean;
-  loadingText?: string;
-}
+// 统一的图表类型到懒加载组件映射
+const LAZY_CHART_MODULES: Record<string, () => Promise<{ default: ComponentType<any> }>> = {
+  line: () => import('../../charts/line'),
+  bar: () => import('../../charts/bar'),
+  pie: () => import('../../charts/pie'),
+  scatter: () => import('../../charts/scatter'),
+  radar: () => import('../../charts/radar'),
+  heatmap: () => import('../../charts/heatmap'),
+  gauge: () => import('../../charts/gauge'),
+  funnel: () => import('../../charts/funnel'),
+  treemap: () => import('../../charts/treemap'),
+  sunburst: () => import('../../charts/sunburst'),
+  sankey: () => import('../../charts/sankey'),
+};
+
+export const LAZY_CHART_TYPES = Object.keys(LAZY_CHART_MODULES);
 
 /**
  * 默认加载状态组件
@@ -73,22 +80,22 @@ const DefaultLoadingFallback: React.FC<{ text?: string }> = ({ text = '加载中
 export function withLazyLoad<P extends object>(
   ChartComponent: ComponentType<P>,
   loadingFallback?: ComponentType<{ text?: string }>
-): ComponentType<P & { loadingText?: string; fallback?: React.ReactNode }> {
-  const LazyWrapper: React.FC<P & { loadingText?: string; fallback?: React.ReactNode }> = ({
-    loadingText,
-    fallback,
-    ...props
-  }) => {
+): ComponentType<
+  Omit<P, 'loadingText' | 'fallback'> & { loadingText?: string; fallback?: React.ReactNode }
+> {
+  const LazyWrapper: React.FC<
+    Omit<P, 'loadingText' | 'fallback'> & { loadingText?: string; fallback?: React.ReactNode }
+  > = ({ loadingText, fallback, ...props }) => {
     const LoadingComponent = loadingFallback || DefaultLoadingFallback;
     return (
       <Suspense fallback={<LoadingComponent text={loadingText} />}>
         {fallback ? (
           <React.Fragment>
             {fallback}
-            <ChartComponent {...props} />
+            <ChartComponent {...(props as P)} />
           </React.Fragment>
         ) : (
-          <ChartComponent {...props} />
+          <ChartComponent {...(props as P)} />
         )}
       </Suspense>
     );
@@ -102,47 +109,27 @@ export function withLazyLoad<P extends object>(
 /**
  * 预加载图表组件
  * 在需要显示图表之前预先加载
+ * @param silent - 如果为 true，错误不会被打印到控制台（保持旧行为兼容）
+ * @returns Promise that resolves when loaded, rejects on error
  */
-export function preloadChart(chartType: string): void {
-  const chartModules: Record<string, () => Promise<{ default: ComponentType<any> }>> = {
-    line: () => import('../../charts/line'),
-    bar: () => import('../../charts/bar'),
-    pie: () => import('../../charts/pie'),
-    scatter: () => import('../../charts/scatter'),
-    radar: () => import('../../charts/radar'),
-    heatmap: () => import('../../charts/heatmap'),
-    gauge: () => import('../../charts/gauge'),
-    funnel: () => import('../../charts/funnel'),
-    treemap: () => import('../../charts/treemap'),
-    sunburst: () => import('../../charts/sunburst'),
-    sankey: () => import('../../charts/sankey'),
-  };
-
-  const loader = chartModules[chartType];
-  if (loader) {
-    loader().catch(console.error);
+export function preloadChart(chartType: string, silent = true): Promise<void> {
+  const loader = LAZY_CHART_MODULES[chartType];
+  if (!loader) {
+    if (silent) return Promise.resolve();
+    return Promise.reject(new Error(`Unknown chart type: ${chartType}`));
   }
+  return loader()
+    .then(() => undefined)
+    .catch((e) => {
+      if (!silent) console.error('[TaroViz] Failed to preload chart:', chartType, e);
+    });
 }
 
 /**
  * 预加载所有图表组件
  */
-export function preloadAllCharts(): void {
-  const chartTypes = [
-    'line',
-    'bar',
-    'pie',
-    'scatter',
-    'radar',
-    'heatmap',
-    'gauge',
-    'funnel',
-    'treemap',
-    'sunburst',
-    'sankey',
-  ];
-
-  chartTypes.forEach((type) => preloadChart(type));
+export function preloadAllCharts(): Promise<void[]> {
+  return Promise.all(LAZY_CHART_TYPES.map((type) => preloadChart(type)));
 }
 
 /**
@@ -176,12 +163,12 @@ export const LazyChartRegistry = {
     return createLazyChart(chartType);
   },
 
-  preload(chartType: string): void {
-    preloadChart(chartType);
+  preload(chartType: string, silent = true): Promise<void> {
+    return preloadChart(chartType, silent);
   },
 
-  preloadAll(): void {
-    preloadAllCharts();
+  preloadAll(): Promise<void[]> {
+    return preloadAllCharts();
   },
 };
 

package/src/core/components/hooks/index.ts

@@ -0,0 +1,20 @@
+/**
+ * TaroViz 图表组件 Hooks
+ * 提供图表初始化、事件处理、虚拟滚动、性能监控等能力
+ */
+
+export { useChartInit } from './useChartInit';
+export type { UseChartInitOptions, UseChartInitResult } from './useChartInit';
+
+export { useChartEvents } from './useChartEvents';
+export type {
+  ChartEventHandlers,
+  ChartLinkageConfig,
+  UseChartEventsOptions,
+} from './useChartEvents';
+
+export { useVirtualScroll } from './useVirtualScroll';
+export type { UseVirtualScrollOptions, VirtualScrollState } from './useVirtualScroll';
+
+export { usePerformance } from './usePerformance';
+export type { PerformanceData, UsePerformanceOptions } from './usePerformance';

package/src/core/components/hooks/useChartEvents.ts

@@ -0,0 +1,143 @@
+/**
+ * 图表事件 Hook
+ * 负责图表事件的绑定、解绑和联动
+ */
+import { useEffect, useRef } from 'react';
+import type { Adapter } from '../../../adapters/types';
+import { getChart } from '../../utils/chartInstances';
+
+export interface ChartEventHandlers {
+  onClick?: (params: unknown) => void;
+  onDataZoom?: (params: unknown) => void;
+  onZoom?: (data: { start: number; end: number; dataZoomIndex: number }) => void;
+  onLegendSelect?: (params: { name: string; selected: Record<string, boolean> }) => void;
+  onLegendUnselect?: (params: { name: string; selected: Record<string, boolean> }) => void;
+  onTooltipShow?: (params: unknown) => void;
+  onTooltipHide?: (params: unknown) => void;
+}
+
+export interface ChartLinkageConfig {
+  linkedChartIds?: string[];
+  enableClickLinkage?: boolean;
+  enableZoomLinkage?: boolean;
+  enableLegendLinkage?: boolean;
+}
+
+export interface UseChartEventsOptions extends ChartEventHandlers {
+  chartId?: string;
+  linkageConfig?: ChartLinkageConfig;
+}
+
+export function useChartEvents(
+  adapterRef: React.MutableRefObject<Adapter | null>,
+  options: UseChartEventsOptions
+) {
+  const handlersRef = useRef(options);
+  handlersRef.current = options;
+
+  useEffect(() => {
+    const adapter = adapterRef.current;
+    if (!adapter) return;
+
+    const instance = adapter.getInstance();
+    if (!instance) return;
+
+    const { chartId, linkageConfig = {} } = handlersRef.current;
+
+    // Click 事件
+    if (handlersRef.current.onClick) {
+      instance.on('click', handlersRef.current.onClick);
+
+      // 点击联动
+      if (linkageConfig.enableClickLinkage && chartId && linkageConfig.linkedChartIds) {
+        linkageConfig.linkedChartIds.forEach((linkedChartId) => {
+          const linkedChart = getChart(linkedChartId);
+          if (linkedChart) {
+            linkedChart.dispatchAction({ type: 'highlight', name: '' });
+          }
+        });
+      }
+    }
+
+    // DataZoom 事件
+    if (handlersRef.current.onDataZoom || handlersRef.current.onZoom) {
+      instance.on('datazoom', (params: unknown) => {
+        handlersRef.current.onDataZoom?.(params);
+
+        if (handlersRef.current.onZoom) {
+          const p = params as { start?: number; end?: number; dataZoomIndex?: number };
+          handlersRef.current.onZoom({
+            start: p.start || 0,
+            end: p.end || 100,
+            dataZoomIndex: p.dataZoomIndex || 0,
+          });
+        }
+
+        // 缩放联动
+        if (linkageConfig.enableZoomLinkage && chartId && linkageConfig.linkedChartIds) {
+          linkageConfig.linkedChartIds.forEach((linkedChartId) => {
+            const linkedChart = getChart(linkedChartId);
+            if (linkedChart) {
+              const p = params as { start?: number; end?: number; dataZoomIndex?: number };
+              linkedChart.dispatchAction({
+                type: 'dataZoom',
+                start: p.start,
+                end: p.end,
+                dataZoomIndex: p.dataZoomIndex,
+              });
+            }
+          });
+        }
+      });
+    }
+
+    // Legend 事件
+    if (handlersRef.current.onLegendSelect || handlersRef.current.onLegendUnselect) {
+      instance.on('legendselectchanged', (params: unknown) => {
+        const p = params as { name: string; selected: Record<string, boolean> };
+
+        // Legend 联动
+        if (linkageConfig.enableLegendLinkage && chartId && linkageConfig.linkedChartIds) {
+          linkageConfig.linkedChartIds.forEach((linkedChartId) => {
+            const linkedChart = getChart(linkedChartId);
+            if (linkedChart) {
+              linkedChart.setOption({ legend: { selected: p.selected } });
+            }
+          });
+        }
+
+        if (p.selected[p.name]) {
+          handlersRef.current.onLegendSelect?.(p);
+        } else {
+          handlersRef.current.onLegendUnselect?.(p);
+        }
+      });
+    }
+
+    // Tooltip 事件
+    if (handlersRef.current.onTooltipShow) {
+      instance.on('tooltipshow', handlersRef.current.onTooltipShow);
+    }
+    if (handlersRef.current.onTooltipHide) {
+      instance.on('tooltiphide', handlersRef.current.onTooltipHide);
+    }
+
+    return () => {
+      if (handlersRef.current.onClick) {
+        instance.off('click', handlersRef.current.onClick);
+      }
+      if (handlersRef.current.onDataZoom || handlersRef.current.onZoom) {
+        instance.off('datazoom');
+      }
+      if (handlersRef.current.onLegendSelect || handlersRef.current.onLegendUnselect) {
+        instance.off('legendselectchanged');
+      }
+      if (handlersRef.current.onTooltipShow) {
+        instance.off('tooltipshow');
+      }
+      if (handlersRef.current.onTooltipHide) {
+        instance.off('tooltiphide');
+      }
+    };
+  }, [adapterRef]);
+}

package/src/core/components/hooks/useChartInit.ts

@@ -0,0 +1,80 @@
+/**
+ * 图表初始化 Hook
+ * 负责图表的创建、适配器获取和生命周期管理
+ */
+import { useEffect, useRef } from 'react';
+import { getAdapter } from '../../../adapters';
+import type { Adapter } from '../../../adapters/types';
+import type { EChartsOption } from 'echarts';
+
+export interface UseChartInitOptions {
+  width?: number | string;
+  height?: number | string;
+  theme?: string | object;
+  option?: EChartsOption;
+  onInit?: (instance: unknown) => void;
+  direction?: 'ltr' | 'rtl';
+}
+
+export interface UseChartInitResult {
+  adapterRef: React.MutableRefObject<Adapter | null>;
+  chartRef: React.RefObject<HTMLDivElement | null>;
+  isReady: boolean;
+}
+
+export function useChartInit(
+  containerRef: React.RefObject<HTMLDivElement | null>,
+  options: UseChartInitOptions
+): UseChartInitResult {
+  const adapterRef = useRef<Adapter | null>(null);
+  const isReadyRef = useRef(false);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    let mounted = true;
+    let adapter: Adapter | null = null;
+
+    const initChart = async () => {
+      try {
+        adapter = await getAdapter({
+          width: options.width,
+          height: options.height,
+          theme: options.theme,
+          option: options.option,
+          onInit: options.onInit,
+          containerRef,
+          direction: options.direction,
+        });
+
+        if (!mounted) return;
+        if (!adapter) return;
+
+        adapterRef.current = adapter;
+        isReadyRef.current = true;
+        adapter.init();
+      } catch (error) {
+        console.error('[TaroViz] Failed to initialize chart:', error);
+      }
+    };
+
+    initChart();
+
+    return () => {
+      mounted = false;
+      if (adapter) {
+        adapter.dispose();
+        adapterRef.current = null;
+        isReadyRef.current = false;
+      }
+    };
+  }, []); // 一次性初始化
+
+  return {
+    adapterRef,
+    chartRef: containerRef,
+    get isReady() {
+      return isReadyRef.current;
+    },
+  };
+}

package/src/core/components/hooks/usePerformance.ts

@@ -0,0 +1,186 @@
+/**
+ * 性能监控 Hook
+ * 负责图表性能数据的收集和上报
+ */
+import { useRef, useCallback } from 'react';
+import { PerformanceAnalyzer } from '../../utils/performance';
+import type { EChartsOption } from 'echarts';
+
+export interface PerformanceData {
+  renderTime: number;
+  initTime: number;
+  updateTime: number;
+  dataSize: number;
+}
+
+export interface UsePerformanceOptions {
+  enabled?: boolean;
+  onPerformance?: (data: PerformanceData) => void;
+}
+
+export function usePerformance(options: UsePerformanceOptions = {}) {
+  const { enabled = false, onPerformance } = options;
+
+  const analyzerRef = useRef<PerformanceAnalyzer | null>(null);
+  const perfRef = useRef({
+    initStartTime: 0,
+    initEndTime: 0,
+    renderStartTime: 0,
+    renderEndTime: 0,
+    updateStartTime: 0,
+    updateEndTime: 0,
+    dataSize: 0,
+  });
+
+  /**
+   * 初始化性能分析器
+   */
+  const initAnalyzer = useCallback(() => {
+    if (!enabled) return;
+
+    if (!analyzerRef.current) {
+      analyzerRef.current = PerformanceAnalyzer.getInstance({
+        enabled: true,
+        metrics: ['initTime', 'renderTime', 'updateTime', 'dataSize', 'frameRate'],
+        sampleInterval: 1000,
+        maxSamples: 100,
+        realTime: true,
+        autoStart: true,
+      });
+    }
+  }, [enabled]);
+
+  /**
+   * 记录性能数据
+   */
+  const recordPerformance = useCallback(
+    (type: 'init' | 'render' | 'update', _data?: unknown) => {
+      const now = Date.now();
+      const perf = perfRef.current;
+      const _dataSize = 0; // 可通过参数传入
+
+      switch (type) {
+        case 'init':
+          if (!perf.initStartTime) {
+            perf.initStartTime = now;
+          } else {
+            perf.initEndTime = now;
+            const initTime = perf.initEndTime - perf.initStartTime;
+
+            if (analyzerRef.current) {
+              analyzerRef.current.recordInitTime(initTime);
+            }
+
+            onPerformance?.({
+              renderTime: 0,
+              initTime,
+              updateTime: 0,
+              dataSize: perf.dataSize,
+            });
+          }
+          break;
+
+        case 'render':
+          if (!perf.renderStartTime) {
+            perf.renderStartTime = now;
+          } else {
+            perf.renderEndTime = now;
+            const renderTime = perf.renderEndTime - perf.renderStartTime;
+
+            if (analyzerRef.current) {
+              analyzerRef.current.recordRenderTime(renderTime);
+            }
+
+            onPerformance?.({
+              renderTime,
+              initTime: perf.initEndTime - perf.initStartTime,
+              updateTime: 0,
+              dataSize: perf.dataSize,
+            });
+          }
+          break;
+
+        case 'update':
+          if (!perf.updateStartTime) {
+            perf.updateStartTime = now;
+          } else {
+            perf.updateEndTime = now;
+            const updateTime = perf.updateEndTime - perf.updateStartTime;
+
+            if (analyzerRef.current) {
+              analyzerRef.current.recordUpdateTime(updateTime);
+            }
+
+            onPerformance?.({
+              renderTime: 0,
+              initTime: 0,
+              updateTime,
+              dataSize: perf.dataSize,
+            });
+          }
+          break;
+      }
+    },
+    [onPerformance]
+  );
+
+  /**
+   * 计算数据大小
+   */
+  const calculateDataSize = useCallback((option?: EChartsOption): number => {
+    if (!option) return 0;
+    try {
+      return JSON.stringify(option).length;
+    } catch {
+      return 0;
+    }
+  }, []);
+
+  /**
+   * 更新数据大小
+   */
+  const updateDataSize = useCallback(
+    (option?: EChartsOption) => {
+      perfRef.current.dataSize = calculateDataSize(option);
+      if (analyzerRef.current && option) {
+        analyzerRef.current.recordDataSize(option);
+      }
+    },
+    [calculateDataSize]
+  );
+
+  /**
+   * 获取性能分析器实例
+   */
+  const getAnalyzer = useCallback(() => {
+    return analyzerRef.current;
+  }, []);
+
+  /**
+   * 清理性能监控
+   */
+  const dispose = useCallback(() => {
+    if (analyzerRef.current) {
+      analyzerRef.current.dispose();
+      analyzerRef.current = null;
+    }
+    perfRef.current = {
+      initStartTime: 0,
+      initEndTime: 0,
+      renderStartTime: 0,
+      renderEndTime: 0,
+      updateStartTime: 0,
+      updateEndTime: 0,
+      dataSize: 0,
+    };
+  }, []);
+
+  return {
+    initAnalyzer,
+    recordPerformance,
+    calculateDataSize,
+    updateDataSize,
+    getAnalyzer,
+    dispose,
+  };
+}