PAG官网 | PAG动效

PAG官网 | PAG动效

  • 首页
  • 产品
  • 功能
  • 文档
  • 案例
  • CN
    EN
    English
    CN
    简体中文
  • GitHub
  • 论坛交流
  • 免费下载
  • Languages iconCN
    • EN

›Web 进阶

了解 PAG

  • PAG 简介
  • 常见问题

快速开始

  • 安装 PAGViewer
  • 安装 AE 导出插件
  • 导出 PAG 文件
  • SDK 快速接入

导出插件

  • 插件选项配置面板
  • 导出面板使用指南
  • BMP 预合成导出
  • PAG 填充模式
  • PAG 时间伸缩
  • 快捷键设置
  • 导出错误码说明
  • AE 导出检测规则
  • 文本制作规则
  • 添加文本背景
  • 如何导出音频
  • 手动安装导出插件

预览工具

  • 编辑预览效果
  • 查看 PAG 文件结构
  • 快捷键列表
  • 导出图片序列
  • 素材加水印
  • 切换 Beta 版本

性能优化

  • 使用性能监测面板
  • PAG 素材优化指南

移动端进阶

  • 常用 API 解读
  • UI 及列表场景播放优化
  • 占位图替换视频
  • 播放有声素材
  • 文本图层说明
  • 渲染导出视频
  • 企业版 SDK 鉴权

Web 进阶

  • SDK 安装
  • 加载 PAG 文件
  • 播放 PAG 文件
  • 平台特性说明

API 参考

  • API 文档

视频教程

  • PAG 使用流程
  • PAG 性能优化分享
  • PAGExporter 面板分享
  • PAG 线上答疑

资源下载

  • PAGViewer 下载
  • PAG 测试素材下载
  • PAG Demo 工程下载
  • 2022 音视频技术大会
  • PAG 转换工具下载
  • PAG 文件格式规范

TAVMedia

  • TAVMedia 简介
  • TAVMedia 快速入门
  • 常用 API 解读

其他

  • Lottie 迁移至 PAG
  • 专业词汇表

播放 PAG 文件


初始化 PAGView

指定 PAGFile 对象与 canvas 对象进行绑定,实例化成 PAGView 对象。

const pagView = await PAG.PAGView.init(pagFile, canvas);

首帧渲染

PAGView.init 默认会进行首帧渲染。

在进行首帧渲染的过程中,当 PAG 动画文件中存在 BMP 预合成(下文说明如何确认 PAG 文件是否存在 BMP 预合成)时,会调用 VideoReader 模块。

由于 VideoReader 模块在 Web 平台依赖于 VideoElement,所以在部分移动端场景下,PAGView.init 不是在用户交互产生的调用链中,可能会存在不允许播放导致无法正常渲染画面的问题。

当出现这种情况,我们推荐取消首帧渲染

const pagView = await PAG.PAGView.init(pagFile, canvas, { firstFrame: false });

在用户交互产生的调用链中再调用 pagView.play() 进行画面渲染。

高清渲染

在 Web 平台上,我们需要考虑两种像素分辨率:设备像素分辨率(设备实际的点的数量)和 CSS 像素分辨率(在编程时我们所使用的点的数量)。这两者之间的比率被称为 devicePixelRatio。这意味着,如果我们想在屏幕上显示一个 1px 大小的 CSS 像素,我们实际需要渲染的尺寸是 1px * devicePixelRatio。

默认情况下,PAG 会自动缩放 Canvas 的尺寸以适应屏幕的可视尺寸。这个过程可能会改变 Canvas 的宽高以及 style 属性。

如果你不希望 PAG 修改 Canvas 的属性,你可以在初始化时取消缩放,如下所示:

const pagView = await PAG.PAGView.init(pagFile, canvas, { useScale: false });

多个 PAGView

首先,因为 PAG Web 版是单线程的 SDK,所以我们不建议同屏播放多个 PAGView。

对于有多个 PAGView 实例的场景,我们需要先知道,浏览器环境中 WebGL 活跃的 context 数量是有限制的,Chrome 是 16 个, Safari 是 8 个。因为有这个限制存在,我们应当及时使用 destroy 回收无用的 PAGView 实例和移除 Canvas 的引用。

推荐的解决方案是使用 PAG 的组合模式,自己创建一个 PAGComposition,然后把需要播放的 PAGFile 通过 addLayer 的方法添加 进去,setStartTime 可以设置每个 PAGFile 相对于 PAGComposition 的开始时间,setMatrix 可以设置相当于 PAGComposition 的位置。

以下是特殊场景的解决方法,不推荐使用:

如果你需要在 Chrome 浏览器中同屏存在多个 PAGView 实例且不需要在 Safari 上使用,可以尝试使用 canvas2D 模式,需要在 PAGView.init 的时候传入 { useCanvas2D: true } 。这个模式下,会用一个 WebGL 当作渲染器,然后往多个 canvas2D 分发画面,从而规避 WebGL 活跃 context 数量的限制。

因为 Safari 上 CanvasRenderingContext2D.drawImage() 的性能很差,所以我们不推荐在 Safari 上使用这个模式。

渲染尺寸

为了高清的渲染效果,PAGView 默认会按照 Canvas 尺寸 * devicePixelRatio 作为实际渲染尺寸。 受设备自身性能影响 WebGL 的最大渲染尺寸可能各不相同。会出现渲染尺寸过大导致白屏的情况。

建议移动端下,实际渲染尺寸不大于 2560px。

注册解码器

对于“用户与页面交互之后才可以使用 Video 标签进行视频播放”规则的限制,PAG Web 版提供软件解码器注入接口 PAG.registerSoftwareDecoderFactory()。

注入软件解码器后,PAG 会调度软件解码器去对 BMP 预合成进行解码与上屏,从而实现部分平台进入页面自动播放的功能。

推荐解码器接入:https://github.com/libpag/ffavc/tree/main/web

已知“用户与页面交互之后才可以使用 Video 标签进行视频播放”限制的平台有:移动端微信浏览器,iPhone 省电模式,部分 Android 浏览器。

操作动效

播放

pagView.play();

暂停

pagView.pause();

停止

pagView.stop();

销毁

pagView.destroy();

Web 自适应说明

填充模式

当 PAGView(PAGSurface)和 PAGFile 的尺寸不一致时,会使用填充模式进行适应,默认是 LetterBox 模式。你可以在 PAG 填充模式 章节中找到更多信息。

填充模式:

  • None:不缩放,左上角位置开始裁剪;
  • LetterBox:黑边,在保持高宽比的情况下缩放到设备的可用屏幕大小,图像不发生变形,如果图片尺寸和填充区域比例不一致,会出现黑边,为默认填充模式;
  • Stretch:拉伸,不保持宽高比填充,会发生失变形;
  • Zoom:裁剪,在保持高宽比的情况下缩放到完全填满可用的屏幕大小;

Canvas 尺寸变化

如 高清渲染 章节中所述,PAGView.init() 会默认将 canvas 的宽高设定为 宽高 * dpr,然后使用 style 将其缩放回原尺寸进行展示。

但是,如果以上填充模式无法满足你的需求, 你也可以关闭 PAGView 默认的高清渲染, 手动控制渲染尺寸。

首先,你需要计算 canvas 的尺寸:

const styleDeclaration = window.getComputedStyle(canvas, null);
canvas.width = Number(styleDeclaration.width.replace('px', '')) * window.devicePixelRatio;
canvas.height = Number(styleDeclaration.height.replace('px', '')) * window.devicePixelRatio;

接着,在初始化 PAGView 时,传入 useScale: false 关闭默认的高清渲染:

const pagView = await PAG.PAGView.init(pagFile, canvas, { useScale: false });

最后,当 canvas 展示大小发生变化时,重新计算 canvas 的尺寸,并调用 pagView.updateSize 方法:

window.onresize = () => {
  const styleDeclaration = window.getComputedStyle(canvas, null);
  canvas.width = Number(styleDeclaration.width.replace('px', '')) * window.devicePixelRatio;
  canvas.height = Number(styleDeclaration.height.replace('px', '')) * window.devicePixelRatio;
  pagView.updateSize();
  pagView.flush();
}
← Load PAG FilePlatform Capabilities →
  • 初始化 PAGView
  • 操作动效
  • Web 自适应说明
    • 填充模式
    • Canvas 尺寸变化
Address: Tencent Binhai Building, No. 33 Haitian Second Road, Nanshan District, Shenzhen, Guangdong Province, China.
TEL: 0755-86013388
QQ Group: 893379574
Copyright © 2018 - 2025 Tencent. All Rights Reserved.
Privacy Policy
公司地址:广东省深圳市南山区海天二路33号腾讯滨海大厦
联系电话:0755-86013388
QQ群:893379574
Copyright © 2018 - 2025 Tencent. All Rights Reserved.
隐私政策
Copyright © 2018 - 2025 Tencent. All Rights Reserved.
Address: Tencent Binhai Building, No. 33 Haitian Second Road, Nanshan District, Shenzhen, Guangdong Province, China.
TEL: 0755-86013388
QQ Group: 893379574
Privacy Policy
Copyright © 2018 - 2025 Tencent. All Rights Reserved.
公司地址:广东省深圳市南山区海天二路33号腾讯滨海大厦
联系电话:0755-86013388
QQ群:893379574
隐私政策