@agions/taroviz 1.11.1 → 2.0.3

package/src/core/utils/drillDownHelpers.ts

@@ -0,0 +1,426 @@
+/**
+ * DrillDown 辅助函数
+ * 将 createDrillDown 中的逻辑拆分为独立函数，提高代码可维护性
+ */
+
+import type { ECharts, EChartsOption, ECElementEvent } from 'echarts';
+import type { DrillDownSource, DrillDownConfig } from './drillDown';
+
+// ============================================================================
+// 图表配置构建
+// ============================================================================
+
+/**
+ * 从 DrillDownSource 数组构建 ECharts option
+ */
+export function buildOptionFromSources(sources: DrillDownSource[]): EChartsOption {
+  if (!sources || sources.length === 0) return {};
+
+  const names = sources.map((s) => s.name);
+  const values = sources.map((s) => s.value);
+
+  return {
+    xAxis: {
+      type: 'category',
+      data: names,
+    },
+    yAxis: {
+      type: 'value',
+    },
+    series: [
+      {
+        type: 'bar',
+        data: values,
+      },
+    ],
+  };
+}
+
+// ============================================================================
+// 下钻配置获取
+// ============================================================================
+
+/**
+ * 根据层级和触发数据项获取下钻后的图表配置
+ */
+export function getDrillDownOption(
+  level: number,
+  dataItem: DrillDownSource | undefined,
+  direction: 'down' | 'up' | 'reset',
+  sources: DrillDownSource[],
+  initialSources: DrillDownSource[] | undefined,
+  currentOption: EChartsOption,
+  initialOption: Record<string, unknown>
+): EChartsOption {
+  let targetOption: EChartsOption = {};
+
+  if (direction === 'reset' || level === 0) {
+    // 重置或回到第一层：使用初始数据
+    if (initialSources) {
+      targetOption = buildOptionFromSources(initialSources);
+    } else {
+      targetOption = {};
+    }
+  } else if (direction === 'up') {
+    // 上钻：从 history 中找到上一层的状态
+    if (sources.length > 0 && sources[0].chartOption) {
+      targetOption = sources[0].chartOption;
+    } else {
+      targetOption = buildOptionFromSources(sources);
+    }
+  } else if (direction === 'down' && dataItem) {
+    // 下钻
+    if (dataItem.chartOption) {
+      // 优先使用自定义 chartOption
+      targetOption = dataItem.chartOption;
+    } else if (dataItem.children && dataItem.children.length > 0) {
+      // 从 children 构建图表 option
+      targetOption = buildOptionFromSources(dataItem.children);
+    }
+  }
+
+  return targetOption;
+}
+
+// ============================================================================
+// 数据源获取
+// ============================================================================
+
+/**
+ * 获取当前层级的数据源列表
+ */
+export function getCurrentLevelSources(
+  currentLevel: number,
+  initialSources: DrillDownSource[] | undefined,
+  history: Array<{ level: number; dataItem: DrillDownSource }>
+): DrillDownSource[] {
+  if (currentLevel === 0) {
+    // 第 0 层：使用 initialSources
+    return initialSources ?? [];
+  }
+
+  // 其他层级：从 history 中找到上一层点击的数据项的 children
+  const lastHistory = history[history.length - 1];
+  if (lastHistory && lastHistory.dataItem.children) {
+    return lastHistory.dataItem.children;
+  }
+
+  return [];
+}
+
+// ============================================================================
+// 下钻执行
+// ============================================================================
+
+/**
+ * 检查是否有下钻数据
+ */
+export function hasDrillDownData(
+  dataItem: DrillDownSource | undefined
+): dataItem is DrillDownSource {
+  if (!dataItem) return false;
+  return !!(dataItem.children && dataItem.children.length > 0) || !!dataItem.chartOption;
+}
+
+/**
+ * 在当前层级数据中查找匹配的数据项
+ */
+export function findMatchedSource(
+  name: string | number,
+  value: unknown,
+  currentLevelSources: DrillDownSource[],
+  initialSources: DrillDownSource[] | undefined,
+  currentLevel: number
+): DrillDownSource | undefined {
+  // 在当前层级的数据中查找匹配项
+  let matchedSource = currentLevelSources.find(
+    (s) => String(s.name) === String(name) || s.value === value
+  );
+
+  // 如果没找到，尝试在 initialSources 中查找
+  if (!matchedSource && currentLevel === 0 && initialSources) {
+    matchedSource = initialSources.find(
+      (s) => String(s.name) === String(name) || s.value === value
+    );
+  }
+
+  return matchedSource;
+}
+
+/**
+ * 执行下钻操作
+ */
+export function executeDrillDown(
+  params: ECElementEvent,
+  state: {
+    chartInstance: ECharts | null;
+    config: DrillDownConfig;
+    currentLevel: number;
+    history: Array<{ level: number; dataItem: DrillDownSource }>;
+    currentOption: EChartsOption;
+  }
+): boolean {
+  const { chartInstance, config } = state;
+  if (!chartInstance) return false;
+
+  const { name, value } = params;
+
+  // 获取当前层级数据源
+  const currentLevelSources = getCurrentLevelSources(
+    state.currentLevel,
+    config.initialSources,
+    state.history
+  );
+
+  // 查找匹配项
+  const matchedSource = findMatchedSource(
+    name,
+    value,
+    currentLevelSources,
+    config.initialSources,
+    state.currentLevel
+  );
+
+  // 如果没有下钻数据，不执行
+  if (!hasDrillDownData(matchedSource)) {
+    console.warn('[DrillDown] No drill-down data available for:', name);
+    return false;
+  }
+
+  // 记录历史
+  if (matchedSource) {
+    state.history.push({ level: state.currentLevel, dataItem: matchedSource });
+  }
+
+  // 更新层级
+  state.currentLevel += 1;
+
+  // 获取新的图表配置
+  const newOption = getDrillDownOption(
+    state.currentLevel,
+    matchedSource,
+    'down',
+    matchedSource.children ?? [],
+    config.initialSources,
+    state.currentOption,
+    {}
+  );
+
+  // 更新图表
+  if (newOption && Object.keys(newOption).length > 0) {
+    chartInstance.setOption(newOption, true);
+    state.currentOption = newOption;
+  }
+
+  // 触发回调
+  config.onDrillDown?.({
+    level: state.currentLevel,
+    name: matchedSource?.name ?? (name as string | number),
+    value: matchedSource?.value ?? value,
+    sources: matchedSource?.children ?? [],
+    chartOption: newOption,
+    rawParams: params as unknown as Record<string, unknown>,
+  });
+
+  return true;
+}
+
+// ============================================================================
+// 状态管理
+// ============================================================================
+
+/**
+ * 执行上钻操作
+ */
+export function executeDrillUp(
+  state: {
+    chartInstance: ECharts | null;
+    currentLevel: number;
+    history: Array<{ level: number; dataItem: DrillDownSource }>;
+    currentOption: EChartsOption;
+    initialOption: Record<string, unknown>;
+  },
+  config: DrillDownConfig
+): boolean {
+  const { chartInstance } = state;
+  if (!chartInstance || state.currentLevel <= 0) {
+    console.warn('[DrillDown] Cannot drill up: already at top level');
+    return false;
+  }
+
+  const previousLevel = state.currentLevel;
+
+  // 弹出历史
+  state.history.pop();
+
+  // 更新层级
+  state.currentLevel -= 1;
+
+  // 获取当前层级数据源
+  const currentLevelSources = getCurrentLevelSources(
+    state.currentLevel,
+    config.initialSources,
+    state.history
+  );
+
+  // 获取新的图表配置
+  const newOption = getDrillDownOption(
+    state.currentLevel,
+    undefined,
+    'up',
+    currentLevelSources,
+    config.initialSources,
+    state.currentOption,
+    state.initialOption
+  );
+
+  // 更新图表
+  if (newOption && Object.keys(newOption).length > 0) {
+    chartInstance.setOption(newOption, true);
+    state.currentOption = newOption;
+  } else if (state.currentLevel === 0 && state.initialOption) {
+    chartInstance.setOption(state.initialOption as EChartsOption, true);
+    state.currentOption = state.initialOption as EChartsOption;
+  }
+
+  // 触发回调
+  config.onDrillUp?.({
+    previousLevel,
+    currentLevel: state.currentLevel,
+    chartOption: newOption,
+  });
+
+  return true;
+}
+
+/**
+ * 执行重置操作
+ */
+export function executeReset(
+  state: {
+    chartInstance: ECharts | null;
+    currentLevel: number;
+    history: Array<{ level: number; dataItem: DrillDownSource }>;
+    currentOption: EChartsOption;
+    initialOption: Record<string, unknown>;
+  },
+  config: DrillDownConfig
+): void {
+  const { chartInstance } = state;
+  if (!chartInstance) return;
+
+  // 清空历史
+  state.history = [];
+  state.currentLevel = 0;
+
+  // 获取当前层级数据源
+  const currentLevelSources = getCurrentLevelSources(
+    state.currentLevel,
+    config.initialSources,
+    state.history
+  );
+
+  // 获取初始配置
+  const newOption = getDrillDownOption(
+    0,
+    undefined,
+    'reset',
+    currentLevelSources,
+    config.initialSources,
+    state.currentOption,
+    state.initialOption
+  );
+
+  // 更新图表
+  if (newOption && Object.keys(newOption).length > 0) {
+    chartInstance.setOption(newOption, true);
+    state.currentOption = newOption;
+  } else if (state.initialOption && Object.keys(state.initialOption).length > 0) {
+    chartInstance.setOption(state.initialOption as EChartsOption, true);
+    state.currentOption = state.initialOption as EChartsOption;
+  }
+
+  // 触发回调
+  config.onReset?.({ level: 0 });
+}
+
+/**
+ * 执行跳转到指定层级
+ */
+export function executeDrillTo(
+  level: number,
+  dataItem: DrillDownSource | undefined,
+  state: {
+    chartInstance: ECharts | null;
+    currentLevel: number;
+    history: Array<{ level: number; dataItem: DrillDownSource }>;
+    currentOption: EChartsOption;
+  },
+  config: DrillDownConfig
+): void {
+  const { chartInstance } = state;
+  if (!chartInstance) return;
+
+  if (level < 0 || level > state.history.length) {
+    console.warn('[DrillDown] Invalid drill level:', level);
+    return;
+  }
+
+  const previousLevel = state.currentLevel;
+  state.currentLevel = level;
+
+  if (level === state.history.length) {
+    // 下钻
+    if (dataItem) {
+      state.history.push({ level: level - 1, dataItem });
+    }
+  } else if (level < state.history.length) {
+    // 上钻或跳转：调整 history
+    state.history = state.history.slice(0, level);
+  } else {
+    // level === 0, reset
+    state.history = [];
+  }
+
+  // 获取当前层级数据源
+  const currentLevelSources = getCurrentLevelSources(
+    state.currentLevel,
+    config.initialSources,
+    state.history
+  );
+
+  const newOption = getDrillDownOption(
+    level,
+    dataItem,
+    level === 0 ? 'reset' : 'down',
+    currentLevelSources,
+    config.initialSources,
+    state.currentOption,
+    {}
+  );
+
+  if (newOption && Object.keys(newOption).length > 0) {
+    chartInstance.setOption(newOption, true);
+    state.currentOption = newOption;
+  }
+
+  // 触发回调
+  if (level > previousLevel) {
+    config.onDrillDown?.({
+      level,
+      name: dataItem?.name ?? '',
+      value: dataItem?.value ?? 0,
+      sources: dataItem?.children ?? [],
+      chartOption: newOption,
+      rawParams: {},
+    });
+  } else if (level < previousLevel) {
+    config.onDrillUp?.({
+      previousLevel,
+      currentLevel: level,
+      chartOption: newOption,
+    });
+  } else {
+    config.onReset?.({ level: 0 });
+  }
+}

package/src/core/utils/events.ts

@@ -0,0 +1,12 @@
+/**
+ * 事件名称常量定义
+ */
+export const events = {
+  click: 'click',
+  mousemove: 'mousemove',
+  mouseup: 'mouseup',
+  mousedown: 'mousedown',
+  mouseover: 'mouseover',
+  mouseout: 'mouseout',
+  globalout: 'globalout',
+};

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

@@ -1,8 +1,10 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 /**
  * TaroViz 图表导出工具
  * 支持导出为 PNG、JPEG、SVG、PDF 等格式
  */
 import type { ECharts } from 'echarts';
+import { generateFormattedFilename, downloadBlob, downloadFile, dataURLToBlob } from '../download';
 
 // ============================================================================
 // 类型定义
@@ -17,7 +19,7 @@ type ExportImageType = 'png' | 'jpeg' | 'svg' | 'webp' | 'gif';
 /**
  * getDataURL 方法参数（基于 ECharts 官方类型，扩展 webp/gif 支持）
  */
-interface EChartsDataURLOptions {
+interface __EChartsDataURLOptions {
   type?: ExportImageType;
   pixelRatio?: number;
   backgroundColor?: string;
@@ -30,11 +32,18 @@ interface EChartsDataURLOptions {
  */
 interface JSPDFInstance {
   setProperties(props: Record<string, string>): void;
-  setFontSize(size: number): void;
-  setTextColor(r: number, g: number, b: number): void;
-  text(text: string, x: number, y: number): void;
-  addImage(imageData: string, format: string, x: number, y: number, width: number, height: number): void;
-  output(type: 'blob'): Blob;
+  setFontSize(size: number): JSPDFInstance;
+  setTextColor(r: number, g: number, b: number): JSPDFInstance;
+  text(text: string, x: number, y: number): JSPDFInstance;
+  addImage(
+    imageData: string,
+    format: string,
+    x: number,
+    y: number,
+    width: number,
+    height: number
+  ): JSPDFInstance;
+  output(type: string): Blob | string | Uint8Array;
 }
 
 /**
@@ -123,52 +132,6 @@ export interface ExportResult {
 // 工具函数
 // ============================================================================
 
-/**
- * 将 Data URL 转换为 Blob
- */
-function dataURLToBlob(dataURL: string): Blob {
-  const arr = dataURL.split(',');
-  const mime = arr[0].match(/:(.*?);/)?.[1] || 'image/png';
-  const bstr = atob(arr[1]);
-  let n = bstr.length;
-  const u8arr = new Uint8Array(n);
-  while (n--) {
-    u8arr[n] = bstr.charCodeAt(n);
-  }
-  return new Blob([u8arr], { type: mime });
-}
-
-/**
- * 下载文件
- */
-function downloadFile(data: string | Blob, filename: string, _mimeType: string): void {
-  const blob = typeof data === 'string' ? dataURLToBlob(data) : data;
-  const url = URL.createObjectURL(blob);
-
-  const link = document.createElement('a');
-  link.href = url;
-  link.download = filename;
-  link.style.display = 'none';
-
-  document.body.appendChild(link);
-  link.click();
-
-  // 清理
-  setTimeout(() => {
-    document.body.removeChild(link);
-    URL.revokeObjectURL(url);
-  }, 100);
-}
-
-/**
- * 生成文件名
- */
-function generateFilename(name: string, format: string): string {
-  const timestamp = new Date().toISOString().slice(0, 10);
-  const sanitizedName = name.replace(/[^a-zA-Z0-9\u4e00-\u9fa5]/g, '_');
-  return `${sanitizedName}_${timestamp}.${format}`;
-}
-
 // ============================================================================
 // 导出类
 // ============================================================================
@@ -194,7 +157,7 @@ class ChartExporter {
 
     return {
       data,
-      filename: generateFilename('chart', type),
+      filename: generateFormattedFilename('chart', type),
       mimeType,
     };
   }
@@ -222,7 +185,7 @@ class ChartExporter {
 
     return {
       data,
-      filename: generateFilename('chart', 'svg'),
+      filename: generateFormattedFilename('chart', 'svg'),
       mimeType,
     };
   }
@@ -250,16 +213,15 @@ class ChartExporter {
     // 动态导入 jspdf
     let JSPDFClass: new (options: Record<string, string>) => JSPDFInstance;
     try {
-      // 尝试使用动态导入，使用 webpackIgnore 注释避免预解析
-      // @ts-expect-error - 动态导入
+      // @ts-expect-error - 动态导入，使用 webpackIgnore 注释避免预解析
       const module = await import(/* webpackIgnore: true */ 'jspdf');
       JSPDFClass = module.default as new (options: Record<string, string>) => JSPDFInstance;
     } catch {
-      // 如果没有 jspdf，提供备选方案
-      console.warn('[TaroViz] jspdf not found, falling back to image download');
+      // 如果没有 jspdf，提供备选方案（返回 PNG 而非 PDF）
+      console.warn('[TaroViz] jspdf not found, falling back to PNG export');
       return {
         data: imageData,
-        filename: generateFilename('chart', 'png'),
+        filename: generateFormattedFilename('chart', 'png'),
         mimeType: 'image/png',
       };
     }
@@ -301,9 +263,7 @@ class ChartExporter {
 
     // 添加标题
     if (includeTitle) {
-      doc.setFontSize(16);
-      doc.setTextColor(51, 51, 51);
-      doc.text(title, marginLeft, marginTop);
+      doc.setFontSize(16).setTextColor(51, 51, 51).text(title, marginLeft, marginTop);
     }
 
     // 添加图表
@@ -314,16 +274,25 @@ class ChartExporter {
 
     // 添加页脚
     const footerY = pageHeight - (margin.bottom ?? 40) / 2;
-    doc.setFontSize(10);
-    doc.setTextColor(153, 153, 153);
+    doc.setFontSize(10).setTextColor(153, 153, 153);
     doc.text(`Generated by TaroViz on ${new Date().toLocaleDateString()}`, marginLeft, footerY);
 
-    // 导出为 Blob
-    const pdfBlob = doc.output('blob') as Blob;
+    // 导出为 Blob（兼容不同版本的 jsPDF output 返回类型）
+    let pdfBlob: Blob;
+    const outputResult = doc.output('blob');
+    if (outputResult instanceof Blob) {
+      pdfBlob = outputResult;
+    } else if (typeof outputResult === 'string') {
+      pdfBlob = new Blob([outputResult], { type: 'application/pdf' });
+    } else {
+      pdfBlob = new Blob([new Uint8Array(outputResult as unknown as ArrayBuffer)], {
+        type: 'application/pdf',
+      });
+    }
 
     return {
       data: pdfBlob,
-      filename: generateFilename(title.replace(/\s+/g, '_'), 'pdf'),
+      filename: generateFormattedFilename(title.replace(/\s+/g, '_'), 'pdf'),
       mimeType: 'application/pdf',
       size: pdfBlob.size,
     };

package/src/core/utils/format.ts

@@ -0,0 +1,44 @@
+/**
+ * 格式化数值
+ * @param value 要格式化的数值
+ * @param digits 小数位数
+ * @param options 配置选项
+ * @returns 格式化后的字符串
+ */
+export function formatNumber(
+  value: number,
+  digits: number = 2,
+  options: {
+    useGrouping?: boolean;
+    locale?: string;
+  } = {}
+): string {
+  const { useGrouping = true, locale = 'zh-CN' } = options;
+
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+    useGrouping,
+  }).format(value);
+}
+
+/**
+ * 获取颜色的对比色
+ * @param color 十六进制颜色值
+ * @returns 对比色
+ */
+export function getContrastColor(color: string): string {
+  // 移除#前缀
+  const hex = color.replace('#', '');
+
+  // 转换为RGB
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+
+  // 计算亮度
+  const brightness = (r * 299 + g * 587 + b * 114) / 1000;
+
+  // 根据亮度返回黑色或白色
+  return brightness > 128 ? '#000000' : '#FFFFFF';
+}