PAG Manager Wrapper

一个用于简化 libpag 动画初始化和使用的轻量级封装库。

✨ 特性

• 🎯 极简设计 - 只保留核心功能，代码精简易维护
• 🚀 快速上手 - 3 行代码即可使用
• 🎬 智能处理 - 自动检测 video 元素并采用不同渲染策略
• 🎨 基础控制 - 播放、暂停、停止
• 📦 超轻量级 - 除 libpag 外无其他依赖

📦 安装

npm install pag-manager-wrapper libpag rollup-plugin-copy

🚀 快速开始

最简使用（3 行代码）

import PAGManager from 'pag-manager-wrapper';

const pagManager = new PAGManager();
await pagManager.init({ url: '/animation.pag', canvas: 'pag-canvas', autoPlay: true });

完整示例

import PAGManager from 'pag-manager-wrapper';

const pagManager = new PAGManager();

// 初始化
await pagManager.init({
  url: '/path/to/animation.pag',
  canvas: 'my-canvas',      // Canvas 元素 ID 或 DOM 对象
  repeatCount: 1,           // 播放次数，0 为无限循环
  autoPlay: false           // 是否自动播放
});

// 播放控制
pagManager.play();          // 播放
pagManager.pause();         // 暂停
pagManager.stop();          // 停止

// 销毁释放资源
pagManager.destroy();

🎯 核心特性：Video 元素智能处理

本库会自动检测 PAG 文件是否包含 video 元素，并采用不同的渲染策略：

• 包含 video 元素：使用特殊渲染流程，确保 video 首帧正确显示
• 不包含 video 元素：直接渲染，性能更优

// 库内部自动处理
const hasVideo = pagFile.numVideos() > 0;

if (hasVideo) {
  // 使用特殊渲染流程
  await this.renderVideoFirstFrame(this.pagView);
} else {
  // 直接渲染首帧
  await this.pagView.flush();
}

📖 API 文档

init(options)

初始化 PAG 动画

参数：

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | url | string | 是 | - | PAG 文件 URL | | canvas | string | HTMLCanvasElement | 是 | - | Canvas 元素 ID 或 DOM 对象 | | repeatCount | number | 否 | 1 | 重复次数，0 为无限循环 | | autoPlay | boolean | 否 | false | 是否自动播放 |

返回： Promise<PAGView> - PAGView 实例

play()

播放动画

pause()

暂停动画

stop()

停止动画并重置到第一帧

destroy()

销毁 PAG 实例，释放资源

💡 使用示例

Vue 3

<template>
  <div>
    <canvas id="pag-canvas"></canvas>
    <button @click="pagManager.play()">播放</button>
    <button @click="pagManager.pause()">暂停</button>
  </div>
</template>

<script setup>
import { onMounted, onUnmounted } from 'vue';
import PAGManager from 'pag-manager-wrapper';

const pagManager = new PAGManager();

onMounted(async () => {
  await pagManager.init({
    url: '/animation.pag',
    canvas: 'pag-canvas',
    repeatCount: 1
  });
});

onUnmounted(() => {
  pagManager.destroy();
});
</script>

⚙️ 配置 Vite

在 vite.config.js 中添加 wasm 文件复制配置：

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import copy from 'rollup-plugin-copy';

export default defineConfig({
  plugins: [
    vue(),
    copy({
      targets: [
        {
          src: './node_modules/libpag/lib/libpag.wasm',
          dest: process.env.NODE_ENV === 'production' ? 'dist/' : 'public/'
        }
      ],
      hook: process.env.NODE_ENV === 'production' ? 'writeBundle' : 'buildStart'
    })
  ]
});

🎯 设计理念

本库采用极简设计理念，只保留最核心的功能：

✅ 保留的功能

• PAG 初始化
• Video 元素检测和特殊处理
• 基础播放控制（play, pause, stop）
• 资源销毁

理由： 如果需要高级功能，可以直接使用 init() 返回的 PAGView 实例调用 libpag 的原生 API。

📋 注意事项

1. Canvas 元素必须提前存在于 DOM 中
2. 使用完毕后记得调用 destroy() 释放资源
3. 一个 PAGManager 实例对应一个动画
4. 支持传入 Canvas 元素 ID（字符串）或 Canvas DOM 对象

📄 许可证

MIT License

简洁 · 高效 · 易用