@agions/taroviz 1.7.0 → 1.9.0

package/src/core/animation/AnimationManager.ts

@@ -13,21 +13,33 @@ import {
 } from './types';
 
 /**
- * 动画预设集合
+ * Checks the OS/browser prefers-reduced-motion setting.
+ * Returns true if the user has requested reduced motion.
+ */
+function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Professional animation presets following frontend-design-pro skill guidelines:
+ * - Easing: cubic-bezier(0.16, 1, 0.3, 1) ("cubicOut") for natural deceleration
+ * - Durations: 100-200ms micro, 300-500ms transitions, never >600ms
+ * - NO bounce/elastic — anti-patterns that feel廉价 (cheap)
  */
 const DEFAULT_ANIMATION_PRESETS: AnimationPreset[] = [
   {
     name: 'default',
-    description: '默认动画配置',
+    description: '默认动画配置 — 专业级 (300-500ms, cubicOut)',
     config: {
       enabled: true,
-      duration: 1000,
+      duration: 400,
       easing: 'cubicOut',
-      appearDuration: 1200,
+      appearDuration: 450,
       appearEasing: 'cubicOut',
-      updateDuration: 800,
+      updateDuration: 300,
       updateEasing: 'cubicOut',
-      disappearDuration: 600,
+      disappearDuration: 250,
       disappearEasing: 'cubicIn',
       threshold: 1000,
       progressive: true,
@@ -36,17 +48,17 @@ const DEFAULT_ANIMATION_PRESETS: AnimationPreset[] = [
   },
   {
     name: 'fast',
-    description: '快速动画配置',
+    description: '快速动画配置 — 微交互 (150-200ms)',
     config: {
       enabled: true,
-      duration: 500,
-      easing: 'linear',
-      appearDuration: 600,
-      appearEasing: 'linear',
-      updateDuration: 400,
-      updateEasing: 'linear',
-      disappearDuration: 300,
-      disappearEasing: 'linear',
+      duration: 150,
+      easing: 'cubicOut',
+      appearDuration: 200,
+      appearEasing: 'cubicOut',
+      updateDuration: 150,
+      updateEasing: 'cubicOut',
+      disappearDuration: 100,
+      disappearEasing: 'cubicIn',
       threshold: 2000,
       progressive: true,
       progressiveStep: 1000,
@@ -54,55 +66,57 @@ const DEFAULT_ANIMATION_PRESETS: AnimationPreset[] = [
   },
   {
     name: 'slow',
-    description: '慢速动画配置',
+    description: '慢速动画配置 — 页面过渡 (500-600ms, capped)',
     config: {
       enabled: true,
-      duration: 2000,
+      duration: 500,
       easing: 'cubicInOut',
-      appearDuration: 2400,
+      appearDuration: 600,
       appearEasing: 'cubicInOut',
-      updateDuration: 1600,
+      updateDuration: 400,
       updateEasing: 'cubicInOut',
-      disappearDuration: 1200,
+      disappearDuration: 300,
       disappearEasing: 'cubicInOut',
       threshold: 500,
       progressive: true,
       progressiveStep: 250,
     },
   },
+  // DEPRECATED — bounce is an anti-pattern per frontend-design-pro skill
   {
     name: 'bounce',
-    description: '弹跳动画配置',
+    description: '[已废弃] 弹跳动画 — 请使用 default 或 fast',
     config: {
-      enabled: true,
-      duration: 1500,
-      easing: 'bounceOut',
-      appearDuration: 1800,
-      appearEasing: 'bounceOut',
-      updateDuration: 1200,
-      updateEasing: 'bounceOut',
-      disappearDuration: 900,
-      disappearEasing: 'bounceIn',
+      enabled: false, // disabled by default — anti-pattern
+      duration: 0,
+      easing: 'cubicOut',
+      appearDuration: 0,
+      appearEasing: 'cubicOut',
+      updateDuration: 0,
+      updateEasing: 'cubicOut',
+      disappearDuration: 0,
+      disappearEasing: 'cubicIn',
       threshold: 500,
-      progressive: true,
+      progressive: false,
       progressiveStep: 250,
     },
   },
+  // DEPRECATED — elastic is an anti-pattern per frontend-design-pro skill
   {
     name: 'elastic',
-    description: '弹性动画配置',
+    description: '[已废弃] 弹性动画 — 请使用 default 或 fast',
     config: {
-      enabled: true,
-      duration: 1500,
-      easing: 'elasticOut',
-      appearDuration: 1800,
-      appearEasing: 'elasticOut',
-      updateDuration: 1200,
-      updateEasing: 'elasticOut',
-      disappearDuration: 900,
-      disappearEasing: 'elasticIn',
+      enabled: false, // disabled by default — anti-pattern
+      duration: 0,
+      easing: 'cubicOut',
+      appearDuration: 0,
+      appearEasing: 'cubicOut',
+      updateDuration: 0,
+      updateEasing: 'cubicOut',
+      disappearDuration: 0,
+      disappearEasing: 'cubicIn',
       threshold: 500,
-      progressive: true,
+      progressive: false,
       progressiveStep: 250,
     },
   },
@@ -213,6 +227,7 @@ export class AnimationManager {
 
   /**
    * 根据数据量和动画类型获取优化后的动画配置
+   * 尊重 prefers-reduced-motion 无障碍设置
    */
   public getOptimizedConfig(
     config: Partial<AnimationConfig> = {},
@@ -224,6 +239,18 @@ export class AnimationManager {
       ...config,
     };
 
+    // Respect OS/browser prefers-reduced-motion setting (WCAG)
+    if (prefersReducedMotion()) {
+      return {
+        ...mergedConfig,
+        enabled: false,
+        duration: 0,
+        appearDuration: 0,
+        updateDuration: 0,
+        disappearDuration: 0,
+      };
+    }
+
     // 根据数据量优化动画
     if (mergedConfig.threshold && dataLength > mergedConfig.threshold) {
       mergedConfig.enabled = false;

package/src/core/components/BaseChart.tsx

@@ -9,6 +9,7 @@ import React, { useEffect, useRef, useMemo, useCallback } from 'react';
 
 import { generateEChartsAnimationConfig } from '../animation';
 import { EChartsOption, EChartsType, AnimationConfig } from '../types';
+import type { DataZoomComponentOption } from 'echarts';
 import { registerChart, removeChart, getChart } from '../utils/chartInstances';
 import { DebugPanel, DebugPanelOptions, updateDebugInfo } from '../utils/debug';
 import { PerformanceAnalyzer } from '../utils/performance';
@@ -21,8 +22,27 @@ import type { BaseChartProps } from '../../charts/types';
 // ============================================================================
 
 /** 图表事件参数类型 */
-export interface ChartEventParams {
-  [key: string]: any;
+export interface ChartEventParams extends Record<string, unknown> {
+  componentType?: string;
+  componentSubType?: string;
+  componentIndex?: number;
+  seriesType?: string;
+  seriesIndex?: number;
+  seriesId?: string;
+  seriesName?: string;
+  name?: string;
+  dataIndex?: number;
+  data?: unknown;
+  dataType?: string;
+  value?: unknown;
+  color?: string;
+  borderColor?: string;
+  dimensionNames?: string[];
+  encode?: Record<string, number[]>;
+  marker?: string;
+  status?: string;
+  dimensionIndex?: number;
+  percent?: number;
 }
 
 /** 图表导出选项 */
@@ -146,7 +166,7 @@ const BaseChart: React.FC<ChartProps> = (props) => {
   } = props;
 
   // Refs
-  const chartInstanceRef = useRef<any>(null);
+  const chartInstanceRef = useRef<EChartsType | null>(null);
   const performanceRef = useRef({
     initStartTime: 0,
     initEndTime: 0,
@@ -162,7 +182,7 @@ const BaseChart: React.FC<ChartProps> = (props) => {
     isScrolling: false,
   });
   const oldOptionRef = useRef<EChartsOption | undefined>(option);
-  const adapterRef = useRef<any>(null);
+  const adapterRef = useRef<unknown>(null);
   const debugConfigRef = useRef<DebugPanelOptions | null>(null);
   const performanceAnalyzerRef = useRef<PerformanceAnalyzer | null>(null);
 
@@ -206,6 +226,22 @@ const BaseChart: React.FC<ChartProps> = (props) => {
       }
     }
 
+    // Inject dataZoom when enableZoom is true (keyboard-accessible zoom)
+    if (_enableZoom) {
+      processed = JSON.parse(JSON.stringify(processed));
+      // Avoid duplicate dataZoom entries
+      const existingDzArr = Array.isArray(processed.dataZoom)
+        ? processed.dataZoom as DataZoomComponentOption[]
+        : processed.dataZoom ? [processed.dataZoom as DataZoomComponentOption] : [];
+      if (!existingDzArr.some((dz) => dz?.type === 'inside')) {
+        processed.dataZoom = [
+          ...(existingDzArr || []),
+          // Inside (mouse wheel + keyboard) — wired to keyboard nav in BaseChartWrapper
+          { type: 'inside', start: 0, end: 100, zoomOnMouseWheel: true, moveOnMouseMove: false },
+        ];
+      }
+    }
+
     // Apply animation config
     const dataLength = calculateDataLength(processed);
     const animConfig = generateEChartsAnimationConfig(animation, dataLength);
@@ -213,6 +249,7 @@ const BaseChart: React.FC<ChartProps> = (props) => {
   }, [
     option,
     animation,
+    _enableZoom,
     enableDataFiltering,
     filters,
     virtualScroll,
@@ -223,13 +260,14 @@ const BaseChart: React.FC<ChartProps> = (props) => {
 
   // Internal chartInit that wraps the user's callback
   const handleChartInit = useCallback(
-    (instance: any) => {
+    (instance: EChartsType) => {
       chartInstanceRef.current = instance;
-      adapterRef.current = instance;
+      adapterRef.current = instance as unknown;
 
       // Performance monitoring init
       if (enablePerformanceMonitoring) {
         performanceAnalyzerRef.current = PerformanceAnalyzer.getInstance({
+          chartId,
           enabled: true,
           metrics: ['initTime', 'renderTime', 'updateTime', 'dataSize', 'frameRate'],
           sampleInterval: 1000,
@@ -394,15 +432,40 @@ const BaseChart: React.FC<ChartProps> = (props) => {
     }
   }, [option, onPerformance]);
 
-  // Data update callback
+  // Data update callback — supports debounce
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
   useEffect(() => {
-    if (onDataUpdate && dataUpdateOptions?.enabled !== false) {
+    if (!onDataUpdate || dataUpdateOptions?.enabled === false) return;
+
+    const delay = dataUpdateOptions?.debounceDelay ?? 0;
+
+    if (debounceTimerRef.current) {
+      clearTimeout(debounceTimerRef.current);
+    }
+
+    if (delay > 0) {
+      debounceTimerRef.current = setTimeout(() => {
+        const oldOpt = oldOptionRef.current;
+        if (oldOpt !== option) {
+          onDataUpdate(oldOpt, option);
+          oldOptionRef.current = option;
+        }
+      }, delay);
+    } else {
       const oldOpt = oldOptionRef.current;
       if (oldOpt !== option) {
         onDataUpdate(oldOpt, option);
         oldOptionRef.current = option;
       }
     }
+
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+        debounceTimerRef.current = null;
+      }
+    };
   }, [option, onDataUpdate, dataUpdateOptions]);
 
   // Cleanup on unmount
@@ -413,7 +476,7 @@ const BaseChart: React.FC<ChartProps> = (props) => {
         performanceAnalyzerRef.current.dispose();
         performanceAnalyzerRef.current = null;
       }
-      if (adapterRef.current) adapterRef.current.dispose();
+      if (adapterRef.current) (adapterRef.current as EChartsType).dispose();
     };
   }, [chartId]);
 

package/src/core/types/common.ts

@@ -1,12 +1,31 @@
 /**
  * ECharts 类型定义
  */
-export type EChartsOption = any;
+export type { EChartsOption } from 'echarts';
+
+/**
+ * 图表事件参数类型
+ * 使用 ECharts 内的事件参数接口
+ */
+export interface ChartEventParams {
+  componentType?: string;
+  seriesType?: string;
+  seriesIndex?: number;
+  seriesName?: string;
+  name?: string;
+  dataIndex?: number;
+  data?: unknown;
+  value?: unknown;
+  color?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  target?: unknown;
+}
 
 /**
  * 图表事件监听器
  */
-export type ChartEventListener = Record<string, (params: any) => void>;
+export type ChartEventListener = Record<string, (params: ChartEventParams) => void>;
 
 /**
  * 图表渲染器类型
@@ -17,24 +36,9 @@ export type ChartRenderer = 'canvas' | 'svg';
  * DataURL选项
  */
 export interface DataURLOption {
-  /**
-   * 导出的图片类型
-   */
   type?: 'png' | 'jpeg';
-
-  /**
-   * 设备像素比
-   */
   pixelRatio?: number;
-
-  /**
-   * 背景色
-   */
   backgroundColor?: string;
-
-  /**
-   * 排除的组件列表
-   */
   excludeComponents?: string[];
 }
 
@@ -42,14 +46,7 @@ export interface DataURLOption {
  * 图表尺寸类型
  */
 export interface ChartSize {
-  /**
-   * 宽度
-   */
   width?: number | string;
-
-  /**
-   * 高度
-   */
   height?: number | string;
 }
 
@@ -57,29 +54,10 @@ export interface ChartSize {
  * 图表动画设置
  */
 export interface ChartAnimation {
-  /**
-   * 是否启用动画
-   */
   enabled?: boolean;
-
-  /**
-   * 动画时长
-   */
   duration?: number;
-
-  /**
-   * 动画缓动效果
-   */
   easing?: string;
-
-  /**
-   * 初始动画时长
-   */
   animationDuration?: number;
-
-  /**
-   * 更新动画时长
-   */
   animationDurationUpdate?: number;
 }
 
@@ -87,29 +65,10 @@ export interface ChartAnimation {
  * 图表主题设置
  */
 export interface ChartTheme {
-  /**
-   * 主题名称或配置
-   */
   theme?: string | object;
-
-  /**
-   * 背景色
-   */
   backgroundColor?: string;
-
-  /**
-   * 文本颜色
-   */
   textColor?: string;
-
-  /**
-   * 轴线颜色
-   */
   axisLineColor?: string;
-
-  /**
-   * 分割线颜色
-   */
   splitLineColor?: string;
 }
 
@@ -117,64 +76,17 @@ export interface ChartTheme {
  * 图表加载状态配置
  */
 export interface ChartLoadingOptions {
-  /**
-   * 加载提示文本
-   */
   text?: string;
-
-  /**
-   * 加载动画颜色
-   */
   color?: string;
-
-  /**
-   * 文本颜色
-   */
   textColor?: string;
-
-  /**
-   * 遮罩颜色
-   */
   maskColor?: string;
-
-  /**
-   * z层级
-   */
   zlevel?: number;
-
-  /**
-   * 字体大小
-   */
   fontSize?: number;
-
-  /**
-   * 是否显示旋转器
-   */
   showSpinner?: boolean;
-
-  /**
-   * 旋转器半径
-   */
   spinnerRadius?: number;
-
-  /**
-   * 线宽
-   */
   lineWidth?: number;
-
-  /**
-   * 字体粗细
-   */
   fontWeight?: number | string;
-
-  /**
-   * 字体样式
-   */
   fontStyle?: string;
-
-  /**
-   * 字体族
-   */
   fontFamily?: string;
 }
 
@@ -216,7 +128,6 @@ export enum ChartEventType {
   BRUSHSELECTED = 'brushselected',
   RENDERED = 'rendered',
   FINISHED = 'finished',
-  // 自定义事件
   CHART_READY = 'chartReady',
   CHART_RESIZE = 'chartResize',
   CHART_ERROR = 'chartError',