SVGA使用手册

SVGA动画播放

一、SVAG介绍

​ SVGA 是一种跨平台的开源动画格式，同时兼容 iOS / Android / Web。SVGA 除了使用简单，性能卓越，同时让动画开发分工明确，各自专注各自的领域，大大减少动画交互的沟通成本，提升开发效率。动画设计师专注动画设计，通过工具输出 svga 动画文件，提供给开发工程师在集成 svga player 之后直接使用。动画开发从未如此简单！SVGA 除了使用简单，性能卓越，同时让动画开发分工明确，各自专注各自的领域，大大减少动画交互的沟通成本，提升开发效率。

二、安装

• cdn引用

  <script src="https://cdn.jsdelivr.net/npm/svgaplayerweb@2.0.7/build/svga.min.js"></script>
  

• npm安装

  npm install svgaplayerweb --save
  // 添加 const SVGA = require('svgaplayerweb'); 或 import SVGA from 'svgaplayerweb'; 至 xxx.js
  

• 直接下载svga.min.js文件：https://github.com/svga/SVGAPlayer-Web

三、使用指南

1. 手动加载： 自行创建Player和Parser并加载动画

   // 1、添加div容器
   <div id="demoCanvas" style="styles..."></div>
   // 2、加载动画
   var player = new SVGA.Player('#demoCanvas');
   var parser = new SVGA.Parser('#demoCanvas'); // 如果你需要支持 IE6+，那么必须把同样的选择器传给 Parser。
   parser.load('svga文件路径', function(videoItem) {
    	// 创建动画   
       player.setVideoItem(videoItem);
    	// 开始动画 后面api会讲到   
       player.startAnimation();
   })
   

2. 自动加载： 为vanvas元素添加src属性，动画会在页面加载完成后播放

   <div src="rose_2.0.0.svga" id="demoCanvas" style="styles..."></div>
   new SVGA.autoload(document.querySelector('#demoCanvas'))
   
   // 动态替换图片
   player.setImage('图片路径', 'ImageKey');
   

3. 动态文本： 在指定元素上添加文本，获取 ImageKey。

   // 注意setText操作必须在startAnimation之前执行
   // player.setText('Hello, World!', 'ImageKey');
   player.setText({ 
       text: 'Hello, World!, 
       family: 'Arial',
       size: "24px", 
       color: "#ffe0a4",
       offset: {x: 0.0, y: 0.0}
   }, 'ImageKey'); // 可自定义文本样式
   

四、基本实例

​ 博主所遇到的业务需求是：

1. 有多张svga图片，通过选项卡效果控制图片展示；
2. 当没有点击切换时，当前svga动画播放完毕后，自动播放下一个，选项卡也跟着变化；
3. 需要注意点： 点击切换选项卡时，必须要把上一个的动画清除，否则会破坏当前动画播放时间；

实例：

​ 页面结构

<!-- 项目是由uniapp写的，所以用到了单向数据绑定，点击事件绑定 -->
<div :class="indexActive == 0 ? 'active': ''"  @tap="cateTap(0)">动画一</div>
<div :class="indexActive == 1 ? 'active': ''"  @tap="cateTap(1)">动画二</div>
<div :class="indexActive == 2 ? 'active': ''"  @tap="cateTap(2)">动画三</div>
<div :class="indexActive == 3 ? 'active': ''"  @tap="cateTap(3)">动画四</div>
<div id="demoCanvas" class="demoCanvas"></div>

​ 逻辑部分

// 引入SVGA对象
const SVGA = require('svga.min.js');	
export default {
		data() {
			return {
				indexActive: 0,
				player: null,
				parser: null
			}
		},
		onReady() {
            // 创建SVGA播放器和解析器
			this.parser = new SVGA.Parser('#demoCanvas');
			this.player = new SVGA.Player('#demoCanvas');
            // 页面加载时自动调用
			this.cateTap(0);
		},
		methods: {
			cateTap: function(index) {
                // 存储this对象
				let self = this;
				self.indexActive = index;
				self.player.clearsAfterStop = true;
				let svgaName = 'static/svga' + index + '.svga';
				self.parser.load(svgaName, function(videoItem) {
                    // 清除上一次动画播放
					self.player.clear();
					self.player.loops = 1;
					// 设置视频对象
					self.player.setVideoItem(videoItem);
					// 开始加载动画
					self.player.startAnimation();
					self.player.onFinished(function() {
                        // 动画加载完之后的回调
						if(self.selected == 3){
							self.cateTap(0);
						} else {
							self.cateTap(++self.indexActive);
						}
					});
				})
			}
		}
	}

​

五、SVGA的属性和方法

1. SVGA播放器： SVGA.Player 用于控制动画的播放和停止

2. Player属性：

   • loops; 动画循环次数，默认值为 0，表示无限循环。
   • clearsAfterStop; 默认值为 true，表示当动画结束时，清空画布。
   • fillMode; 可选值 Forward / Backward（默认），当 clearsAfterStop 为 false 时，Forward 表示动画会在结束后停留在最后一帧，Backward 则会在动画结束后停留在第一帧。

3. Player方法：

   • constructor (canvas); 传入 #id 或者 CanvasHTMLElement 至第一个参数
   • startAnimation(reverse: boolean = false); 从第 0 帧开始播放动画
   • startAnimationWithRange(range: {location: number, length: number}, reverse: boolean = false); 播放 [location, location+length] 指定区间帧动画
   • pauseAnimation(); 暂停在当前帧
   • stopAnimation(); 停止播放动画，如果 clearsAfterStop === true，将会清空画布
   • setContentMode(mode: “Fill” | “AspectFill” | “AspectFit”); 设置动画的拉伸模式
   • setClipsToBounds(clipsToBounds: boolean); 如果超出盒子边界，将会进行裁剪
   • clear(); 强制清空画布
   • stepToFrame(frame: int, andPlay: Boolean); 跳到指定帧，如果 andPlay === true，则在指定帧开始播放动画
   • stepToPercentage(percentage: float, andPlay: Boolean); - 跳到指定百分比，如果 andPlay === true，则在指定百分比开始播放动画
   • setImage(image: string, forKey: string, transform: [a, b, c, d, tx, ty]); 设定动态图像, transform 是可选的, transform 用于变换替换图片
   • setText(text: string | {text: string, family: string, size: string, color: string, offset: {x: float, y: float}}, forKey: string); - 设定动态文本
   • clearDynamicObjects(); 清空所有动态图像和文本

4. Player回调方法（callback Method）：

   • onFinished(callback: () => void): void; - 动画停止播放时回调
   • onFrame(callback: (frame: number): void): void; - 动画播放至某帧后回调
   • onPercentage(callback: (percentage: number): void): void; - 动画播放至某进度后回调

5. SVGA解析器：SVGA.Parser

   • SVGA.Parser 用于加载远端或 Base64 动画，并转换成 VideoItem。
   • 跨域的 SVGA 资源需要使用 CORS 协议才能加载成功。
   • 如果你需要加载 Base64 资源，或者 File 资源，这样传递就可以了 load(File) 或 load('data:svga/2.0;base64,xxxxxx')。

6. Parser方法：

   • constructor();
   • load(url: string, success: (videoItem: VideoEntity) => void, failure: (error: Error) => void): void;

SVGA中文文档说明地址