ohos_apng-drawable:支持APNG（动态PNG）格式的解析与渲染

apng-drawable

简介

apng-drawable是一个快速且轻量级的动画便携网络图形（APNG）图像解码库。本库基于 apng-drawable 原库进行适配，使其可以运行在 OpenHarmony，并沿用其现有用法和特性。

下载安装

   ohpm install @ohos/apng-drawable

OpenHarmony ohpm环境配置等更多内容，请参考 如何安装OpenHarmony ohpm包 。

使用说明

导入并使用

import { ApngDrawable, AnimationCallback } from '@ohos/apng-drawable';

@Entry
@Component
struct Index {
  @State drawable: ApngDrawable | null = null;
  @State callbackText: string = '';
  ...
  
  build() {
    Column() {
      Row() {
        Text('ApngDrawable')
          .fontSize(20)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.White)
          .layoutWeight(1)
          .textAlign(TextAlign.Center)
      }
      .width('100%')
      .height(56)
      .backgroundColor(PRIMARY_COLOR)
      .padding({ left: 16, right: 16 })

      Column() {
        Text($r('app.string.image_1'))
          .fontSize(14)
          .fontWeight(FontWeight.Medium)
          .margin({ top: 16, bottom: 8, left: 16 })
          .width('100%')
          .textAlign(TextAlign.Start)

        Scroll() {
          Row() {
            this.createButton($r('app.string.load'), () => this.startLoad('test.png'));
            this.createButton($r('app.string.load_5x'), () => this.startLoad('test.png', 500, 500));
            this.createButton($r('app.string.load_10x'), () => this.startLoad('test.png', 1000, 1000));
            this.createButton($r('app.string.copy'), () => this.duplicate());
            this.createButton($r('app.string.remove'), () => this.removeView());
          }
          .padding({ left: 12, right: 12, top: 4, bottom: 4 })
        }
        .scrollable(ScrollDirection.Horizontal)
        .scrollBar(BarState.Off)
        .width('100%')
      }
      .layoutWeight(1)
      .width('100%')
      .backgroundColor('#FFFFFF')
      }
      .width('100%')
    .height('100%')
    .backgroundColor('#FFFFFF')
  }

  @Builder
  createButton(text: Resource, onClick: () => void): void {
    Button(text)
      .type(ButtonType.Normal)
      .backgroundColor('#E0E0E0')
      .fontColor('#000000')
      .fontSize(14)
      .fontWeight(FontWeight.Normal)
      .height(36)
      .padding({ left: 16, right: 16 })
      .margin({ right: 8 })
      .onClick(onClick)
  }
  ...
}

更多详细用法请参考开源库sample页面的实现

接口说明

常量

常量	值	说明
LOOP_FOREVER	0	无限循环
LOOP_INTRINSIC	-1	使用APNG内置循环次数

属性

属性	类型	说明
durationMillis	number	动画总时长（毫秒），只读
frameCount	number	动画总帧数，只读
frameDurations	number[]	每帧持续时间数组（毫秒），只读
frameByteCount	number	单帧缓冲区字节大小（宽×高×4），只读
allocationByteCount	number	所有帧的总内存分配，只读
isRecycled	boolean	是否已被回收，只读
currentLoopIndex	number	当前循环索引，只读
currentFrameIndex	number	当前帧索引，只读

方法

方法名	参数	返回值	说明
decode()	buffer: ArrayBuffer, width?: number, height?: number	ApngDrawable	解码 APNG
isApng()	buffer: ArrayBuffer	boolean	判断是否为 APNG
start()	-	void	开始播放
stop()	-	void	停止播放
isRunning()	-	boolean	检查动画是否正在运行
seekTo()	positionMillis: number	void	按毫秒跳转
seekToFrame()	loopIndex: number, frameIndex: number	void	按循环+帧索引跳转
getLoopCount()	-	number	获取循环次数
setLoopCount()	count: number	void	设置循环次数 - -1: 使用APNG文件内嵌循环次数 - 0: 无限循环（默认） - n>0: 循环n次后停止
registerAnimationCallback()	callback: AnimationCallback	void	注册动画回调
unregisterAnimationCallback()	callback: AnimationCallback	boolean	取消注册
clearAnimationCallbacks()	-	void	清空所有回调
copy()	-	ApngDrawable	复制 ApngDrawable
recycle()	-	void	释放资源
getCurrentFrame()	-	Promise<PixelMap | null>	获取当前帧 PixelMap
exportAsBitmap()	-	Promise<PixelMap | null>	导出当前帧为 Bitmap（PixelMap）
saveAsPng()	filePath: string	Promise<boolean>	将当前帧保存为 PNG 文件

约束与限制

在下述版本验证通过：

• DevEco Studio NEXT Developer Beta3: (5.0.3.530), SDK: API12 (5.0.0.35(SP3))

项目结构

|---- ohos_apng-drawable  
|     |---- entry  # 示例代码文件夹
|     |---- library  # apng-drawable 库文件夹
|     |     |---- src
|     |     |     └── main  
|     |     |         |---- cpp  # C++ Native 代码
|     |     |         |    |---- apng-drawable  # APNG解码器核心
|     |     |         |    |---- thirdparty/libpng  # libpng 核心库
|     |     |         |    |---- CMakeLists.txt
|     |     |         |    └──   napi_init.cpp
|     |     |         └── ets  # ArkTS 代码
|     |     |             |---- apng
|     |     |             |    |---- Apng.ets        # APNG封装类
|     |     |             |    |---- ApngDrawable.ets # Drawable实现
|     |     |             |---- types
|     |     |             |    |---- ApngTypes.ets   # 类型定义
|     |     |---- Index.ets  # 对外接口
|     |---- README.md  # 英文说明
|     |---- README_zh.md  # 中文说明

编译运行，生成依赖库的.so文件

执行脚本：./prebuild.sh

将编译生成的libpng文件夹，拷贝到工程的library/src/main/cpp/thirdparty目录下。

apng-drawable的主要功能代码均在native侧实现，并提供给ArkTS侧使用。

贡献代码

使用过程中若发现任何问题，欢迎提交 Issue ，同时也非常欢迎发起 PR 共同建设。

开源协议

本项目基于 Apache License 2.0 ，请自由地享受和参与开源。