鸿蒙中 帧动画ImageAnimator组件

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

一、ImageAnimator 组件简介

ImageAnimator 是用于播放帧动画的组件，支持逐帧播放图片，能够通过配置图片帧信息、播放时长、次数等属性来实现丰富的动画效果。它在 API Version 7 开始支持，从 API Version 10 开始支持在 ArkTS 卡片中使用，从 API Version 11 开始支持元服务。

二、ImageAnimator 的主要功能

1. 逐帧动画播放：通过设置图片列表和播放时长，实现逐帧播放图片。
2. 播放状态控制：支持开始、暂停、停止、恢复等控制操作。
3. 动画效果定制：通过属性设置播放次数、方向、时长等，实现多样化的动画效果。
4. 事件回调：提供动画状态变化的回调接口，如开始、暂停、完成等 。

三、ImageAnimator 的主要属性

以下是 ImageAnimator 支持的属性及其功能描述：

属性名称	类型	必填	描述
images	Array<ImageFrameInfo>	是	设置图片帧信息集合，每帧包含路径、大小、位置等信息。
duration	number	是	单次播放总时长（毫秒），若单帧设置了 duration，则总时长无效。
reverse	boolean	否	播放方向，false 正序播放，true 倒序播放。
fixedSize	boolean	否	是否固定图片大小为组件大小，true 表示图片与组件大小一致。
fillMode	FillMode	否	动画结束后的状态，如 Forwards（停留在最后一帧）。
iterations	number	否	播放次数，默认 1 次，-1 表示无限循环。
preDecode	number	否	预解码图片数量，用于性能优化（已弃用）。
state	AnimationStatus	否	控制动画状态，如 Running（运行）、Paused（暂停）。

四、ImageFrameInfo 对象说明

images 属性中的每一帧信息由 ImageFrameInfo 对象表示，具体属性如下：

属性名称	类型	必填	描述
src	string | Resource	是	图片路径，支持 png、jpg、svg 等格式。
width	number | string	否	图片宽度，默认值 0。
height	number | string	否	图片高度，默认值 0。
top	number | string	否	图片相对于组件左上角的纵向坐标，默认值 0。
left	number | string	否	图片相对于组件左上角的横向坐标，默认值 0。
duration	number	否	当前帧的显示时长（毫秒），若设置此属性，则总时长无效。

五、ImageAnimator 的主要事件

以下是支持的事件回调及其功能：

事件名称	功能描述	参数类型	描述
onStart	动画开始播放时触发	() => void	动画启动回调。
onPause	动画暂停播放时触发	() => void	动画暂停回调。
onRepeat	动画重复播放时触发	() => void	动画重复回调。
onCancel	动画返回初始状态时触发	() => void	动画取消回调。
onFinish	动画播放完成或停止时触发	() => void	动画完成回调。

六、ImageAnimator 的主要方法

以下是用于控制动画播放的方法：

方法名称	功能描述	参数	描述
start()	启动动画	无	开始播放动画。
pause()	暂停动画	无	暂停当前动画。
stop()	停止动画	无	停止动画并重置。
resume()	恢复动画	无	恢复暂停的动画。
getState()	获取当前动画状态	无	返回当前状态。

七、使用示例

示例1：基础动画配置

@Entry
@Component
struct ImageAnimatorExample {
  @State state: AnimationStatus = AnimationStatus.Initial;

  build() {
    Column({ space: 10 }) {
      ImageAnimator()
        .images([
          { src: $r('app.media.frame1') },
          { src: $r('app.media.frame2') },
          { src: $r('app.media.frame3') },
          { src: $r('app.media.frame4') }
        ])
        .duration(2000) // 总时长 2000ms
        .state(this.state)
        .reverse(false) // 正序播放
        .fillMode(FillMode.Forwards) // 动画结束停留在最后一帧
        .iterations(1) // 播放一次
        .width(300)
        .height(300)
        .onStart(() => {
          console.log('动画开始');
        })
        .onFinish(() => {
          console.log('动画结束');
        });
    }
  }
}

示例 2：动态控制动画状态 

@Entry
@Component
struct DynamicControlExample {
  @State animationStatus: AnimationStatus = AnimationStatus.Initial;

  build() {
    Column({ space: 10 }) {
      ImageAnimator()
        .images([
          { src: $r('app.media.frame1') },
          { src: $r('app.media.frame2') },
          { src: $r('app.media.frame3') }
        ])
        .duration(1000)
        .state(this.animationStatus)
        .reverse(true) // 倒序播放
        .width(200)
        .height(200);

      Button('开始动画')
        .onClick(() => {
          this.animationStatus = AnimationStatus.Running;
        });

      Button('暂停动画')
        .onClick(() => {
          this.animationStatus = AnimationStatus.Paused;
        });
    }
  }
}