企业官网建设流程全解析

• 图形学
• 音视频
• 跨平台

导读

本文以ohos/libpag/README.md为骨架，系统讲解 libpag 在 HarmonyOS Next（OpenHarmony）平台上的定位、核心能力、OHPM 集成方式与源码构建流程，并结合作品仓库中ohos/libpag模块的真实源码（ArkTS API、HAR 包配置、原生库导出）进行纵深印证。读完本文，你将掌握如何在自己的 HarmonyOS 应用中通过 OHPM 安装@tencent/libpag、如何用PAGView/PAGViewController播放 PAG 动画并配置播放参数，以及如何从源码构建和调试这个渲染库。

一、libpag 与 PAG 是什么

libpag 是 PAG（Portable Animated Graphics，便携式动画图形）文件的实时渲染库，能够同时渲染矢量动画与位图（光栅）动画，覆盖 iOS、Android、OpenHarmony、macOS、Windows、Linux、Web 等多个平台。

PAG 本身是一种开源的动画记录文件格式。动画设计师可以通过 PAGExporter 插件在 Adobe After Effects 中一键导出.pag文件，并借助 PAGViewer 应用进行预览——PAGExporter 与 PAGViewer 均提供 macOS 与 Windows 版本。按照官方文档说明，PAG 已被微信、手机 QQ、王者荣耀、腾讯视频、QQ 音乐等 40+ 腾讯应用采用，服务数亿用户。

在 HarmonyOS 生态中，libpag 以HAR（HarmonyOS Ability Resource）静态共享包的形式发布，包名为@tencent/libpag，版本 1.0.1。从仓库中的 ohos/libpag/oh-package.json5 可以看到包的元信息：

• main字段指向Index.ets，即对外 API 的统一出口；
• 依赖项为libpag.so（本地原生库，位于src/main/cpp/types/libpag），说明 ArkTS 层通过 NAPI 桥接 C++ 原生渲染内核；
• 许可证为 Apache-2.0。

仓库中 ohos/libpag/CHANGELOG.md 记录了版本演进：v1.0.1 将库类型由动态库改为har（原因：动态库无法正常引入使用），v1.0.0 为初始版本——这解释了为何当前模块以 HAR 形式提供。

二、四大核心优势（官方口径）

以下优势均来自官方文档的明确说明，可作为评估选型的事实依据：

1. 高效文件格式：得益于高度紧凑的二进制格式设计，导出同样动画时 PAG 文件比 JSON 文件解码快约 10 倍、体积小约 50%。位图或音视频素材可内嵌进单个文件，无需附带其他资源，便于分发。
2. 全量 AE 特性支持：PAG 将矢量导出与位图导出技术结合，可把 AE 动画完整导出到单个文件，连第三方插件特效也能一并导出，而不像部分方案只支持有限的矢量特性。
3. 可量化的性能：PAGViewer 内置性能监控面板，可展示 PAG 文件的归一化性能数据，让设计师不依赖开发也能自查与优化性能；配合 PAGExporter 插件内置的数十种自动优化手段，兼顾视觉效果与性能。
4. 运行时可编辑动画：通过 PAG SDK 灵活的编辑 API，开发者可在运行时修改单个 PAG 文件的图层结构、将多个 PAG 文件混合成一个合成、替换文本与图片并保留所有预置动画效果，大幅降低视频模板类产品的开发工作量。

三、系统要求

在 HarmonyOS 上使用 libpag 的硬性前提：

• HarmonyOS Next 5.0.0(12) 或更高版本。

仓库中 ohos/libpag/src/main/module.json5 进一步印证了包的分发形态与运行环境：

• type为har；
• 支持的设备类型为phone（手机）、tablet（平板）、2in1（二合一设备）；
• 声明了ohos.permission.INTERNET权限（用途场景绑定在PAGFile上、使用时授权），这与 PAGView 支持加载网络路径文件的异步接口相呼应。

四、快速开始：在 HarmonyOS 应用中集成

官方文档提供了两种安装方式，以下逐一说明。

方式一：通过 OHPM 安装

在项目根目录执行：

ohpm install @tencent/libpag

OHPM（OpenHarmony Package Manager）会自动解析并安装@tencent/libpag及其依赖。

方式二：手动声明依赖

在应用模块的oh-package.json5中手动添加依赖项：

"dependencies": { "@tencent/libpag": "^1.0.1", }

然后执行安装命令：

ohpm install

也可使用发布包

你还可以直接使用从 release 页面下载的 har 包，将其引入工程后使用。

五、ArkTS 层 API 一览与典型播放流程

安装完成后，@tencent/libpag的对外接口统一由 ohos/libpag/Index.ets 导出，主要类型包括：

• 视图与控制器：PAGView、PAGViewV2、PAGViewController、PAGImageView、PAGImageViewV2、PAGImageViewController
• 播放核心：PAGPlayer、PAGSurface、PAG
• 数据模型：PAGFile、PAGComposition、PAGLayer（含PAGLayerType）、PAGImage、PAGImageLayer、PAGShapeLayer、PAGSolidLayer、PAGTextLayer、PAGMarker、PAGVideoRange、PAGText
• 能力与工具：PAGFont、PAGDiskCache

其中PAGView是声明式 ArkUI 组件，从源码 ohos/libpag/src/main/ets/PAGView.ets 可见，其本质是对XComponent（type: XComponentType.SURFACE、libraryname: "pag"）的封装：组件加载完成后回调controller.update()，并通过onVisibleAreaChange监听可视区域变化，按可视比例把显隐状态同步给原生层，从而在列表快速滚动等场景下自动停止离屏渲染、节省电量。

一个典型的最小使用流程（基于PAGViewController的公开方法，见 ohos/libpag/src/main/ets/PAGViewController.ets）：

1. 创建PAGViewController，与PAGView组件绑定（aboutToAppear时attachToView）；
2. 用setPath(path)从本地路径加载 PAG 文件（文件不存在或数据非法时返回false），或用setPathAsync(path)异步加载本地/网络路径文件（返回Promise<PAGFile | null>）；也可用setComposition(composition)直接设置合成对象；
3. 调用play()开始播放，pause()暂停，setRepeatCount(n)设置播放次数（0 或负数表示无限循环，默认 1 次）；
4. 通过PAGViewListener接口（onAnimationStart/onAnimationEnd/onAnimationRepeat/onAnimationCancel/onAnimationUpdate）监听动画生命周期，调用addListener/removeListener管理监听器。

PAGViewController还提供了一组对实际业务非常有用的配置方法（默认值均来自源码注释）：

此外，PAGView还提供了getBounds(layer)获取图层在视图坐标系下的像素显示区域，便于做点击热区与精准交互。原生层符号通过 ohos/libpag/export.def 以*pag*全局导出，确保 NAPI 桥接符号在动态链接时可见。

六、从源码构建 libpag

如果你想深入内核或参与开发，官方建议在macOS 平台使用 CLion IDE进行开发构建。

分支管理约定

• main分支是活跃开发分支，包含最新特性与修复；
• release/下的分支是经过完整测试的稳定里程碑分支，会周期性从main切出；切出后仅合入高优先级修复。

注意：当前仓库仅包含PAG 4.0 之后的最新代码；如需使用旧版 PAG 3.0，请从 release 页面下载预编译库。

构建前置工具链

官方要求的最低版本如下：

• Xcode 13.0+
• GCC 9.0+
• Visual Studio 2019+
• NodeJS 14.14.0+
• Ninja 1.9.0+
• CMake 3.13.0+
• QT 6.2.0+
• Emscripten 3.1.58+

第三方依赖管理（depsync）

libpag 使用 depsync 工具管理第三方依赖：

macOS 平台：在项目根目录直接运行脚本，脚本会自动安装必要工具并同步所有第三方仓库：

./sync_deps.sh

其他平台：先安装最新版 Node.js（可能需要重启电脑），再全局安装 depsync：

npm install -g depsync

然后在项目根目录运行：

depsync

同步过程中可能需要 Git 账号与密码；请预先开启git-credential-store，以便后续CMakeLists.txt自动触发同步。

用 CLion 构建

同步完成后，用 CLion 打开项目并构建 pag 库：

• macOS：无需额外 CLion 配置；
• Windows：需确保已安装 VS2019 的 [Desktop development with C++] 与 [Universal Windows Platform development] 两个组件；然后在File -> Setting -> Build, Execution, Deployment -> ToolChains中将 CLion 工具链设置为Visual Studio，架构选amd64（推荐）或x86。

如果 cmake 构建过程出错，请将 cmake 命令行工具升级到最新版本后重试。

七、许可与贡献

libpag 采用 Apache Version 2.0 许可，详见仓库根目录的 LICENSE.txt。需要说明的是，本仓库中腾讯代码的版权声明此前以 "THL A29 Limited" 名义登记，该实体现已注销，所有既往分发副本应视为以 "Tencent" 名义持有版权。

使用 libpag SDK 时请遵守 PAG SDK 的个人信息处理规则（隐私政策）。如有改进建议，欢迎提交 issue / pull request，提交前请先阅读 CONTRIBUTING.md。

结语

通过本文可以看到，libpag 在 HarmonyOS Next 上以 HAR 包形态提供了从 PAG 文件加载、播放控制到图层编辑、性能调优的一整套 ArkTS API，底层则由libpag.so原生内核支撑。无论是直接ohpm install @tencent/libpag快速接入，还是拉取源码用 CLion 自行构建，你都能在 OpenHarmony 设备上稳定渲染出 AE 制作的 PAG 动画，并将文本替换、图像替换、多文件合成等运行时编辑能力直接落地到自己的产品中。

• 图形学
• 音视频
• 跨平台