02集成指南

将播放器集成至 iOS / Android / Web / Flutter / HarmonyOS

以下安装步骤和示例代码整理自各项目官方 README;完整参数、最新版本和变更请以对应仓库为准。

01

CocoaPods · Objective-C

iOS

使用原生 CoreAnimation 渲染,可从应用包或远端服务器加载 SVGA 文件。

安装

在 Podfile 中添加依赖,然后执行 pod install。

安装
Ruby
target 'MyApp' do
  pod 'SVGAPlayer', '~> 2.3'
end

播放

创建 SVGAPlayer 和 SVGAParser,解析完成后赋值 videoItem 并开始播放。

播放
Objective-C
SVGAPlayer *player = [[SVGAPlayer alloc] initWithFrame:CGRectMake(0, 0, 200, 200)];
[self.view addSubview:player];

SVGAParser *parser = [[SVGAParser alloc] init];
[parser parseWithNamed:@"posche" inBundle:nil completionBlock:^(SVGAVideoEntity *videoItem) {
    if (videoItem != nil) {
        player.videoItem = videoItem;
        [player startAnimation];
    }
} failureBlock:nil];

说明

  • 从远端服务器加载时改用 parseWithURL:completionBlock:failureBlock:。
  • 支持动态替换图片、添加文本、隐藏元素和自定义绘制,详见仓库 Wiki。
02

Gradle · JitPack · Kotlin

Android

使用原生 Android Canvas 渲染,可从 assets 或远端服务器加载动画。

安装

在根 build.gradle 添加 JitPack 仓库,在 app/build.gradle 添加依赖。

安装
Gradle
// root build.gradle
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

// app/build.gradle
implementation 'com.github.svga:SVGAPlayer-Android:2.6.1'

播放

在布局中添加 SVGAImageView,指定动画资源并开启自动播放。

播放
XML
<com.opensource.svgaplayer.SVGAImageView
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:source="posche.svga"
    app:autoPlay="true" />

说明

  • 使用 SVGAParser 单例前需调用 SVGAParser.shareParser().init(context)。
  • 混淆时保留 com.squareup.wire.** 与 com.opensource.svgaplayer.proto.**。
  • README 示例中的 compile 为旧版 Gradle 写法,新项目使用 implementation。
03

npm / CDN · JavaScript

Web

功能完整的 Web 播放器,支持 SVGA 1.x(需 JSZip)、音频播放和 IE 兼容模式。

安装

通过 npm 安装,或直接引入 CDN 构建。

安装
Shell
npm install svgaplayerweb --save

<!-- 或直接引入 -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/build/svga.min.js"></script>

播放

准备一个容器,创建 Player 与 Parser,加载动画后播放。

播放
HTML
<div id="demoCanvas"></div>

<script>
  const player = new SVGA.Player('#demoCanvas');
  const parser = new SVGA.Parser('#demoCanvas');
  parser.load('rose.svga', (videoItem) => {
    player.setVideoItem(videoItem);
    player.startAnimation();
  });
</script>

说明

  • 支持 SVGA 1.x 时需额外引入 JSZip;播放音频需引入 howler.js。
  • 需要更小体积时使用 Web Lite。
04

npm / CDN · TypeScript

Web Lite

面向移动端 Web 的轻量播放器,体积小于 60 KB(gzip 小于 18 KB),使用 WebWorker 解析。

安装

通过 npm 安装,或使用 unpkg CDN 构建。

安装
Shell
npm i svga

<!-- 或直接引入 -->
<script src="https://unpkg.com/svga/dist/index.min.js"></script>

播放

创建 Parser 读取动画,挂载到 canvas 后开始播放。

播放
TypeScript
import { Parser, Player } from 'svga'

const parser = new Parser()
const svga = await parser.load('xx.svga')

const player = new Player(document.getElementById('canvas'))
await player.mount(svga)
player.start()

说明

  • 不支持 SVGA 1.x 格式,也不支持播放音频。
  • 兼容 Android 4.4+ / iOS 9+。
05

pub.dev · Dart

Flutter

基于 CustomPainter 的 Flutter 实现,可从本地 assets 或远端服务器加载动画。

安装

在 pubspec.yaml 中添加依赖。

安装
YAML
dependencies:
  svgaplayer_flutter: ^2.0.0

播放

最简单的用法是 SVGASimpleImage;需要精细控制时使用 SVGAAnimationController。

播放
Dart
SVGASimpleImage(
  resUrl: 'https://github.com/svga/SVGA-Samples/blob/master/angel.svga?raw=true',
)

说明

  • 仅支持 SVGA 2.0 格式。
  • 需要自行使用 dio 等库处理资源缓存,并通过 SVGAParser 的字节解码方法处理缓存数据。
06

OHPM · ArkTS

HarmonyOS

面向 HarmonyOS NEXT 的 SVGA 播放器,提供声明式 UI 1.0 / 2.0 组件。

安装

通过 OHPM 安装。

安装
Shell
ohpm install @tb-open/svga

播放

初始化 SVGA,创建控制器并通过 SvgaPlayerV2 渲染动画。

播放
ArkTS
import { Svga, SvgaController, SvgaPlayerV2 } from '@tb-open/svga'

// AbilityStage.onCreate
Svga.init(this.context)

private controller: SvgaController = new SvgaController({
  loops: 3,
  fillMode: 'forwards',
  autoRelease: true,
  clearsAfterStop: true
})

SvgaPlayerV2({
  url: $r('app.media.example_animation'),
  controller: this.controller
})
  .width(300)
  .height(150)

说明

  • 支持应用资源、远程 URL 和沙箱文件路径。
  • 可通过控制器控制播放、替换图片与文本,并监听播放进度和点击事件。