更新记录

1.0.0（2026-07-17）

• 首个稳定版本。
• 支持 uni-app x Web、Android、iOS 和 HarmonyOS，以及 uni-app Vue 3 H5/Web。
• 支持本地路径、远程 URL 和平台绝对路径加载 PAG 动画。
• 支持自动播放、循环次数、画面适配、最大帧率、缓存和视频层配置。
• 提供播放、暂停、停止、进度跳转、状态查询和缓存清理方法。
• 提供 ready、error、start、end、cancel、repeat 事件及统一错误码。
• 支持通过唯一组件 ID 创建 Context，并支持同页多实例独立播放。
• 集成 libpag 原生依赖，并随插件提供 Web WASM 资源和第三方许可证声明。

平台兼容性

uni-app(5.15)

uni-app x(5.15)

hans-pag

hans-pag 是基于 libpag 的 PAG 动画播放组件，支持本地和远程 .pag 文件、播放控制、进度跳转、循环和多实例播放。

平台兼容

• HBuilderX 4.61+
• Android API 21+，支持 armeabi-v7a、arm64-v8a、x86_64
• iOS 12.0+
• HarmonyOS NEXT API 15+，仅支持 arm64-v8a
• Web 建议 Chrome 69+ 或 Safari 15+

安装

将插件导入项目，确认目录为 uni_modules/hans-pag。Android、iOS 和 HarmonyOS 使用原生依赖；调试 App 时如标准基座不包含依赖，请制作自定义调试基座。

uni-app x 用法

<template>
    <hans-pag
        id="bannerPag"
        class="pag"
        src="/static/pag/banner.pag"
        :autoplay="true"
        :repeat-count="0"
        scale-mode="letter-box"
        @ready="onReady"
        @error="onError"
    />
</template>

<script setup lang="uts">
    import { createHansPagContext } from "@/uni_modules/hans-pag"

    function onReady(e: UTSJSONObject) {
        console.log("duration", e.getNumber("durationMs", 0))
    }

    function onError(e: UTSJSONObject) {
        console.error(e.getString("code", ""), e.getString("message", ""))
    }

    function pauseBanner() {
        createHansPagContext("bannerPag")?.pause()
    }
</script>

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

uni-app Vue 3 Web 用法

<template>
    <hans-pag ref="pagRef" class="pag" src="/static/pag/banner.pag" @error="onError" />
</template>

<script setup>
    import { ref } from 'vue'

    const pagRef = ref(null)

    function onError(e) {
        console.error(e.code, e.message)
    }

    function pauseBanner() {
        pagRef.value?.pause()
    }
</script>

Props

事件

uni-app x 事件参数为 UTSJSONObject，uni-app Vue 3 Web 为普通对象。

错误码包括 E_UNSUPPORTED_PLATFORM、E_NATIVE_DEP_MISSING、E_INIT_FAILED、E_INVALID_SRC、E_LOAD_FAILED、E_DECODE_FAILED、E_CANCELLED、E_WASM_LOAD_FAILED 和 E_RENDER_FAILED。

实例方法

uni-app x 使用 createHansPagContext(id) 获取实例；uni-app Vue 3 Web 使用组件 ref。两者提供相同方法：

使用注意

• 多实例使用时必须设置不同的 id，并在页面卸载后避免继续持有旧 Context。
• Web 加载远程 PAG 时，资源服务器必须允许跨域访问。
• Web 使用单线程 WASM；大量同屏实例可能受浏览器 WebGL context 数量和设备性能限制。
• 普通 uni-app Vue 3 仅支持 H5/Web；Android、iOS、HarmonyOS 原生播放请使用 uni-app x。
• 1.0.0 仅提供播放能力，不支持文字/图片替换、截图或图层查询。

隐私与许可证

组件自身不采集个人信息。src 为远程地址时，网络请求由宿主应用指定并负责合规。libpag 采用 Apache-2.0 许可证，相关许可证和第三方声明位于 LICENSES/。