更新记录

1.1.0（2026-08-14）

• 鸿蒙端改为 renderjs + libpag-web 方案（ArkWeb 中渲染），彻底解决原生库崩溃与 embed 空白问题
• 修复鸿蒙 file:// 环境 CORS：wasm 内联 base64（script 加载），.pag 逻辑层下载转 base64 传递
• 新增 width/height 属性：控制动画渲染分辨率（canvas 像素尺寸），动态修改实时生效
• 修复等比缩放：libpag web PAGScaleMode 为数字枚举（fit=2），scaleMode 真正生效
• 修复 H5 依赖加载：本地静态资源优先，CDN（jsdelivr/unpkg）多级兜底
• App 下载统一使用 uni.downloadFile，移除 iOS/Android 原生下载实现（消除 Swift/Kotlin 编译兼容问题）
• 小程序 wasm 内置插件（static/mp-weixin/），本地 .pag 素材自动兜底 .png 后缀
• 修复小程序 canvas node 被 Vue3 响应式代理导致 libpag 崩溃（原生对象移出 data）

平台兼容性

uni-app(5.23)

sn-pag 腾讯 PAG 动画组件

基于腾讯 libpag 的跨平台 PAG 动画播放组件，支持 H5、微信小程序、App 安卓/iOS、App 鸿蒙。

平台支持

注意：App 端在普通 vue 页面通过 renderjs 运行 libpag web 版（wasm），非原生 PAGView 性能。如需原生性能，建议在 nvue/uvue 页面使用原生组件。

安装

1. 将 uni_modules/sn-pag 目录复制到项目的 uni_modules/ 下。
2. 安装 npm 依赖：

   npm install libpag libpag-miniprogram

3. 微信小程序：wasm 已随插件内置（static/mp-weixin/），在微信开发者工具执行「工具 → 构建 npm」即可。本地 .pag 素材若读取失败（微信对 .pag 后缀限制），插件会自动尝试 .png 后缀，或将素材复制一份为 .png 后缀使用。
4. App 端：使用 renderjs 方案，无需自定义基座；真机运行需配置网络下载权限（INTERNET 权限默认已有）。

基本用法

<template>
  <view style="width: 300px; height: 300px;">
    <sn-pag
      ref="pag"
      src="https://pag.qq.com/file/like.pag"
      :autoPlay="true"
      :repeatCount="-1"
      scaleMode="fit"
      :frameRate="60"
      @init="onInit"
      @load="onLoad"
      @animationStart="onStart"
      @animationEnd="onEnd"
      @frame="onFrame"
      @fail="onFail"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onInit() {
      console.log("init");
    },
    onLoad(e) {
      console.log("load", e);
    },
    onStart() {
      console.log("start");
    },
    onEnd() {
      console.log("end");
    },
    onFrame(e) {
      console.log("progress", e.progress);
    },
    onFail(e) {
      console.error("fail", e);
    },
  },
  onUnload() {
    this.$refs.pag && this.$refs.pag.destroy();
  },
};
</script>

Props

Events

Methods（通过 ref 调用）

错误码

注意事项

H5

• 网络 PAG 文件需服务端配置 CORS。
• wasm 文件需正确 MIME（application/wasm）。
• 默认从 jsdelivr CDN 加载 wasm，生产环境建议将 libpag wasm 部署到自己的静态服务器并修改 renderjs 中的 locateFile。

App 安卓/iOS

• 网络文件由 UTS 原生层下载到缓存目录，再由 renderjs 读取。
• 组件必须在页面 onUnload 时调用 destroy() 释放资源。
• renderjs 运行在 webview，性能低于原生渲染，复杂动效请真机测试。

微信小程序

• 必须复制 wasm 到 static/mp-weixin/ 并构建 npm。
• 本地 .pag 文件可能需要改后缀为 .png。

鸿蒙

• 需要 HBuilderX 4.23+ 与鸿蒙 vue3 项目。
• 实现方式：鸿蒙 vue 页面运行在 ArkWeb（webview）中，与 H5/App 端一样使用 renderjs + canvas + libpag-web 方案渲染（官方推荐，见 uni-app 文档：vue 页面可用 renderjs 集成 H5 版动画库）。
• 不要使用 @tencent/libpag（鸿蒙原生库）+ defineNativeEmbed 原生组件方案：实测该方案存在严重问题——1.0.1 版本在 API 20 设备上必然崩溃（libpag.so NAPI 回调与新版 SDK 不兼容）；4.5.88 版本在 embed（NodeController）环境中 XComponent 无法渲染（空白）。renderjs 方案彻底绕开这些问题。
• 鸿蒙 repeatCount 语义与其他平台一致（插件内部已做映射）。
• 注意：鸿蒙工具链对工程目录路径有限制（≤110字符、无中文特殊字符），如项目路径过长需在 .hbuilderx/launch.json 配置 distPathDev/distPathBuild 指定短路径。

依赖版本

• libpag web: ^4.5.84
• libpag-miniprogram: latest
• 鸿蒙端无需 ohpm 原生依赖（采用 renderjs + libpag-web，不使用 @tencent/libpag 鸿蒙库）