Apache ECharts仪表盘动画失效问题（Angular 16环境）

在Angular 16.0.2环境使用Apache ECharts 5.5.1时，仪表盘（gauge）组件的动画未正常生效，但详情文本的动画可正常运行。已升级ECharts至5.5.1，问题仍存在；但在线编译器中复现场景时动画正常。

相关配置与代码 #

package.json中ECharts依赖 #

"node_modules/echarts": {
      "version": "5.5.1",
      "resolved": "https://registry.npmjs.org/echarts/-/echarts-5.5.1.tgz",
      "integrity": "sha512-Fce8upazaAXUVUVsjgV6mBnGuqgO+JNDlcgF79Dksy4+wgGpQB2lmYoO4TSweFg/mZITdpGHomw/cNBJZj1icA==",
      "dependencies": {
        "tslib": "2.3.0",
        "zrender": "5.6.0"
      }
}

chart.html #

<div echarts #EChartsPercentage [options]="getOptionsForPercentages()" style="width :100px"></div>

chart.ts #

getOptionsForPercentages() {
    const gaugeData = [
      {
        value: 20,
        name: 'Perfect',
        title: {
          offsetCenter: ['0%', '20%']
        },
        detail: {
          valueAnimation: true,
          offsetCenter: ['0%', '-10%']
        }
      }
    ];
    const option = {
      series: [
        {
          animation: true,
          animationDelay: 2000,
          animationDuration: 2000,
          animationThreshold: 500000,
          type: 'gauge',
          startAngle: 90,
          endAngle: -270,
          pointer: {
            show: false
          },
          clockwise: true,
          progress: {
            show: true,
            overlap: false,
            roundCap: true,
            clip: false,
            itemStyle: {
              borderWidth: 1,
              borderColor: '#464646'
            }
          },
          axisLine: {
            lineStyle: {
              width: 40
            }
          },
          splitLine: {
            show: false,
            distance: 0,
            length: 10
          },
          axisTick: {
            show: false
          },
          axisLabel: {
            show: false,
            distance: 50
          },
          data: gaugeData,
          title: {
            fontSize: 14
          },
          detail: {
            width: 50,
            height: 14,
            fontSize: 14,
            color: 'inherit',
            borderColor: 'inherit',
            borderRadius: 20,
            borderWidth: 1,
            formatter: '{value}%'
          }
        }
      ]
    };
    return option;
  }

common.module.ts #

import { NgxEchartsModule } from 'ngx-echarts';
.
.
@NgModule({
  declarations: [
    ...
  ],
  imports: [
    ...
    NgxEchartsModule.forRoot({
      echarts: () => import('echarts'),
    }),
  ],
  exports: [
    ...
  ],
  schemas: [NO_ERRORS_SCHEMA, CUSTOM_ELEMENTS_SCHEMA]
})

可能的原因与解决方法 #

1. Options重复生成导致动画中断 #

模板中直接绑定getOptionsForPercentages()会触发Angular每次变更检测时生成新的options对象，ECharts频繁接收新配置会打断初始动画逻辑。
解决：提前初始化options到组件属性，避免重复生成：

// chart.ts
percentageOptions: any;

ngOnInit(): void {
  this.percentageOptions = this.getOptionsForPercentages();
}

模板修改为：

<div echarts #EChartsPercentage [options]="percentageOptions" style="width :100px"></div>

2. ECharts懒加载初始化延迟 #

NgxEcharts的懒加载配置可能导致组件在ECharts完全加载前初始化，动画相关渲染逻辑未注册完成。
解决：在组件中等待ECharts加载完成后再初始化配置：

async ngOnInit(): Promise<void> {
  await import('echarts');
  this.percentageOptions = this.getOptionsForPercentages();
}

3. 变更检测策略冲突 #

若组件使用ChangeDetectionStrategy.OnPush，可能导致图表更新逻辑未被正确触发，影响动画执行。
解决：检查组件变更检测策略，若使用OnPush，可手动触发变更检测：

import { ChangeDetectorRef } from '@angular/core';

constructor(private cdr: ChangeDetectorRef) {}

async ngOnInit(): Promise<void> {
  await import('echarts');
  this.percentageOptions = this.getOptionsForPercentages();
  this.cdr.detectChanges();
}

4. 动画配置优先级问题 #

当前配置的animationDelay: 2000可能导致初始动画触发时机异常，且仪表盘的progress动画可能需单独配置。
解决：移除animationDelay，或给progress单独设置动画参数：

progress: {
  show: true,
  overlap: false,
  roundCap: true,
  clip: false,
  itemStyle: {
    borderWidth: 1,
    borderColor: '#464646'
  },
  animation: { duration: 2000 } // 单独配置progress动画
}

5. zrender版本兼容性 #

ECharts 5.5.1依赖的zrender 5.6.0可能与Angular 16环境存在兼容性问题，导致渲染层动画失效。
解决：尝试降级zrender到5.5.x版本，或升级至最新兼容版本：

npm install zrender@5.5.0 --save

内容的提问来源于stack exchange，提问作者reed richards