更新记录

1.0.0（2026-09-04） 下载此版本

• 首次发布。
• 支持 Android、iOS、HarmonyOS NEXT 和微信小程序播放 PAG 动画。
• 支持 uni-app 和 uni-app x 项目。
• 支持网络地址和本地 PAG 文件。
• 支持自动播放、循环次数和缩放模式配置。
• 提供 play、pause、stop、setProgress、reload 控制方法。
• 提供 load、start、repeat、end、error 事件。
• 微信小程序默认采用 libpag-lite-miniprogram，仅支持单个 BMP 视频序列帧格式的 PAG 文件。

平台兼容性

uni-app(4.61)

uni-app x(4.61)

其他

uni-pag-player

可被其他 uni-app / uni-app x 项目直接复制使用的 PAG 动画组件。App 原生端使用腾讯 libpag，传统 uni-app 的 App 页面使用 libpag Web，微信小程序使用官方轻量 SDK。

平台

微信小程序为了免拷贝 wasm、控制分包体积，默认使用官方 lite SDK，只支持“单个 BMP 视频序列帧”的 PAG 文件。导出时在 PAGExporter 根节点勾选 BMP；需要文字/矢量编辑等完整 PAG 能力时，请按后面的“完整小程序 SDK”切换。

安装

把 uni-pag-player 整个目录复制到目标项目的 uni_modules/ 下。HBuilderX 4.61+ 会按平台自动处理 Gradle、CocoaPods 和 OHPM 依赖；含原生依赖时请制作自定义调试基座，标准基座不能运行。

传统 uni-app / Web 工程还需在项目根目录安装 JavaScript 依赖：

npm i libpag@^4.5.85 libpag-lite-miniprogram@^4.5.85

微信开发者工具中执行一次“工具 → 构建 npm”。远程 .pag 地址必须加入微信小程序 downloadFile/request 合法域名，并允许 CORS（Web/App Vue）。

使用

组件符合 easycom 规范，不需要注册：

<template>
  <uni-pag-player
    ref="pag"
    class="pag"
    src="https://example.com/animation.pag"
    :autoplay="true"
    :repeat-count="0"
    scale-mode="letterBox"
    @load="onLoad"
    @error="onError"
  />
</template>

<script setup>
import { ref } from 'vue'
const pag = ref(null)
const onLoad = event => console.log('loaded', event)
const onError = event => console.error(event)

// pag.value.play()
// pag.value.pause()
// pag.value.stop()
// pag.value.setProgress(0.5)
// pag.value.reload()
</script>

<style>.pag { width: 300px; height: 300px; }</style>

属性

方法为 play()、pause()、stop()、setProgress(0..1)、reload()。事件为 load、start、repeat、end、error；不同 SDK 的原生回调能力有差异，load/error 在所有目标平台提供。

本地资源路径

• Android 原生：把 PAG 放到项目 Android assets，传 assets://animation.pag。
• iOS：传主 Bundle 中资源的绝对路径。
• HarmonyOS：传沙箱文件路径或 HTTPS 地址。
• 微信小程序：传 wx.env.USER_DATA_PATH 中的文件路径，或 HTTPS 地址。
• App Vue/Web：建议使用 HTTPS 或 /static/... 构建后的 URL。

完整小程序 SDK（可选）

如果 PAG 不是单一 BMP 序列帧，将 libpag-lite-miniprogram 换成 libpag-miniprogram，并按腾讯文档把该包的 lib/libpag.wasm.br 放入项目可访问目录，然后通过 PAGInit({ locateFile }) 初始化。完整 SDK 会明显增加包体，插件默认不内置二进制，以免占用所有引用项目的主包额度。

打包提示

• Android 最低 API 21；混淆时 libpag AAR 已带 consumer rules，若宿主覆盖规则，追加 -keep class org.libpag.** { *; }。
• iOS deployment target 为 12.0。
• HarmonyOS NEXT 至少 API 12，建议使用与 HBuilderX 配套的最新 DevEco SDK。
• 原生依赖锁定在 libpag 4.4.53 / OHPM 1.x，JavaScript SDK 锁定兼容版本范围；升级前应在四端真机回归。

许可

插件源码采用 MIT；腾讯 libpag 由其 Apache-2.0 许可证约束，未复制到本仓库。