HarmonyOS 技术精讲 - Image Kit：动图处理 - GIF 与 WebP 帧操作

一、开篇：一个常见的动图处理问题

HarmonyOS NEXT 开发中，Image Kit 的使用率很高，但动图处理这块，很多人第一次接触时都会遇到一个尴尬情况：能获取到 ImageSource，但帧数据读不出来，或者读出来的帧顺序是乱的。

拿一个简单场景举例：App 里需要一个表情选择器，用户点一下 GIF，页面能逐帧播放预览。这时候，你要解决的问题就是：如何正确地从 GIF 中把每一帧的 PixelMap 取出来，并精确控制每帧的停留时间。

Image Kit 提供了一套较完整的动图解码能力，但关键 API 的调用顺序和参数细节很容易踩坑。本文围绕一个具体功能 —— 读取 GIF 文件，打印每帧延迟时间，并实现循环播放所有帧的简单动画 —— 把整个过程拆解清楚。

二、它解决什么问题

Image Kit 的动图处理主要解决以下场景：

场景	说明
GIF 动图显示与播放	获取帧数据、控制播放进度
WebP 动图支持	与 GIF 使用同一套 API，无额外适配成本
逐帧编辑	获取每帧 PixelMap 后进行裁剪、缩放、叠加等操作
自定义动画控制器	不依赖系统默认播放，开发者可以自己控制帧切换逻辑

适合场景：自定义表情播放、帧动画编辑器、帧级图片处理。

不适合场景：只是简单显示一个动图，不需要关注帧细节 —— 直接用 Image 组件的 source 属性就够了。

三、环境说明

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机

四、核心实现：GIF 逐帧解码与播放

4.1 读取文件并创建 ImageSource

动图处理的第一步是通过 fs.open 获取文件描述符，然后创建 ImageSource。

下面是完整的文件读取代码：

import { fs } from '@kit.CoreFileKit';
import { image } from '@kit.ImageKit';
import { common } from '@kit.AbilityKit';

@Entry
@Component
struct GifPlayer {
  @State currentIndex: number = 0;
  @State totalFrames: number = 0;
  @State pixelMaps: image.PixelMap[] = [];
  @State frameDelays: number[] = [];
  private updateTask: number = -1;

  aboutToAppear() {
    this.loadGif();
  }

  async loadGif() {
    const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
    // 将 GIF 文件放到 resources/rawfile 目录下
    const fileUri = 'resource://rawfile/animation.gif';
    const file: fs.File = fs.openSync(fileUri, fs.OpenMode.READ_ONLY);
    
    // 创建 ImageSource
    const imageSource: image.ImageSource = image.createImageSource(file.fd);

    // 获取总帧数
    const frameCount: number = imageSource.getFrameCount();
    this.totalFrames = frameCount;
    console.info(`总帧数: ${frameCount}`);

    // 遍历每一帧，获取延迟时间和 PixelMap
    const pixelMaps: image.PixelMap[] = [];
    const delays: number[] = [];
    for (let i = 0; i < frameCount; i++) {
      const delay = this.getFrameDelay(imageSource, i);
      delays.push(delay);
      const pixelMap: image.PixelMap = await imageSource.createPixelMap({
        index: i,
        desiredSize: { width: 120, height: 120 }
      });
      pixelMaps.push(pixelMap);
    }
    this.pixelMaps = pixelMaps;
    this.frameDelays = delays;

    // 打印延迟时间
    delays.forEach((d, idx) => {
      console.info(`帧 ${idx} 延迟: ${d} 毫秒`);
    });

    // 开始播放
    this.startAnimation();
  }

  getFrameDelay(source: image.ImageSource, index: number): number {
    // 通过 ImageSource 的 getImageProperty 获取帧延迟
    // 注意属性名：GIF 使用 "FrameDelay"，WebP 使用 "AnimationDelay"
    const delayStr: string = source.getImageProperty("FrameDelay", index);
    // 返回毫秒值，如果获取不到则使用默认 100ms
    return delayStr ? parseInt(delayStr) : 100;
  }

  startAnimation() {
    if (this.pixelMaps.length === 0) return;
    const delay = this.frameDelays[this.currentIndex];
    // 使用 setInterval 模拟帧切换
    this.updateTask = setInterval(() => {
      this.currentIndex = (this.currentIndex + 1) % this.totalFrames;
      const nextDelay = this.frameDelays[this.currentIndex];
      // 动态调整 interval 刷新频率
      clearInterval(this.updateTask);
      this.startAnimation();
    }, delay);
  }

  aboutToDisappear() {
    if (this.updateTask !== -1) {
      clearInterval(this.updateTask);
    }
    // 释放 PixelMap 内存
    this.pixelMaps.forEach(pm => pm.release());
  }

  build() {
    Column() {
      if (this.pixelMaps.length > 0) {
        Image(this.pixelMaps[this.currentIndex])
          .width(200)
          .height(200)
      } else {
        Text('加载中...')
      }
      Text(`帧: ${this.currentIndex + 1} / ${this.totalFrames}`)
        .fontSize(14)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

这段代码关键点：

• image.createImageSource(file.fd) 通过文件描述符创建解码源
• getFrameCount() 返回动图总帧数，这是获取帧信息的第一步
• createPixelMap({ index }) 解码指定帧，返回 PixelMap，可以用于显示或继续处理
• getImageProperty("FrameDelay") 获取帧延迟时间，单位是毫秒

注意事项：

1. getFrameCount 必须在 createPixelMap 之前调用。如果先解码帧，再获取帧数，部分实现中可能会返回 0。
2. createPixelMap 中 desiredSize 参数用于控制输出尺寸，如果不指定，会输出原图大小。
3. “FrameDelay” 属性名大小写敏感，写成 "frameDelay" 会拿不到值。
4. WebP 动图使用 "AnimationDelay" 替代 "FrameDelay"，这部分需要做区分。

4.2 实现循环播放：如何控制动画节奏

上面代码中使用了 setInterval 调用 startAnimation，但有个问题：每次帧切换后，下一帧的延迟时间可能不同。如果只设置一个固定的 interval，会导致播放速度不匹配。

解法是：每切换一次帧，就重新算一次 interval 时间。

startAnimation() {
  if (this.pixelMaps.length === 0) return;
  const delay = this.frameDelays[this.currentIndex];
  this.updateTask = setInterval(() => {
    this.currentIndex = (this.currentIndex + 1) % this.totalFrames;
    clearInterval(this.updateTask);
    this.startAnimation();
  }, delay);
}

这样虽然能适配可变延迟，但有个缺点：当 delay 为 0 或负数时，setInterval 会立即触发多次，导致循环失控。安全起见，需要做一层保护：

const safeDelay = Math.max(delay, 16); // 最低 16ms（约 60fps）

五、踩坑记录

问题 1：帧索引越界

现象：调用 createPixelMap({ index: frameCount }) 时，索引从 0 开始，getFrameCount 返回的是 N，但 index 最大允许值是 N-1。如果访问 index = N，会抛 BusinessError。

原因：getFrameCount 返回的是图片实际存在的帧数，而 createPixelMap 的索引参数是 0-based。

解法：始终在 0 到 frameCount - 1 之间循环，取模运算一定要用 % totalFrames。

问题 2：延迟时间单位不一致

现象：部分 GIF 的延迟时间以 1/100 秒（百分秒）为单位存储，而 getImageProperty("FrameDelay") 默认返回的是毫秒。如果图片的延迟值为 5（百分秒），实际应该显示 50ms，但代码会当成 5ms 处理。

原因：GIF 规范中，帧延迟的存储单位是 10ms 的倍数。有些编码器存的是百分秒，有些存的是毫秒。Image Kit 的 getImageProperty 返回的是整数，但没有标明来源单位。

解法：如果发现播放速度明显过快，可以打印延迟值进行校验。对于低于 20ms 的延迟值，统一放大 10 倍处理：

let displayDelay = parseInt(delayStr);
if (displayDelay < 20) {
  displayDelay *= 10;
}
return displayDelay;

这个方案不一定适用所有文件，但能覆盖大部分网上的 GIF 资源。

六、最佳实践

1. 不要在 build() 中频繁创建对象
   build() 方法会被 ArkUI 多次调用。如果把 PixelMap 的创建逻辑写在里面，会频繁触发组件重建，造成性能问题。建议在 aboutToAppear 或 onPageShow 中统一解析，然后把 PixelMap 数组存入 @State 变量。

2. 释放 PixelMap 内存
   PixelMap 对象持有原生内存资源，用完后必须调用 release() 释放。尤其是在页面销毁的回调 aboutToDisappear 中，需要遍历释放所有 PixelMap。不释放容易导致内存泄漏，长时间运行后 App 可能被系统强杀。

3. 区分 GIF 和 WebP 的属性名
   两个格式使用不同的属性名：

   • GIF: "FrameDelay"
   • WebP: "AnimationDelay"
     推荐统一先尝试 "FrameDelay"，如果返回空再试 "AnimationDelay"，或者根据文件后缀判断。

七、Demo 入口

完整的页面组件如下：

@Entry
@Component
struct Index {
  build() {
    GifPlayer()  // 上面定义的组件
  }
}

将 GIF 文件放入 resources/rawfile 目录下，命名为 animation.gif，直接运行即可看到效果。

八、FAQ

Q：为什么模拟器上 GIF 播放正常，真机上一闪而过？
A：模拟器对帧延迟的解析可能比真机宽松。真机上如果延迟时间获取失败（返回 NaN），会导致 interval 被设为 0，立即触发帧切换。建议在 getImageProperty 返回错误时，提供一个默认值如 100ms。

Q：页面返回后再进入，动图不播放了？
A：aboutToAppear 在页面从后台回到前台时会再次调用，但如果页面已经被销毁再重建，aboutToDisappear 中的 clearInterval 已经执行过，updateTask 被清空。正确做法是在 onPageShow 中重新初始化，在 onPageHide 中暂停动画。

Q：为什么获取到的帧字节数组是空的？
A：createPixelMap 成功返回 PixelMap 后，如果需要获取原始字节，必须用 readPixelsToBuffer 方法。PixelMap 本身不直接存字节数据，它只是一个上层封装对象。

如果你也遇到类似问题，可以重点检查帧索引边界和延迟时间单位。这个功能本身不复杂，但生命周期管理和内存释放处理的好坏，直接影响 App 稳定性。