@agions/taroviz 1.3.1 → 1.6.0

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

@@ -0,0 +1,156 @@
+/**
+ * 虚拟滚动 Hook
+ * 负责大数据集的分页渲染和数据筛选
+ */
+import { useRef, useCallback } from 'react';
+import type { EChartsOption } from 'echarts';
+
+export interface UseVirtualScrollOptions {
+  enabled?: boolean;
+  pageSize?: number;
+  preloadSize?: number;
+  filters?: Record<string, unknown>;
+}
+
+export interface VirtualScrollState {
+  currentPage: number;
+  totalPages: number;
+  totalDataCount: number;
+  startIndex: number;
+  endIndex: number;
+  isScrolling: boolean;
+}
+
+export function useVirtualScroll(options: UseVirtualScrollOptions = {}) {
+  const { enabled = false, pageSize = 100, preloadSize = 50 } = options;
+
+  const stateRef = useRef<VirtualScrollState>({
+    currentPage: 0,
+    totalPages: 1,
+    totalDataCount: 0,
+    startIndex: 0,
+    endIndex: 0,
+    isScrolling: false,
+  });
+
+  /**
+   * 筛选数据
+   */
+  const filterData = useCallback(
+    (data: unknown[], filters: Record<string, unknown> = {}): unknown[] => {
+      if (!filters || Object.keys(filters).length === 0) {
+        return data;
+      }
+
+      return data.filter((item) => {
+        const record = item as Record<string, unknown>;
+        for (const [key, value] of Object.entries(filters)) {
+          if (record[key] !== value && !(record[key] as unknown[])?.includes?.(value)) {
+            return false;
+          }
+        }
+        return true;
+      });
+    },
+    []
+  );
+
+  /**
+   * 处理虚拟滚动
+   * 返回处理后的配置和当前页数据范围
+   */
+  const processVirtualScroll = useCallback(
+    (
+      originalOption: EChartsOption,
+      filters: Record<string, unknown> = {}
+    ): { processedOption: EChartsOption; state: VirtualScrollState } => {
+      const state = stateRef.current;
+
+      if (!enabled || !originalOption?.series) {
+        return { processedOption: originalOption, state };
+      }
+
+      // 深拷贝避免修改原始数据
+      const processedOption = JSON.parse(JSON.stringify(originalOption)) as EChartsOption;
+
+      (processedOption.series as unknown[]).forEach((seriesItem: unknown, _index: number) => {
+        const s = seriesItem as { data?: unknown[] };
+        if (!s.data || !Array.isArray(s.data)) return;
+
+        // 应用筛选
+        const filteredData = filterData(s.data, filters);
+
+        // 计算分页
+        state.totalDataCount = filteredData.length;
+        state.totalPages = Math.ceil(filteredData.length / pageSize);
+
+        const startIndex = state.currentPage * pageSize;
+        const endIndex = Math.min(startIndex + pageSize + preloadSize, filteredData.length);
+
+        state.startIndex = startIndex;
+        state.endIndex = endIndex;
+
+        // 返回当前页数据
+        s.data = filteredData.slice(startIndex, endIndex);
+      });
+
+      return { processedOption, state };
+    },
+    [enabled, pageSize, preloadSize, filterData]
+  );
+
+  /**
+   * 跳转到指定页
+   */
+  const goToPage = useCallback((page: number) => {
+    const state = stateRef.current;
+    if (page >= 0 && page < state.totalPages) {
+      state.currentPage = page;
+    }
+  }, []);
+
+  /**
+   * 下一页
+   */
+  const nextPage = useCallback(() => {
+    goToPage(stateRef.current.currentPage + 1);
+  }, [goToPage]);
+
+  /**
+   * 上一页
+   */
+  const prevPage = useCallback(() => {
+    goToPage(stateRef.current.currentPage - 1);
+  }, [goToPage]);
+
+  /**
+   * 根据滚动位置更新页码
+   */
+  const updatePageFromScroll = useCallback((scrollPercent: number) => {
+    const state = stateRef.current;
+    const newPage = Math.floor((scrollPercent / 100) * state.totalPages);
+    if (newPage !== state.currentPage && newPage >= 0 && newPage < state.totalPages) {
+      state.currentPage = newPage;
+      return true; // 页码变化
+    }
+    return false; // 页码未变化
+  }, []);
+
+  /**
+   * 设置滚动状态
+   */
+  const setScrolling = useCallback((scrolling: boolean) => {
+    stateRef.current.isScrolling = scrolling;
+  }, []);
+
+  return {
+    stateRef,
+    processVirtualScroll,
+    filterData,
+    goToPage,
+    nextPage,
+    prevPage,
+    updatePageFromScroll,
+    setScrolling,
+  };
+}

package/src/core/echarts.ts

@@ -1,7 +1,7 @@
 /**
  * ECharts 组件注册中心
  * 统一管理所有图表组件的注册，避免重复注册
- * 
+ *
  * 使用 tree-shaking 友好型导入
  * 仅在用户使用特定图表时加载对应模块
  */

package/src/core/themes/ThemeManager.ts

@@ -2,7 +2,6 @@
  * TaroViz 主题系统
  * 支持 CSS 变量、动态主题切换、自定义主题
  */
-import type { EChartsOption } from 'echarts';
 
 // ============================================================================
 // 类型定义
@@ -79,7 +78,17 @@ export interface ThemeVariables {
 /**
  * 预设主题
  */
-export type PresetThemeName = 'default' | 'dark' | 'vintage' | 'macarons' | 'infographic' | 'helianthus' | 'blue' | 'red' | 'green' | 'purple';
+export type PresetThemeName =
+  | 'default'
+  | 'dark'
+  | 'vintage'
+  | 'macarons'
+  | 'infographic'
+  | 'helianthus'
+  | 'blue'
+  | 'red'
+  | 'green'
+  | 'purple';
 
 // ============================================================================
 // 预设主题配置
@@ -112,7 +121,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#3ba272',
       '--tv-chart-color-7': '#fc8452',
       '--tv-chart-color-8': '#9a60b4',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -147,7 +157,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#3ba272',
       '--tv-chart-color-7': '#fc8452',
       '--tv-chart-color-8': '#9a60b4',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -182,7 +193,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#c9b8d4',
       '--tv-chart-color-7': '#a8c4d4',
       '--tv-chart-color-8': '#d4c49a',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -217,7 +229,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#a8e6cf',
       '--tv-chart-color-7': '#ffd3b6',
       '--tv-chart-color-8': '#ffaaa5',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -252,7 +265,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#e8352e',
       '--tv-chart-color-7': '#b02ad3',
       '--tv-chart-color-8': '#6475d4',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -287,7 +301,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#f5a623',
       '--tv-chart-color-7': '#6dd3ce',
       '--tv-chart-color-8': '#d4778b',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -322,7 +337,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#3ba272',
       '--tv-chart-color-7': '#fc8452',
       '--tv-chart-color-8': '#9a60b4',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -357,7 +373,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#52c41a',
       '--tv-chart-color-7': '#faad14',
       '--tv-chart-color-8': '#8b5cf6',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -392,7 +409,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#13c2c2',
       '--tv-chart-color-7': '#fa8c16',
       '--tv-chart-color-8': '#eb2f96',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -427,7 +445,8 @@ const PRESET_THEMES: Record<PresetThemeName, ThemeConfig> = {
       '--tv-chart-color-6': '#ff4d4f',
       '--tv-chart-color-7': '#13c2c2',
       '--tv-chart-color-8': '#fa8c16',
-      '--tv-font-family': '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+      '--tv-font-family':
+        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
       '--tv-font-size': '14px',
       '--tv-font-size-small': '12px',
       '--tv-font-size-large': '16px',
@@ -619,9 +638,6 @@ class ThemeManager {
 // 导出单例实例
 export const themeManager = ThemeManager.getInstance();
 
-// 导出类型
-export type { ThemeConfig, ThemeVariables, PresetThemeName };
-
 // 导出预设主题
 export { PRESET_THEMES };
 

package/src/core/types/index.ts

@@ -230,9 +230,9 @@ export interface Adapter {
   convertToDataURL?(opts?: any): string | undefined;
 
   /**
-   * 渲染图表
+   * 渲染图表（仅 H5 环境需要，小程序适配器不需要）
    */
-  render(): JSX.Element;
+  render?(): JSX.Element | null;
 }
 
 /**

package/src/core/utils/chartInstances.ts

@@ -14,7 +14,9 @@ export function registerChart(id: string, instance: EChartsType): void {
   // 如果已存在同名ID，先释放旧实例防止内存泄漏
   if (CHART_INSTANCES[id]) {
     try {
-      console.warn(`[TaroViz] Chart instance '${id}' already exists, replacing and disposing old instance`);
+      console.warn(
+        `[TaroViz] Chart instance '${id}' already exists, replacing and disposing old instance`
+      );
       CHART_INSTANCES[id].dispose();
     } catch (e) {
       console.warn(`Failed to dispose old chart instance: ${id}`, e);
@@ -38,16 +40,21 @@ export function getChart(id: string): EChartsType | undefined {
  */
 export function removeChart(id: string): void {
   if (CHART_INSTANCES[id]) {
+    try {
+      CHART_INSTANCES[id].dispose();
+    } catch (e) {
+      console.warn(`Failed to dispose chart on removal: ${id}`, e);
+    }
     delete CHART_INSTANCES[id];
   }
 }
 
 /**
  * 获取所有图表实例
- * @returns 所有图表实例
+ * @returns 所有图表实例的浅拷贝
  */
 export function getAllCharts(): Record<string, EChartsType> {
-  return CHART_INSTANCES;
+  return { ...CHART_INSTANCES };
 }
 
 /**

package/src/core/utils/chartUtils.ts

@@ -0,0 +1,46 @@
+/**
+ * Chart utilities shared between BaseChart and BaseChartWrapper
+ */
+import type { EChartsOption } from 'echarts';
+
+/**
+ * Normalize size value to CSS string
+ */
+export function normalizeSize(value: number | string | undefined, fallback: string): string {
+  if (value === undefined) return fallback;
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
+/**
+ * Calculate total data points in an ECharts option for animation optimization
+ */
+export function calculateDataLength(option: { series?: unknown } | undefined): number {
+  if (!option) return 0;
+  let count = 0;
+  if (option.series) {
+    const series = Array.isArray(option.series) ? option.series : [option.series];
+    for (const seriesItem of series as any[]) {
+      if (seriesItem.data) {
+        if (Array.isArray(seriesItem.data)) {
+          count += seriesItem.data.length;
+        } else if (typeof seriesItem.data === 'object') {
+          count += Object.keys(seriesItem.data).length;
+        }
+      }
+    }
+  }
+  return count;
+}
+
+/**
+ * Filter data by filter conditions
+ */
+export function filterDataByKeys(data: any[], filters: Record<string, any>): any[] {
+  if (!filters || Object.keys(filters).length === 0) return data;
+  return data.filter((item) => {
+    for (const [key, value] of Object.entries(filters)) {
+      if (item[key] !== value && !item[key]?.includes?.(value)) return false;
+    }
+    return true;
+  });
+}

package/src/core/utils/common.ts

@@ -20,7 +20,20 @@ export const isBrowser = typeof window !== 'undefined' && typeof document !== 'u
  * 是否为NodeJS环境
  * @returns 是否为NodeJS环境
  */
-export const isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+export const isNode = (() => {
+  // 更可靠的环境检测：检查是否是真正的 Node.js 环境
+  // 而不是打包后的代码（如 webpack 定义的 process.env）
+  try {
+    return (
+      typeof process !== 'undefined' &&
+      process.versions &&
+      process.versions.node &&
+      Object.prototype.toString.call(globalThis.process) === '[object process]'
+    );
+  } catch {
+    return false;
+  }
+})();
 
 /**
  * 是否为React Native环境

package/src/core/utils/export/ExportUtils.ts

@@ -103,7 +103,7 @@ function dataURLToBlob(dataURL: string): Blob {
 /**
  * 下载文件
  */
-function downloadFile(data: string | Blob, filename: string, mimeType: string): void {
+function downloadFile(data: string | Blob, filename: string, _mimeType: string): void {
   const blob = typeof data === 'string' ? dataURLToBlob(data) : data;
   const url = URL.createObjectURL(blob);
 
@@ -142,19 +142,12 @@ class ChartExporter {
   /**
    * 导出图表为图片
    */
-  static exportImage(
-    chart: ECharts,
-    options: ExportImageOptions = {}
-  ): ExportResult {
-    const {
-      type = 'png',
-      pixelRatio = 2,
-      backgroundColor = '#ffffff',
-      quality = 0.8,
-    } = options;
+  static exportImage(chart: ECharts, options: ExportImageOptions = {}): ExportResult {
+    const { type = 'png', pixelRatio = 2, backgroundColor = '#ffffff', quality = 0.8 } = options;
 
     const mimeType = `image/${type}`;
-    const data = chart.getDataURL({
+    // 使用 any 避免 ECharts 类型定义与实际支持类型不匹配
+    const data = (chart.getDataURL as any)({
       type,
       pixelRatio,
       backgroundColor,
@@ -174,8 +167,9 @@ class ChartExporter {
   static exportSVG(chart: ECharts, options: ExportSVGOptions = {}): ExportResult {
     const { compress = false } = options;
 
-    const svgData = chart.getSvgData();
-    if (!svgData) {
+    // ECharts 5.x 使用 getDataURL 获取 SVG
+    const svgData = (chart.getDataURL as any)({ type: 'svg' });
+    if (!svgData || svgData === 'data:image/svg+xml;charset=utf8,') {
       throw new Error('SVG export is not supported. Please use canvas renderer.');
     }
 
@@ -198,10 +192,7 @@ class ChartExporter {
   /**
    * 导出图表为 PDF (需要 jspdf 库支持)
    */
-  static async exportPDF(
-    chart: ECharts,
-    options: ExportPDFOptions = {}
-  ): Promise<ExportResult> {
+  static async exportPDF(chart: ECharts, options: ExportPDFOptions = {}): Promise<ExportResult> {
     const {
       orientation = 'portrait',
       pageSize = 'a4',
@@ -222,7 +213,7 @@ class ChartExporter {
     let jsPDF: any;
     try {
       // 尝试使用动态导入，使用 webpackIgnore 注释避免预解析
-      // @ts-ignore - 动态导入
+      // @ts-expect-error - 动态导入
       jsPDF = (await import(/* webpackIgnore: true */ 'jspdf')).default;
     } catch {
       // 如果没有 jspdf，提供备选方案
@@ -283,7 +274,7 @@ class ChartExporter {
     doc.addImage(imageData, 'PNG', chartX, chartY, chartWidth, chartHeight);
 
     // 添加页脚
-    const footerY = pageHeight - margin.bottom / 2;
+    const footerY = pageHeight - (margin.bottom ?? 40) / 2;
     doc.setFontSize(10);
     doc.setTextColor(153, 153, 153);
     doc.text(`Generated by TaroViz on ${new Date().toLocaleDateString()}`, marginLeft, footerY);
@@ -306,7 +297,7 @@ class ChartExporter {
     charts: Array<{ name: string; chart: ECharts }>,
     options: BatchExportOptions
   ): Promise<ExportResult[]> {
-    const { format, filenamePrefix = 'chart', compress } = options;
+    const { format, filenamePrefix: _filenamePrefix = 'chart', compress } = options;
 
     const results: ExportResult[] = [];
 
@@ -347,7 +338,7 @@ class ChartExporter {
   static async copyToClipboard(chart: ECharts, options: ExportImageOptions = {}): Promise<boolean> {
     try {
       const result = this.exportImage(chart, { ...options, type: 'png' });
-      const blob = dataURLToBlob(result.data);
+      const blob = dataURLToBlob(result.data as string);
 
       await navigator.clipboard.write([
         new ClipboardItem({

package/src/core/utils/performance/PerformanceAnalyzer.ts

@@ -156,6 +156,27 @@ export class PerformanceAnalyzer {
     this.emit(PerformanceEventType.MONITORING_END);
   }
 
+  /**
+   * 释放资源
+   * 完全清理性能分析器，包括单例实例
+   */
+  public dispose(): void {
+    this.stop();
+    this.metrics.clear();
+    this.eventHandlers.clear();
+    this.frameRateHistory = [];
+
+    // 如果是当前单例，清除单例引用
+    if (PerformanceAnalyzer.instance === this) {
+      PerformanceAnalyzer.instance = null;
+    }
+  }
+
+  /**
+   * RAF 动画帧 ID，用于取消
+   */
+  private rafId: number | null = null;
+
   /**
    * 开始帧率监控
    */
@@ -169,23 +190,29 @@ export class PerformanceAnalyzer {
       const deltaTime = currentTime - this.lastFrameTime;
       const frameRate = deltaTime > 0 ? Math.round(1000 / deltaTime) : 0;
 
-      this.frameRateHistory.push(frameRate);
-      if (this.frameRateHistory.length > 60) {
+      // 使用 config.maxSamples 限制历史记录长度
+      const maxSamples = this.config.maxSamples ?? 100;
+      if (this.frameRateHistory.length >= maxSamples) {
         this.frameRateHistory.shift();
       }
+      this.frameRateHistory.push(frameRate);
 
       this.lastFrameTime = currentTime;
-      requestAnimationFrame(updateFrameRate);
+      this.rafId = requestAnimationFrame(updateFrameRate);
     };
 
-    requestAnimationFrame(updateFrameRate);
+    this.rafId = requestAnimationFrame(updateFrameRate);
   }
 
   /**
    * 停止帧率监控
    */
   private stopFrameRateMonitoring(): void {
-    // requestAnimationFrame 会自动停止，不需要额外清理
+    // 取消 RAF 循环，防止继续运行
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
     this.frameRateHistory = [];
   }
 

package/src/core/utils/uuid.ts

@@ -8,7 +8,7 @@ export function uuid(): string {
   if (typeof globalThis.crypto?.randomUUID === 'function') {
     return globalThis.crypto.randomUUID();
   }
-  
+
   // 回退：使用 Math.random() + 时间戳混合
   const timestamp = Date.now().toString(36);
   const randomPart = Math.random().toString(36).substring(2, 15);