@agions/taroviz 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agions/taroviz",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "基于 Taro 和 ECharts 的多端图表组件库",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -139,6 +139,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.28.4",
+    "echarts-liquidfill": "^3.1.0",
     "tslib": "^2.8.1"
   },
   "peerDependencies": {

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

@@ -0,0 +1,130 @@
+/**
+ * @jest-environment jsdom
+ */
+import React from 'react';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import BoxplotChart from '../index';
+
+// Mock ECharts and adapters
+jest.mock('echarts/core', () => ({
+  use: jest.fn(),
+  init: jest.fn(() => ({
+    setOption: jest.fn(),
+    showLoading: jest.fn(),
+    hideLoading: jest.fn(),
+    on: jest.fn(),
+    off: jest.fn(),
+    dispose: jest.fn(),
+    resize: jest.fn(),
+  })),
+  getInstanceByDom: jest.fn(),
+}));
+
+// Mock ECharts components
+jest.mock('echarts/components', () => ({
+  GridComponent: jest.fn(),
+  TooltipComponent: jest.fn(),
+  TitleComponent: jest.fn(),
+  LegendComponent: jest.fn(),
+}));
+
+// Mock BaseChartWrapper
+jest.mock('../../common/BaseChartWrapper', () => ({
+  __esModule: true,
+  default: (props: any) => (
+    <div
+      data-testid="boxplot-chart"
+      className={`taroviz-boxplot ${props.className || ''}`}
+      style={{ width: props.width || '100%', height: props.height || 300, ...props.style }}
+    >
+      <div data-testid="chart-option">{JSON.stringify(props.option)}</div>
+    </div>
+  ),
+}));
+
+describe('BoxplotChart', () => {
+  const basicOption = {
+    title: { text: '箱线图测试' },
+    xAxis: { type: 'category' as const, data: ['A', 'B', 'C'] },
+    yAxis: { type: 'value' as const },
+    series: [{
+      type: 'boxplot' as const,
+      data: [
+        [850, 940, 980, 1050, 1130],
+        [920, 1000, 1050, 1150, 1200],
+        [780, 850, 920, 1050, 1150],
+      ],
+    }],
+  };
+
+  describe('Basic Rendering', () => {
+    it('should render without crashing', () => {
+      const { getByTestId } = render(<BoxplotChart option={basicOption} />);
+      expect(getByTestId('boxplot-chart')).toBeInTheDocument();
+    });
+
+    it('should render with custom width and height', () => {
+      const { getByTestId } = render(<BoxplotChart option={basicOption} width={600} height={500} />);
+      expect(getByTestId('boxplot-chart')).toBeInTheDocument();
+    });
+
+    it('should have correct display name', () => {
+      expect(BoxplotChart.displayName).toBe('BoxplotChart');
+    });
+
+    it('should pass option to wrapper', () => {
+      const { getByTestId } = render(<BoxplotChart option={basicOption} />);
+      expect(getByTestId('chart-option')).toHaveTextContent('箱线图测试');
+    });
+  });
+
+  describe('Props', () => {
+    it('should accept className prop', () => {
+      const { getByTestId } = render(<BoxplotChart option={basicOption} className="test-class" />);
+      expect(getByTestId('boxplot-chart')).toHaveClass('test-class');
+    });
+
+    it('should accept style prop', () => {
+      const { getByTestId } = render(<BoxplotChart option={basicOption} style={{ padding: '10px' }} />);
+      expect(getByTestId('boxplot-chart')).toBeInTheDocument();
+    });
+
+    it('should accept loading prop', () => {
+      const { getByTestId } = render(<BoxplotChart option={basicOption} loading={true} />);
+      expect(getByTestId('boxplot-chart')).toBeInTheDocument();
+    });
+
+    it('should accept theme prop', () => {
+      const { getByTestId } = render(<BoxplotChart option={basicOption} theme="dark" />);
+      expect(getByTestId('boxplot-chart')).toBeInTheDocument();
+    });
+  });
+
+  describe('Chart Options', () => {
+    it('should render with multiple data series', () => {
+      const multiOption = {
+        ...basicOption,
+        series: [
+          { type: 'boxplot' as const, name: '2024', data: [[850, 940, 980, 1050, 1130]] },
+          { type: 'boxplot' as const, name: '2025', data: [[920, 1000, 1050, 1150, 1200]] },
+        ],
+      };
+      const { getByTestId } = render(<BoxplotChart option={multiOption} />);
+      expect(getByTestId('boxplot-chart')).toBeInTheDocument();
+    });
+
+    it('should render with custom itemStyle', () => {
+      const optionWithStyle = {
+        ...basicOption,
+        series: [{
+          type: 'boxplot' as const,
+          data: [[850, 940, 980, 1050, 1130]],
+          itemStyle: { color: '#1890ff', borderColor: '#000' },
+        }],
+      };
+      const { getByTestId } = render(<BoxplotChart option={optionWithStyle} />);
+      expect(getByTestId('boxplot-chart')).toBeInTheDocument();
+    });
+  });
+});

package/src/charts/boxplot/index.tsx

@@ -0,0 +1,18 @@
+/**
+ * 箱线图组件
+ * 用于展示数据的分布情况，包括最小值、Q1、中位数、Q3、最大值
+ */
+import React, { memo } from 'react';
+import BaseChartWrapper from '../common/BaseChartWrapper';
+import { BoxplotChartProps } from './types';
+
+const BoxplotChart: React.FC<BoxplotChartProps> = memo((props) => (
+  <BaseChartWrapper {...props} chartType="boxplot" />
+));
+
+BoxplotChart.displayName = 'BoxplotChart';
+
+export default BoxplotChart;
+
+// 导出类型
+export type { BoxplotChartProps, BoxplotOption, BoxplotSeriesItem } from './types';

package/src/charts/boxplot/types.ts

@@ -0,0 +1,46 @@
+/**
+ * 箱线图类型定义
+ */
+
+export type BoxplotChartProps = {
+  option?: BoxplotOption;
+  width?: string | number;
+  height?: string | number;
+  className?: string;
+  style?: React.CSSProperties;
+  onEvents?: Record<string, (params: any) => void>;
+  loading?: boolean;
+  loadingOption?: any;
+  theme?: string;
+  onChartReady?: (chart: any) => void;
+  opts?: {
+    devicePixelRatio?: number;
+    renderer?: 'canvas' | 'svg';
+    useDirtyRect?: boolean;
+  };
+};
+
+export interface BoxplotOption {
+  title?: any;
+  legend?: any;
+  grid?: any;
+  xAxis?: any;
+  yAxis?: any;
+  tooltip?: any;
+  series: BoxplotSeriesItem[];
+  dataset?: any;
+  color?: string[];
+  backgroundColor?: any;
+  textStyle?: any;
+  [key: string]: any;
+}
+
+export interface BoxplotSeriesItem {
+  type: 'boxplot';
+  name?: string;
+  data?: any[];
+  itemStyle?: any;
+  emphasis?: any;
+  dimensions?: string[];
+  encode?: any;
+}

package/src/charts/index.ts

@@ -22,10 +22,18 @@ export { default as GraphChart } from './graph';
 export { default as CandlestickChart } from './candlestick';
 export { default as WordCloudChart } from './wordcloud';
 
+// 导出 v1.6.0 新增图表组件
+export { default as BoxplotChart } from './boxplot';
+export { default as ParallelChart } from './parallel';
+
+// 导出 v1.7.0 新增图表组件
+export { default as LiquidChart } from './liquid';
+export { default as TreeChart } from './tree';
+
 // 导出类型定义
 export * from './types';
 
 /**
  * 版本信息
  */
-export const version = '1.4.0';
+export const version = '1.7.0';

package/src/charts/liquid/index.tsx

@@ -0,0 +1,226 @@
+/**
+ * 水球图组件
+ * ECharts 没有内置水球图，使用 echarts-liquidfill 库实现
+ */
+import React, { memo, useEffect, useRef, useMemo } from 'react';
+import { getAdapter } from '../../adapters';
+import { uuid } from '../../core/utils';
+import { processAdapterConfig } from '../utils';
+import { LiquidChartProps } from './types';
+
+/**
+ * 水球图组件
+ * 使用 echarts-liquidfill 实现
+ */
+const LiquidChart: React.FC<LiquidChartProps> = memo((props) => {
+  const {
+    option,
+    width = '100%',
+    height = '300px',
+    theme,
+    style = {},
+    className = '',
+    autoResize = true,
+    loading = false,
+    loadingOption,
+    onChartInit,
+    onChartReady,
+    renderer = 'canvas',
+    onEvents = {},
+    waveData = [0.6],
+    shape = 'circle',
+    amplitude,
+    waveLength,
+    phase,
+    period,
+    backgroundColor = 'transparent',
+    color,
+    showLabel = true,
+    labelFormatter,
+  } = props;
+
+  const chartId = useRef<string>(`liquid-${uuid()}`);
+  const chartInstance = useRef<any>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const extensionRegistered = useRef<boolean>(false);
+
+  // 构建水球图配置
+  const liquidOption = useMemo(() => {
+    const baseOption = option || {};
+
+    // 如果用户提供了 option，直接返回
+    if (baseOption.series && baseOption.series.length > 0) {
+      return baseOption;
+    }
+
+    // 构建水球图 series
+    const seriesData = waveData.map((value) => {
+      const dataItem: Record<string, unknown> = { value };
+
+      if (showLabel && labelFormatter) {
+        dataItem.label = {
+          formatter: labelFormatter(value),
+        };
+      }
+
+      return dataItem;
+    });
+
+    const seriesConfig: Record<string, unknown> = {
+      type: 'liquidFill',
+      data: waveData,
+      shape,
+      backgroundColor,
+      color: color || ['#4cabce', '#4cabce'],
+      label: showLabel
+        ? {
+            show: true,
+            formatter: labelFormatter
+              ? (params: any) => labelFormatter(params.value)
+              : '{d}%',
+            textStyle: {
+              fontSize: 20,
+              fontWeight: 'bold',
+            },
+          }
+        : { show: false },
+    };
+
+    // 添加可选参数
+    if (amplitude !== undefined) {
+      seriesConfig.amplitude = amplitude;
+    }
+    if (waveLength !== undefined) {
+      seriesConfig.waveLength = waveLength;
+    }
+    if (phase !== undefined) {
+      seriesConfig.phase = phase;
+    }
+    if (period !== undefined) {
+      seriesConfig.period = period;
+    }
+
+    return {
+      ...baseOption,
+      series: [seriesConfig],
+    };
+  }, [option, waveData, shape, backgroundColor, color, showLabel, labelFormatter, amplitude, waveLength, phase, period]);
+
+  // 处理图表初始化
+  useEffect(() => {
+    let mounted = true;
+
+    const initChart = async (): Promise<(() => void) | undefined> => {
+      // 动态导入 echarts-liquidfill 并注册扩展
+      if (!extensionRegistered.current) {
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-require-imports
+          const liquidfill = require('echarts-liquidfill');
+          if (liquidfill && mounted) {
+            liquidfill.register && liquidfill.register();
+            extensionRegistered.current = true;
+          }
+        } catch (e) {
+          console.warn('[TaroViz] LiquidChart: Failed to load echarts-liquidfill extension', e);
+          return undefined;
+        }
+      }
+
+      if (!mounted || !containerRef.current) return undefined;
+
+      const initConfig = processAdapterConfig({
+        canvasId: chartId.current,
+        containerRef,
+        width,
+        height,
+        theme,
+        autoResize,
+        renderer,
+        option: liquidOption,
+        onInit: (instance: any) => {
+          chartInstance.current = instance;
+
+          // 绑定事件
+          if (onEvents) {
+            Object.keys(onEvents).forEach((eventName) => {
+              instance.on(eventName, (onEvents as any)[eventName]);
+            });
+          }
+
+          if (onChartInit) {
+            onChartInit(instance);
+          }
+
+          if (onChartReady) {
+            onChartReady(instance);
+          }
+        },
+      });
+
+      const adapter = await getAdapter(initConfig);
+      adapter.init();
+
+      return () => {
+        if (chartInstance.current) {
+          if (onEvents) {
+            Object.keys(onEvents).forEach((eventName) => {
+              chartInstance.current?.off(eventName);
+            });
+          }
+          chartInstance.current.dispose();
+          chartInstance.current = null;
+        }
+      };
+    };
+
+    let cleanupFn: (() => void) | undefined;
+    initChart().then((cleanup) => {
+      cleanupFn = cleanup;
+    });
+
+    return () => {
+      mounted = false;
+      cleanupFn?.();
+    };
+  }, [liquidOption, width, height, theme, autoResize, renderer, onChartInit, onChartReady, onEvents]);
+
+  // 更新配置
+  useEffect(() => {
+    if (chartInstance.current && liquidOption) {
+      chartInstance.current.setOption(liquidOption, true);
+    }
+  }, [liquidOption]);
+
+  // 控制加载状态
+  useEffect(() => {
+    if (chartInstance.current) {
+      if (loading) {
+        chartInstance.current.showLoading(loadingOption);
+      } else {
+        chartInstance.current.hideLoading();
+      }
+    }
+  }, [loading, loadingOption]);
+
+  // 自定义样式
+  const mergedStyle = {
+    width: typeof width === 'number' ? `${width}px` : width,
+    height: typeof height === 'number' ? `${height}px` : height,
+    ...style,
+  };
+
+  return (
+    <div
+      className={`taroviz-liquid ${className}`}
+      style={mergedStyle}
+      ref={containerRef as React.RefObject<HTMLDivElement>}
+    />
+  );
+});
+
+LiquidChart.displayName = 'LiquidChart';
+
+export default LiquidChart;
+
+// 导出类型
+export type { LiquidChartProps, LiquidOption, LiquidShape, LiquidSeries, LiquidSeriesDataItem } from './types';

package/src/charts/liquid/types.ts

@@ -0,0 +1,130 @@
+/**
+ * 水球图类型定义
+ * ECharts 没有内置水球图，使用 echarts-liquidfill 库实现
+ */
+import type React from 'react';
+import type { EChartsOption } from 'echarts';
+
+// ============================================================================
+// 水球图配置类型
+// ============================================================================
+
+/** 水球图系列数据项 */
+export interface LiquidSeriesDataItem {
+  /** 数据值，范围 [0, 1] */
+  value: number;
+  /** 数据项名称 */
+  name?: string;
+  /** 图形样式 */
+  itemStyle?: Record<string, unknown>;
+  /** 标签配置 */
+  label?: Record<string, unknown>;
+  /** 强调状态 */
+  emphasis?: Record<string, unknown>;
+}
+
+/** 水球图形状类型 */
+export type LiquidShape = 'circle' | 'rect' | 'roundRect';
+
+/** 水球图系列配置 */
+export interface LiquidSeries {
+  /** 系列类型 */
+  type?: 'liquidFill';
+  /** 系列名称 */
+  name?: string;
+  /** 数据数组 */
+  data?: (number | LiquidSeriesDataItem)[];
+  /** 图形形状 */
+  shape?: LiquidShape;
+  /** 振幅 (相对于半径的比例) */
+  amplitude?: number;
+  /** 波长 (相对于画布宽度) */
+  waveLength?: number | string;
+  /** 相位偏移 */
+  phase?: number;
+  /** 周期时间 (ms) */
+  period?: number;
+  /** 波的个数 */
+  waveCount?: number;
+  /** 是否禁用动画 */
+  animationDisabled?: boolean;
+  /** 动画时长 */
+  animationDuration?: number;
+  /** 动画缓动函数 */
+  animationEasing?: string;
+  /** 动画延迟 */
+  animationDelay?: number | ((idx: number) => number);
+  /** 颜色数组 */
+  color?: string[];
+  /** 背景色 */
+  backgroundColor?: string;
+  /** 图形内标签 */
+  label?: Record<string, unknown>;
+  /** 图形样式 */
+  itemStyle?: Record<string, unknown>;
+  /** emphasis状态 */
+  emphasis?: Record<string, unknown>;
+  /** 浪的样式 */
+  waveStyle?: Record<string, unknown>;
+}
+
+/** 水球图选项配置 */
+export interface LiquidOption extends Omit<EChartsOption, 'series'> {
+  series?: LiquidSeries[];
+}
+
+// ============================================================================
+// 组件 Props
+// ============================================================================
+
+/**
+ * 水球图组件属性
+ */
+export interface LiquidChartProps {
+  /** 图表配置项 (EChartsOption) */
+  option?: LiquidOption;
+  /** 宽度 */
+  width?: string | number;
+  /** 高度 */
+  height?: string | number;
+  /** 水球数据数组，每个值代表一个波纹，范围 [0, 1] */
+  waveData?: number[];
+  /** 图形形状 */
+  shape?: LiquidShape;
+  /** 振幅 (相对于半径的比例) */
+  amplitude?: number;
+  /** 波长 (相对于画布宽度) */
+  waveLength?: number | string;
+  /** 相位偏移 */
+  phase?: number;
+  /** 周期时间 (ms) */
+  period?: number;
+  /** 背景色 */
+  backgroundColor?: string;
+  /** 颜色数组 */
+  color?: string[];
+  /** 是否显示标签 */
+  showLabel?: boolean;
+  /** 标签格式化 */
+  labelFormatter?: (value: number) => string;
+  /** 主题 */
+  theme?: string | Record<string, unknown>;
+  /** 样式 */
+  style?: React.CSSProperties;
+  /** 类名 */
+  className?: string;
+  /** 是否自动调整大小 */
+  autoResize?: boolean;
+  /** 渲染器类型 */
+  renderer?: 'canvas' | 'svg';
+  /** 加载状态 */
+  loading?: boolean;
+  /** 加载配置 */
+  loadingOption?: Record<string, unknown>;
+  /** 图表初始化回调 */
+  onChartInit?: (chart: any) => void;
+  /** 图表就绪回调 */
+  onChartReady?: (chart: any) => void;
+  /** 事件回调 */
+  onEvents?: Record<string, (params: any) => void>;
+}