@agions/taroviz 1.11.1 → 2.0.3

package/src/charts/types.ts

@@ -3,6 +3,7 @@
  */
 import type { CSSProperties, ReactNode } from 'react';
 import type { EChartsOption, ECharts } from 'echarts';
+import type { AnimationConfig } from '../core/animation/types';
 
 // ============================================================================
 // 基础类型定义
@@ -163,24 +164,8 @@ export interface ChartData {
 // 动画配置
 // ============================================================================
 
-/** 动画配置 */
-export interface AnimationConfig {
-  /** 是否启用动画 */
-  enabled?: boolean;
-  /** 动画时长 (ms) */
-  duration?: number;
-  /** 动画缓动函数 */
-  easing?: string;
-  /** 动画延迟 (ms) */
-  delay?: number;
-  /** 是否在渲染时使用动画 */
-  animate?: boolean;
-  /** 是否在数据更新时使用动画 */
-  animateUpdate?: boolean;
-}
-
 // ============================================================================
-// 基础图表属性
+// 事件回调类型
 // ============================================================================
 
 /**
@@ -472,81 +457,145 @@ export interface ScatterChartProps extends BaseChartProps {
 /**
  * 雷达图属性
  */
-export interface RadarChartProps extends BaseChartProps {
-  /** 雷达图指示器 */
-  indicators?: Array<{ name: string; max?: number; color?: string }>;
+export interface RadarIndicator {
+  /** 指标名称 */
+  name: string;
+  /** 最大值 */
+  max: number;
+  /** 最小值（可选，默认 0） */
+  min?: number;
+}
 
-  /** 雷达图形状 */
-  shape?: 'polygon' | 'circle';
+/** 雷达图数据系列项 */
+export interface RadarDataItem {
+  /** 数据值数组，对应每个 indicator 的值 */
+  value: number[];
+  /** 系列名称 */
+  name?: string;
+}
 
-  /** 中心点 */
-  center?: [number | string, number | string];
+/** 雷达图面积样式配置 */
+export interface RadarAreaStyle {
+  /** 是否显示面积填充 */
+  show?: boolean;
+  /** 填充颜色 */
+  color?: string;
+  /** 透明度 */
+  opacity?: number;
+}
 
-  /** 半径 */
-  radius?: number | string;
+/** 雷达图线样式配置 */
+export interface RadarLineStyle {
+  /** 线宽 */
+  width?: number;
+  /** 线型 */
+  type?: 'solid' | 'dashed' | 'dotted';
+  /** 颜色 */
+  color?: string;
+}
+
+/** 雷达图标签配置 */
+export interface RadarLabel {
+  /** 是否显示标签 */
+  show?: boolean;
+  /** 标签位置 */
+  position?: 'inside' | 'outside' | 'center';
+  /** 标签格式化 */
+  formatter?: string | ((value: number, indicator: RadarIndicator) => string);
+}
+
+/**
+ * 雷达图属性
+ */
+export interface RadarChartProps extends Omit<BaseChartProps, 'data'> {
+  /** 雷达图指示器 */
+  indicators: RadarIndicator[];
+  /** 雷达图数据系列 */
+  data: RadarDataItem[];
+  /** 起始角度（0-360，默认 90） */
+  startAngle?: number;
+  /** 是否显示中心圆环 */
+  centerCircle?: boolean;
+  /** 中心圆环半径（0-1，默认 0） */
+  centerCircleSize?: number;
+  /** 面积样式 */
+  areaStyle?: RadarAreaStyle;
+  /** 线样式 */
+  lineStyle?: RadarLineStyle;
+  /** 标签配置 */
+  label?: RadarLabel;
+  /** 是否平滑曲线 */
+  smooth?: boolean;
+  /** 自定义 ECharts option 合并 */
+  optionMerge?: Partial<EChartsOption>;
+}
+
+/**
+ * 漏斗图数据项
+ */
+export interface FunnelDataItem {
+  /** 数值 */
+  value: number;
+  /** 名称 */
+  name: string;
 }
 
 /**
  * 漏斗图属性
  */
-export interface FunnelChartProps extends BaseChartProps {
+export interface FunnelChartProps extends Omit<BaseChartProps, 'data'> {
+  /** 漏斗数据 */
+  data?: FunnelDataItem[];
   /** 漏斗排序方式 */
   sort?: 'ascending' | 'descending' | 'none';
-
   /** 漏斗对齐方式 */
   align?: 'left' | 'center' | 'right';
-
   /** 间隙 */
   gap?: number;
-
   /** 最小高度 */
   min?: number;
-
   /** 最大高度 */
   max?: number;
+  /** 自定义 ECharts option 合并 */
+  optionMerge?: Partial<EChartsOption>;
 }
 
 /**
- * 仪表盘属性
+ * 热力图数据项
  */
-export interface GaugeChartProps extends BaseChartProps {
-  /** 最小值 */
-  min?: number;
-
-  /** 最大值 */
-  max?: number;
-
-  /** 当前值 */
-  value?: number;
-
-  /** 刻度分段数 */
-  splitNumber?: number;
-
-  /** 半径 */
-  radius?: number | string;
-
-  /** 起始角度 */
-  startAngle?: number;
-
-  /** 结束角度 */
-  endAngle?: number;
+export interface HeatmapDataItem {
+  /** X 轴索引或值 */
+  x: number | string;
+  /** Y 轴索引或值 */
+  y: number | string;
+  /** 热力值 */
+  value: number;
+}
 
-  /** 进度显示 */
-  showProgress?: boolean;
+/**
+ * 热力图 X/Y 轴配置
+ */
+export interface HeatmapAxis {
+  /** 轴标签 */
+  name?: string;
+  /** 轴数据 */
+  data?: (string | number)[];
 }
 
 /**
  * 热力图属性
  */
-export interface HeatmapChartProps extends BaseChartProps {
+export interface HeatmapChartProps extends Omit<BaseChartProps, 'data'> {
   /** X 轴数据 */
-  xAxisData?: (string | number)[];
-
+  xData?: (string | number)[];
   /** Y 轴数据 */
-  yAxisData?: (string | number)[];
-
+  yData?: (string | number)[];
+  /** 热力图数据 */
+  data?: HeatmapDataItem[];
   /** 视觉映射配置 */
   visualMap?: Record<string, unknown>;
+  /** 自定义 ECharts option 合并 */
+  optionMerge?: Partial<EChartsOption>;
 }
 
 /**
@@ -707,6 +756,8 @@ export interface SankeyChartProps extends BaseChartProps {
     itemStyle?: Record<string, unknown>;
     lineStyle?: Record<string, unknown>;
   };
+  /** 自定义 ECharts option 合并 */
+  optionMerge?: Partial<EChartsOption>;
 }
 
 /**
@@ -739,48 +790,6 @@ export interface BoxplotChartProps extends Omit<BaseChartProps, 'data'> {
   smooth?: boolean;
 }
 
-/**
- * K线图/股票图属性
- * 用于展示股票、外汇等金融数据
- */
-export interface CandlestickChartProps extends Omit<BaseChartProps, 'data'> {
-  /** K线数据数组，每项为 [open, close, lowest, highest] */
-  candlestickData?: number[][];
-
-  /** X轴数据 */
-  xAxisData?: (string | number)[];
-
-  /** 数据对应的维度名 */
-  dimensions?: string[];
-
-  /** 批量数据 */
-  batchData?: Array<{
-    name: string;
-    data: number[][];
-  }>;
-
-  /** K线柱条样式 */
-  itemStyle?: Record<string, unknown>;
-
-  /** 强调状态 */
-  emphasis?: Record<string, unknown>;
-
-  /** 是否平滑曲线 */
-  smooth?: boolean;
-
-  /** 是否显示MA线 */
-  ma?: Array<{
-    period: number;
-    color?: string;
-  }>;
-
-  /** 是否显示成交量 */
-  showVolume?: boolean;
-
-  /** 成交量柱子样式 */
-  volumeBar?: Record<string, unknown>;
-}
-
 /**
  * 关系图属性
  * 用于展示节点之间的关系
@@ -839,6 +848,8 @@ export interface GraphChartProps extends BaseChartProps {
     itemStyle?: Record<string, unknown>;
     lineStyle?: Record<string, unknown>;
   };
+  /** 自定义 ECharts option 合并 */
+  optionMerge?: Partial<EChartsOption>;
 }
 
 // ============================================================================
@@ -880,9 +891,98 @@ export type { EChartsOption, ECharts } from 'echarts';
 export type { ECBasicOption as EChartsCoreOption } from 'echarts/types/dist/shared';
 
 /**
- * 词云图属性
- * 用于展示文本数据的词频分布
+ * 漏斗图标签配置
  */
+export interface FunnelLabel {
+  /** 是否显示标签 */
+  show?: boolean;
+  /** 标签位置 */
+  position?: 'inside' | 'outside' | 'left' | 'right';
+  /** 标签格式化 */
+  formatter?: string | ((_value: number, _name: string) => string);
+}
+
+/**
+ * 关系图节点数据
+ */
+export interface GraphNode {
+  /** 节点 ID */
+  id?: string | number;
+  /** 节点名称 */
+  name: string;
+  /** 节点值 */
+  value?: number | number[];
+  /** 节点类别 */
+  category?: number;
+  /** 节点符号 */
+  symbol?: string;
+  /** 节点符号大小 */
+  symbolSize?: number | number[];
+  /** 是否固定位置 */
+  fixed?: boolean;
+  /** X 坐标 */
+  x?: number;
+  /** Y 坐标 */
+  y?: number;
+  /** 其他自定义属性 */
+  [key: string]: unknown;
+}
+
+/**
+ * 关系图链接/边数据
+ */
+export interface GraphLink {
+  /** 源节点 */
+  source: string | number;
+  /** 目标节点 */
+  target: string | number;
+  /** 链接值 */
+  value?: number;
+  /** 线条样式 */
+  lineStyle?: Record<string, unknown>;
+  /** 其他自定义属性 */
+  [key: string]: unknown;
+}
+
+/**
+ * 桑基图节点数据
+ */
+export interface SankeyNode {
+  /** 节点名称 */
+  name: string;
+  /** 节点值 */
+  value?: number;
+  /** 其他自定义属性 */
+  [key: string]: unknown;
+}
+
+/**
+ * 桑基图链接/边数据
+ */
+export interface SankeyLink {
+  /** 源节点 */
+  source: string | number;
+  /** 目标节点 */
+  target: string | number;
+  /** 链接值 */
+  value: number;
+  /** 其他自定义属性 */
+  [key: string]: unknown;
+}
+
+/**
+ * 词云图数据项
+ */
+export interface WordCloudDataItem {
+  /** 词名 */
+  name: string;
+  /** 词频值 */
+  value: number;
+  /** 文本样式 */
+  textStyle?: Record<string, unknown>;
+  /** emphasis 状态 */
+  emphasis?: Record<string, unknown>;
+}
 export interface WordCloudChartProps extends BaseChartProps {
   /** 词云数据 - 也可以通过 option.series[0].data 传入 */
   wordCloudData?: Array<{
@@ -915,7 +1015,9 @@ export interface WordCloudChartProps extends BaseChartProps {
 
   /** 强调状态 */
   emphasis?: {
-    focus?: 'self' | 'adjacency';
-    textStyle?: Record<string, unknown>;
+    itemStyle?: Record<string, unknown>;
+    lineStyle?: Record<string, unknown>;
   };
+  /** 自定义 ECharts option 合并 */
+  optionMerge?: Partial<EChartsOption>;
 }

package/src/charts/utils.ts

@@ -12,13 +12,13 @@ export function processAdapterConfig(config: {
   theme?: string | object;
   autoResize?: boolean;
   canvasId?: string;
-  containerRef?: any;
-  option?: any;
+  containerRef?: unknown;
+  option?: unknown;
   renderer?: 'canvas' | 'svg';
-  [key: string]: any;
-}): any {
+  [key: string]: unknown;
+}): Record<string, unknown> {
   // 将复杂类型转换为简单类型
-  const processedConfig = {
+  const processedConfig: Record<string, unknown> = {
     width: typeof config.width === 'number' ? config.width : undefined,
     height: typeof config.height === 'number' ? config.height : undefined,
     theme: typeof config.theme === 'string' ? config.theme : undefined,
@@ -30,7 +30,7 @@ export function processAdapterConfig(config: {
   };
 
   // 复制其他可能存在的属性
-  const result: Record<string, any> = { ...processedConfig };
+  const result: Record<string, unknown> = { ...processedConfig };
   Object.keys(config).forEach((key) => {
     if (!(key in processedConfig)) {
       result[key] = config[key];
@@ -44,7 +44,9 @@ export function processAdapterConfig(config: {
  * 安全地调用适配器渲染方法
  * 解决 render 方法可能不存在的问题
  */
-export function safeRenderAdapter(adapter: any): JSX.Element | null {
+export function safeRenderAdapter(
+  adapter: { render?: () => JSX.Element | null } | null
+): JSX.Element | null {
   if (adapter && typeof adapter.render === 'function') {
     try {
       return adapter.render();

package/src/charts/wordcloud/__tests__/index.test.tsx

@@ -1,39 +1,106 @@
 /**
- * @version v1.5.0
+ * WordCloudChart 组件测试
  */
-
 import React from 'react';
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
 import WordCloudChart from '../index';
 
+// 使用正确的 mock 方式，参考 parallel 图表的测试
+jest.mock('../../common/BaseChartWrapper');
+jest.mock('echarts/charts', () => ({ WordCloudChart: jest.fn() }));
+
 describe('WordCloudChart', () => {
-  it('renders without crashing', () => {
-    const { container } = render(<WordCloudChart />);
-    expect(container).toBeTruthy();
-  });
-
-  it('renders with custom width and height', () => {
-    const { container } = render(<WordCloudChart width={600} height={400} />);
-    // BaseChartWrapper renders a fragment with a hidden accessibility table (first child)
-    // and the actual chart div (last child), so we query the last child for styles
-    const chartDiv = container.lastChild;
-    expect(chartDiv).toHaveStyle({ width: '600px', height: '400px' });
-  });
-
-  it('renders with word data', () => {
-    const option = {
-      series: [
-        {
-          type: 'wordCloud' as const,
-          data: [
-            { name: 'JavaScript', value: 10000 },
-            { name: 'TypeScript', value: 8000 },
-            { name: 'React', value: 6000 },
-          ],
-        },
-      ],
-    } as any;
-    const { container } = render(<WordCloudChart option={option} />);
-    expect(container).toBeTruthy();
+  const mockData = [
+    { name: 'JavaScript', value: 100 },
+    { name: 'TypeScript', value: 80 },
+    { name: 'React', value: 60 },
+    { name: 'Vue', value: 50 },
+    { name: 'Node.js', value: 40 },
+    { name: 'Python', value: 30 },
+    { name: 'Go', value: 20 },
+  ];
+
+  it('应该渲染词云图组件', () => {
+    render(<WordCloudChart wordCloudData={mockData} width={800} height={400} />);
+
+    expect(screen.getByTestId('base-chart-wrapper')).toBeInTheDocument();
+  });
+
+  it('应该传递正确的 option 到 BaseChart', () => {
+    render(<WordCloudChart wordCloudData={mockData} width={800} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series).toBeDefined();
+    expect(option.series.type).toBe('wordCloud');
+    expect(option.series.data).toEqual(mockData);
+    expect(option.series.shape).toBe('circle');
+  });
+
+  it('当 wordCloudData 为空时应该返回 null', () => {
+    const { container } = render(<WordCloudChart wordCloudData={[]} width={800} height={400} />);
+
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('应该支持自定义 shape', () => {
+    render(<WordCloudChart wordCloudData={mockData} shape="star" width={800} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.shape).toBe('star');
+  });
+
+  it('应该支持自定义 sizeRange', () => {
+    render(
+      <WordCloudChart wordCloudData={mockData} sizeRange={[15, 80]} width={800} height={400} />
+    );
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.sizeRange).toEqual([15, 80]);
+  });
+
+  it('应该支持自定义 rotationRange', () => {
+    render(
+      <WordCloudChart wordCloudData={mockData} rotationRange={[-45, 45]} width={800} height={400} />
+    );
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.rotationRange).toEqual([-45, 45]);
+  });
+
+  it('应该支持自定义 gridSize', () => {
+    render(<WordCloudChart wordCloudData={mockData} gridSize={10} width={800} height={400} />);
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.series.gridSize).toBe(10);
+  });
+
+  it('应该支持 optionMerge 自定义配置', () => {
+    const customTitle = { title: { text: '词云图标题', left: 'center' } };
+
+    render(
+      <WordCloudChart wordCloudData={mockData} optionMerge={customTitle} width={800} height={400} />
+    );
+
+    const baseChartWrapper = screen.getByTestId('base-chart-wrapper');
+    const optionElement = baseChartWrapper.querySelector('[data-testid="chart-option"]');
+    const option = JSON.parse(optionElement?.textContent || '{}');
+
+    expect(option.title).toEqual(customTitle.title);
   });
 });

package/src/charts/wordcloud/index.tsx

@@ -1,13 +1,79 @@
 /**
- * WordCloudChart组件
+ * TaroViz 词云图组件
+ *
+ * 基于 ECharts wordCloud 系列实现词云可视化
  */
-import React, { memo } from 'react';
-import BaseChartWrapper from '../common/BaseChartWrapper';
-import { WordCloudChartProps } from '../types';
-
-const WordCloudChart: React.FC<WordCloudChartProps> = memo((props) => (
-  <BaseChartWrapper {...props} chartType="wordcloud-chart" />
-));
-WordCloudChart.displayName = 'WordCloudChart';
+import { createOptionChartComponent } from '@/charts/createOptionChartComponent';
+import type { WordCloudChartProps } from './types';
+// 类型 WordCloudDataItem 通过下方 export type 导出供外部使用
+
+/**
+ * 构建词云图 ECharts option
+ */
+function buildWordCloudOption(props: WordCloudChartProps) {
+  const {
+    wordCloudData,
+    shape,
+    sizeRange,
+    rotationRange,
+    rotationStep,
+    gridSize,
+    drawOutOfBound,
+    textStyle,
+    optionMerge,
+  } = props;
+
+  // 验证数据
+  if (!wordCloudData || wordCloudData.length === 0) {
+    console.warn('[TaroViz] WordCloudChart: wordCloudData is required');
+    return null;
+  }
+
+  // 构建词云图 series
+  const series = {
+    type: 'wordCloud' as const,
+    shape: shape || 'circle',
+    data: wordCloudData,
+    sizeRange: sizeRange || [12, 60],
+    rotationRange: rotationRange || [-90, 90],
+    rotationStep: rotationStep || 45,
+    gridSize: gridSize || 8,
+    drawOutOfBound: drawOutOfBound !== false,
+    textStyle: {
+      fontFamily: 'sans-serif',
+      fontWeight: 'bold',
+      ...textStyle,
+    },
+    emphasis: {
+      itemStyle: {
+        shadowBlur: 10,
+        shadowColor: 'rgba(0, 0, 0, 0.5)',
+      },
+    },
+  };
+
+  const option: any = {
+    tooltip: {
+      trigger: 'item',
+      formatter: (params: any) => {
+        if (!params || !params.data) return '';
+        return `<b>${params.data.name}</b><br/>词频: ${params.data.value}`;
+      },
+    },
+    series,
+  };
+
+  // 合并自定义配置
+  if (optionMerge) {
+    Object.assign(option, optionMerge);
+  }
+
+  return option;
+}
+
+const WordCloudChart = createOptionChartComponent<WordCloudChartProps>(
+  'WordCloudChart',
+  buildWordCloudOption
+);
 
 export default WordCloudChart;

package/src/charts/wordcloud/types.ts

@@ -0,0 +1,6 @@
+/**
+ * TaroViz 词云图类型定义
+ *
+ * 从主 types 文件导入基础类型，只导出组件特有的类型
+ */
+export type { WordCloudChartProps, WordCloudDataItem } from '../types';