#### 示例代码 ```xml import { isMobile } from 'react-device-detect'; import { default as VChart } from '../../../../src/index';

// 1. 创建图表配置项与数据 const initialSpec = { type: 'bar', data: [ { id: 'barData', values: [ { month: 'January', sales: 22 }, { month: 'February', sales: 13 }, { month: 'March', sales: 25 }, { month: 'April', sales: 29 }, { month: 'May', sales: 38 } ] } ], xField: 'month', yField: 'sales', crosshair: { xField: { visible: true } }, animation: true // 开启动画 };

// 2. 创建 VChart 实例 const vchart = new VChart(initialSpec, { dom: 'chart' });

// 3. 渲染图表 vchart.renderAsync().then(() => { console.log('图表渲染完成'); });

// 4. 动画入场 setTimeout(() => { console.log('动画入场'); }, 1000);

// 5. 数据更新（新增图元） setTimeout(() => { const newData = [ { month: 'June', sales: 45 }, { month: 'July', sales: 50 } ]; vchart.updateDataSync('barData', newData, undefined, { reAnimate: true }); console.log('新增图元'); }, 3000);

// 6. 数据更新（图元更新） setTimeout(() => { const updatedData = [ { month: 'January', sales: 30 }, { month: 'February', sales: 20 }, { month: 'March', sales: 35 }, { month: 'April', sales: 39 }, { month: 'May', sales: 48 }, { month: 'June', sales: 55 }, { month: 'July', sales: 60 } ]; vchart.updateDataSync('barData', updatedData, undefined, { reAnimate: true }); console.log('图元更新'); }, 6000);

// 7. 数据更新（图元退出） setTimeout(() => { const remainingData = [ { month: 'January', sales: 30 }, { month: 'February', sales: 20 }, { month: 'March', sales: 35 }, { month: 'April', sales: 39 }, { month: 'May', sales: 48 } ]; vchart.updateDataSync('barData', remainingData, undefined, { reAnimate: true }); console.log('图元退出'); }, 9000);

// 8. 图元状态（state）的使用 setTimeout(() => { vchart.updateState( { selected: { style: { fill: 'red' } } }, (series, mark, stateKey) => { return mark.datum.sales > 40; } ); console.log('图元状态更新'); }, 12000);

// 9. 图表退场 setTimeout(() => { vchart.release(); console.log('图表退场'); }, 15000);

1. **创建图表配置项与数据**：
1. **创建 VChart 实例**：
1. **渲染图表**：
1. **动画入场**：
1. **数据更新（新增图元）**：
1. **数据更新（图元更新）**：
1. **数据更新（图元退出）**：
1. **图元状态（state）的使用**：
1. **图表退场**：

</div></div>
*  定义了一个初始的图表配置项`initialSpec`，其中包含图表类型、数据、坐标轴字段和动画配置。

*  数据部分包含了一个`barData`的数据集，初始包含5个月的销售数据。

*  使用`initialSpec`和DOM容器`chart`创建一个VChart实例。

*  调用`renderAsync`方法异步渲染图表。图表渲染完成后，会触发动画入场效果。

*  在渲染完成后，通过`setTimeout`模拟动画入场。实际动画效果由VChart内部处理。

*  在3秒后，通过`updateDataSync`方法新增两个月的销售数据。`reAnimate: true`参数确保新增数据时有动画效果。

*  在6秒后，通过`updateDataSync`方法更新所有图元的数据。`reAnimate: true`参数确保更新数据时有动画效果。

*  在9秒后，通过`updateDataSync`方法移除两个月的销售数据。`reAnimate: true`参数确保移除数据时有动画效果。

*  在12秒后，通过`updateState`方法更新图元的状态。这里设置了一个`selected`状态，当图元的`sales`值大于40时，图元的填充颜色变为红色。

*  在15秒后，通过`release`方法销毁图表实例，图表退场。

---


<div style="display: flex;"><div style="flex: 40; margin:5px;">#### 动画流程图
</div><div style="flex: 60; margin:5px;">#### 流程说明
1. **创建图表配置项与数据**：定义初始图表配置和数据。
1. **创建 VChart 实例**：使用配置和DOM容器创建VChart实例。
1. **渲染图表**：调用`renderAsync`方法渲染图表，触发动画入场效果。
1. **动画入场**：图表渲染完成后，自动触发入场动画。
1. **数据更新（新增图元）**：通过`updateDataSync`方法新增数据，触发新增动画。
1. **数据更新（图元更新）**：通过`updateDataSync`方法更新数据，触发更新动画。
1. **数据更新（图元退出）**：通过`updateDataSync`方法移除数据，触发退出动画。
1. **图元状态（state）的使用**：通过`updateState`方法更新图元状态，设置特定条件下的样式。
1. **图表退场**：通过`release`方法销毁图表实例，图表退场。

</div></div>
### 源码实现流程

1. **初始化 VChart 实例**

当你创建一个 `VChart` 实例并传入 `spec` 时，构造函数会处理 `animation` 配置：

文件：`vchart.ts` 方法：`constructor`

```xml
constructor(spec: ISpec, options: IInitOption) {
  this._option = mergeOrigin(this._option, { animation: (spec as any).animation !== false }, options);
  *// ...*
}

这段代码确保了如果 spec 中没有显式禁用动画（即 animation !== false），则启用动画。

• 设置新 spec 并初始化图表

在 VChart 类中，_setNewSpec 方法用于设置新的 spec，并将其转换为内部使用的格式：

文件：vchart.ts 方法：_setNewSpec

private _setNewSpec(spec: any, forceMerge?: boolean): boolean {
  if (!spec) {
    return false;
  }
  if (isString(spec)) {
    spec = JSON.parse(spec);
  }
  if (forceMerge && this._originalSpec) {
    spec = mergeSpec({}, this._originalSpec, spec);
  }
  this._originalSpec = spec;
  this._spec = this._getSpecFromOriginalSpec();
  return true;
}

接着，_initChartSpec 方法会根据 spec 初始化图表规格：

文件：vchart.ts 方法：_initChartSpec

private _initChartSpec(spec: any, actionSource: VChartRenderActionSource) {
  *// 如果用户注册了函数，在配置中替换相应函数名为函数内容*
  if (VChart.getFunctionList() && VChart.getFunctionList().length) {
    spec = functionTransform(spec, VChart);
  }
  this._spec = spec;
  if (!this._chartSpecTransformer) {
    this._chartSpecTransformer = Factory.createChartSpecTransformer(
      this._spec.type,
      this._getChartOption(this._spec.type)
    );
  }
  this._chartSpecTransformer?.transformSpec(this._spec);
  *// 插件生命周期*
  this._chartPluginApply('onAfterChartSpecTransform', this._spec, actionSource);
  this._specInfo = this._chartSpecTransformer?.transformModelSpec(this._spec);
  *// 插件生命周期*
  this._chartPluginApply('onAfterModelSpecTransform', this._spec, this._specInfo, actionSource);
}

• 创建和初始化 Chart 实例

在 _initChart 方法中，创建并初始化图表实例：

文件：vchart.ts 方法：_initChart

private _initChart(spec: any) {
  if (!this._compiler) {
    this._option?.onError('compiler is not initialized');
    return;
  }
  if (this._chart) {
    this._option?.onError('chart is already initialized');
    return;
  }
  const chart = Factory.createChart(spec.type, spec, this._getChartOption(spec.type));
  if (!chart) {
    this._option?.onError('init chart fail');
    return;
  }
  this._chart = chart;
  this._chart.setCanvasRect(this._currentSize.width, this._currentSize.height);
  this._chart.created(this._chartSpecTransformer);
  this._chart.init();
  this._event.emit(ChartEvent.initialized, {
    chart,
    vchart: this
  });
}

• 更新动画状态

当图表需要重新渲染或更新时，_updateAnimateState 方法会被调用来更新动画状态：

文件：vchart.ts 方法：_updateAnimateState

private _updateAnimateState(initial?: boolean) {
  if (this._option.animation) {
    const animationState = initial ? AnimationStateEnum.appear : AnimationStateEnum.update;
    this._chart?.getAllRegions().forEach(region => {
      region.animate?.updateAnimateState(animationState, true);
    });
    this._chart?.getAllComponents().forEach(component => {
      component.animate?.updateAnimateState(animationState, true);
    });
  }
}

• 初始状态：如果 initial 为 true，则设置动画状态为 AnimationStateEnum.appear（入场动画）。

• 更新状态：否则，设置为 AnimationStateEnum.update（更新动画）。

• 渲染图表

在 renderSync 和 renderAsync 方法中，animation 配置会被传递给编译器进行渲染：

文件：vchart.ts 方法：_renderSync

protected _renderSync = (option: IVChartRenderOption = {}) => {
  const self = this as unknown as IVChart;
  if (!this._beforeRender(option)) {
    return self;
  }
  *// 填充数据绘图*
  this._compiler?.render(option.morphConfig);
  this._afterRender();
  return self;
};

• 动画状态的更新

在 updateSpec 和 updateCustomConfigAndRerender 方法中，reAnimate 标志用于决定是否重新触发动画：

文件：vchart.ts 方法：updateSpec 和 updateCustomConfigAndRerender

if (userUpdateOptions?.reAnimate) {
  this.stopAnimation();
  this._updateAnimateState(true);
}

动画系统设计概述

VChart的动画系统设计遵循模块化、可扩展和易于配置的原则，旨在为开发者提供一个灵活且强大的工具来创建丰富的动画效果。以下是该系统的几个关键组成部分及其工作原理：

原理

1. 动画接口与抽象

• IAnimate 接口：定义了所有动画必须实现的方法和属性，包括获取唯一的ID、更新动画状态以及获取状态信号名称。

• IAnimationSpec 接口：规定了动画配置的结构，涵盖了从入场到退场的各种动画设置。

classDiagram

class AnimationStateEnum {

    --枚举--

    appear: AnimationStateEnum

    disappear: AnimationStateEnum

    enter: AnimationStateEnum

    update: AnimationStateEnum

    exit: AnimationStateEnum

    state: AnimationStateEnum

    normal: AnimationStateEnum

    none: AnimationStateEnum

}



class IAnimate {

    <<interface>>

    +updateAnimateState(state: AnimationStateEnum, noRender?: boolean): void

    +getAnimationStateSignalName(): string

    +id: number

}



class ICartesianGroupAnimationParams {

    <<interface>>

    +direction(): "x" | "y"

    +orient(): "positive" | "negative"

    +width(): number

    +height(): number

}



class AnimateManager {

    --属性--

    -_stateMap: IAnimateState & StateMap

    +id: number

    --方法--

    +updateAnimateState(state: AnimationStateEnum, noRender?: boolean): void

    +getAnimationStateSignalName(): string

    +constructor()

}



class MarkAnimationSpec {

    --属性--

    appear: IAnimationConfig

    enter: IAnimationConfig

    update: IAnimationConfig[]

    exit: IAnimationConfig

    disappear: IAnimationConfig

}



class IAnimationSpec {

    --属性--

    animationAppear: boolean | IStateAnimateSpec<Preset> | IMarkAnimateSpec<MarkName>

    animationEnter: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>

    animationUpdate: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>

    animationExit: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>

    animationDisappear: boolean | ICommonStateAnimateSpec | IMarkAnimateSpec<MarkName>

    animationState: boolean | IStateAnimationConfig

    animationNormal: IMarkAnimateSpec<MarkName>

}



class IStateAnimateSpec {

    --属性--

    duration?: number

    delay?: number

    easing?: EasingType

    oneByOne?: boolean

    preset?: Preset | false

}



class ICommonStateAnimateSpec {

    --属性--

    duration?: number

    delay?: number

    easing?: EasingType

    oneByOne?: boolean

}



class IMorphSeriesSpec {

    --属性--

    enable?: boolean

    morphKey?: string

    morphElementKey?: string

}



class IAnimateState {

    --属性--

    animationState: { callback: (datum: any, element: IElement) => AnimationStateEnum }

}



class IAnimationConfig {

    --属性--

    type?: string

    channel?: string

    custom?: Function

    customParameters?: Function

    oneByOne?: boolean | number

    duration?: number

    easing?: EasingType

    delay?: number

    delayAfter?: number

}



% 关系

AnimationStateEnum "1" --|> "多" AnimateManager: 使用

AnimateManager "1" --|> "1" IAnimate: 实现

AnimateManager "1" -- "1" ICartesianGroupAnimationParams: 依赖

IAnimationSpec "1" -- "多" spec.ts: 定义于

MarkAnimationSpec "1" -- "1" config.ts: 由 config.ts 使用

IAnimationConfig "1" -- "多" utils.ts: 由 utils.ts 处理

IStateAnimateSpec "1" -- "1" ICommonStateAnimateSpec: 继承

IAnimationSpec "1" -- "1" IStateAnimateSpec: 关联

IAnimationSpec "1" -- "1" IMorphSeriesSpec: 关联

IAnimateState "1" -- "1" AnimateManager: 内部使用

IAnimationConfig "1" -- "1" ICommonStateAnimateSpec: 继承

2. 动画管理器

• AnimateManager 类：继承自 StateManager 并实现了 IAnimate 接口，负责管理动画的状态，并提供方法来根据传入的状态更新动画。它处理动画状态的更新和检索，并根据不同状态更新动画状态。

3. 工厂模式

• Factory 类：用于注册新的动画类型，允许将自定义动画逻辑添加到图表组件中。通过静态方法 registerAnimation，可以将特定类型的动画与其配置关联起来，方便后续调用。

4. 动画配置生成

• animationConfig 函数：根据默认配置和用户提供的配置生成最终的动画配置。这个函数遍历所有的动画状态（如出现、进入、更新等），并根据用户配置或默认配置构建出完整的动画配置对象。

5. 动画任务接口

• IAnimationTask 接口：定义了一个动画任务的数据结构，这对于理解复杂的动画序列非常重要。每个任务包含时间偏移、动作队列和后继任务列表，形成了一种链式动画执行机制。

6. 动画的具体实现

• 每个具体的图表系列（如柱状图、饼图、散点图等）都有各自的动画实现文件，这些文件中包含了针对该系列的预设动画函数。例如，柱状图可能有生长动画、淡入动画等；饼图则可能有扇区展开动画等。

通过上述步骤，我们已经完成了一个简单但完整的动画流程创建。在这个过程中，我们利用了VChart动画系统的模块化设计，分别对图表配置、动画注册、实例化图表、数据更新以及动画状态管理进行了处理。这种设计不仅让代码更加清晰易读，同时也提高了系统的灵活性和可维护性。开发者可以根据实际需求轻松地定制不同类型的动画效果，从而提升用户体验。

为了更好地理解和解读这些源码文件，建议按照以下顺序阅读：

• **interface.ts**

• 原因：该文件定义了动画模块中的核心类型和接口，如 AnimationStateEnum、IAnimateState 和 IAnimate 等。理解这些类型和接口是后续代码的基础。

• 重点内容：

• 动画状态枚举 AnimationStateEnum

• 动画状态接口 IAnimateState

• 动画接口 IAnimate

• **spec.ts**

• 原因：该文件定义了动画配置的规范，包括 ICommonStateAnimateSpec、IStateAnimateSpec 和 IAnimationSpec 等。这些规范在实际动画配置中会被使用，因此需要先了解它们的结构。

• 重点内容：

• 动画配置的通用属性 ICommonStateAnimateSpec

• 动画状态配置 IStateAnimateSpec

• 动画规范 IAnimationSpec

• **config.ts**

• 原因：该文件提供了默认的动画配置和一些预设的动画注册函数。理解这些默认配置有助于理解如何自定义动画配置。

• 重点内容：

• 默认动画配置 DEFAULT_ANIMATION_CONFIG

• 预设动画注册函数（如 registerScaleInOutAnimation、registerFadeInOutAnimation 等）

• **utils.ts**

• 原因：该文件包含了许多辅助函数，用于生成和处理动画配置。理解这些函数的工作原理可以帮助你更好地理解动画配置是如何被应用的。

• 重点内容：

• 生成动画配置的函数 animationConfig

• 处理用户动画配置的函数 userAnimationConfig

• 辅助函数（如 produceOneByOne、shouldMarkDoMorph 等）

• **animate-manager.ts**

• 原因：该文件实现了 AnimateManager 类，它是管理动画的核心类。理解这个类的实现可以让你知道动画是如何被管理和更新的。

• 重点内容：

• AnimateManager 类的实现

• 更新动画状态的方法 updateAnimateState

• 获取动画状态信号名称的方法 getAnimationStateSignalName

总结

按照上述顺序阅读这些文件，可以逐步建立起对整个动画模块的理解。从基础的类型和接口开始，逐步深入到具体的配置和实现细节，最终理解动画是如何被管理和应用的。

阅读顺序总结

• **interface.ts** 核心类型和接口

• **spec.ts** 动画配置规范

• **config.ts** 默认配置和预设动画

• **utils.ts** 辅助函数和配置生成

• **animate-manager.ts**动画管理类实现

本文档由以下人员修正整理

玄魂