Mugeda API提供了一组接口,可以通过代码的方式操作动画。常用于制作游戏和带有交互性的动画。使用Mugeda API需要了解javascript。
在IDE中有三种方式,可以使得您的代码和动画进行互动。
在IDE中,点击工具栏上的脚本按钮,在脚本窗口中添加脚本。脚本分为“全局”脚本和“页”脚本。全局脚本是整个动画的脚本,页脚本跟随页面,当页面被复制时,页脚本同样会被复制。
全局脚本和页脚本的运行顺序是:全局脚本→页1脚本→页2脚本……
全局和页脚本间的变量是隔离的,如果需要通讯,可以将变量挂在mugeda
对象上或者window
对象上。例如:
// 在全局脚本中
window.abc = 1;
// 在页1中
alert(window.abc); // 弹出1
在全局脚本中,可以直接使用mugeda
对象。在页脚本中,除了可以直接使用mugeda
对象外,还可以直接使用pageIndex
对象,pageIndex
是一个整数,指示脚本的页号。例如,在页1的脚本中,可以查询到脚本页号:
alert(pageIndex); // 弹出数字0
如果以后调整了页与页之间的顺序,pageIndex会自动变化。
这种方式加入的脚本,如果需要调试,需要区分以下两种方式:
(1)在IDE中,通过点击工具栏上的“预览”按钮预览动画,或扫描IDE中二维码的方式预览动画。此时脚本是通过javascript的new Function的方式在内存中运行。调试一般采用javascript中的console.log
、debugger
方法进行调试。
(2)动画被导出之后,所有脚本会写入导出包中,action
开头的一个js文件中。动画运行时,在浏览器调试台中可以看到这个脚本文件,在其中加断点、调试。
在IDE菜单中,点击“文件”→“导入”→“脚本”,在对话框中,输入脚本文件的url
。url
可以指向服务器上的js文件,或者指向本机的地址。在动画加载时,url
指向的脚本文件会在开始阶段被加载。可以通过浏览器调试这个文件。
另一种方式,是将动画嵌入自己的网页,在网页中直接调用mugeda API来控制动画。
Mugeda API整体上分为三个层次:mugeda对象
、scene对象
、aObject
。
每个mugeda
对象与单个动画对应,是访问单个动画的入口。通过访问mugeda对象
,可以得到mugeda
的总体信息。如:大小、标题。动画中,每个时间轴对应于scene对象
,主舞台和元件实例都有对应的scene对象
。通过操作scene
,可以获取事件轴的信息,对播放位置做跳转。每个动画物体和aObject
对象相对应,控制aObject
,就可以控制物体的位置、透明度、可见性。
mugeda
对象是整个API的最顶层命名空间。
在脚本编辑器中,mugeda
对象已经注入,可以直接在代码中写mugeda
使用。
如果将动画嵌入网页,按照动画加载前和动画加载后,获取mugeda
对象的方式不一样。
如果需要在动画加载前获取mugeda对象,可以通过在动画所在的document
上设置侦听的方式获取。
document.addEventListener('mugedaReady', function(){
var mugeda = window['Mugeda']['currentAni'];
});
如果网页中嵌入了多个动画,每个动画都会引发上面的回调函数。
如果需要在动画加载后获取mugeda
对象,如果网页中只有一个动画,只需要用下面的代码就可以了(注:window
为动画所在的window
)。
var mugeda = window['Mugeda']['currentAni'];
如果页面中包含多个动画,需要用下面的方式遍历找到需要动画的mugeda对象。
window['Mugeda']['animations'].forEach(function(mugeda){
// 此时可以通过mugeda的其他属性,例如mugeda.title找到想要的mugeda对象
});
其他话题:如何将Mugeda动画嵌入自己的网页中?
Mugeda动画除了可以在手机浏览器中全屏播放外,还可以将其作为网页中的一部分,放在自己的网页中。目前,在PC端的
chrome
、firefox
、IE11
等现代浏览器中都能正常播放。可以通过两种方式将动画嵌入网页。
一、
iframe
方式如果您使用的是Mugeda提供的发布功能,得到了发布地址,可以在网页中,直接加入iframe的方式嵌入动画。
<iframe frameborder="0" width="320" height="512" src="发布后的地址"> </iframe>;
如果您是通过导出动画包的方式(zip文件),将文件解压托管到自己的网络空间中,也可以通过上面的方式,将iframe的src属性指向导出包中的index.html文件的地址。
二、直接嵌入方式
有些时候,可能不希望通过iframe加载动画,例如,在早期ios版本中,iframe可能有一些性能或兼容性问题,或者希望拥有更好的可控性,可以将Mugeda直接嵌入网页中。
- 静态载入
在每个动画导出包中,都包含loader.js文件。在html代码中加入以下的片段,指向这个文件。
<div style="width:320px;height:512px;position:relative;">
<script>
window._mrmcp = {
"creative_path": "pa5/", // 指向动画文件夹的位置
"script_id": "box", // 包含动画script元素的id
"render_mode": "embedded"
}
</script>
<script src="pa5/loader.js" id="box"></script>
</div>
- 动态插入
在不允许直接修改html的情况下,可以通过代码的方式,动态的将动画加到网页中。假设网页中存在id为container1和container2的空div:
<div id="container1" style="width:320px;height:512px;position:relative;"></div>
<div id="container2" style="width:320px;height:512px;position:relative;"></div>
// 下面的代码,动态的将2个动画插入这两个空div中。
<script>
var script = document.createElement("script");
script.src = "pa5/loader.js";
script.id = "script1.js";
window._mrmcp = {
"creative_path": "pa5/",
"script_id": "script1",
"render_mode": "embedded"
}
script.onload = function(){
var script = document.createElement("script");
script.src = "pa6/loader.js";
script.id = "script2.js";
window._mrmcp = {
"creative_path": "pa6/",
"script_id": "script2",
"render_mode": "embedded"
}
document.getElementById("container2").appendChild(script);
}
document.getElementById("container1").appendChild(script);
</script>
mugeda对象包含动画加载过程中的事件,如下代码所示:
var mugeda = window["Mugeda"]["currentAni"];
mugeda.addEventListener("scriptready", function(){
// 当动画脚本加载完成后引发回调,this指向mugeda对象(下同)。
});
mugeda.addEventListener("imageready", function(){
// 当动画预加载图片完成后引发回调。
});
mugeda.addEventListener("renderready", function(){
// 当动画准备完成,开始播放前的那一刻引发回调。
});
mugeda.addEventListener("click", function(){
// 在舞台上侦听点击事件
});
其他话题:动画在显示加载界面时,到底在加载什么?
动画需要加载必要的文件后才可以正常播放:
- js文件:在脚本窗口中输入的脚本、通过“导入”,“脚本”对话框加入的脚本,播放器的依赖文件的脚本。
- 图片:需要预先加载一部分图片(目前是预先加载第一页的图片),以免渲染开始动画时,图片没有加载而出现空白画面。
加载时,图片和脚本并行加载。当所有脚本加载完成,在mugeda对象上引发scriptready事件,此时,可以访问到所有的脚本;当所有图片加载完成后,引发imageready事件。当两个时间都引发后,引发renderready事件。
mugeda对象能够获取到一些动画中的全局信息,如下代码所示:
var mugeda = window['Mugeda']['currentAni'];
// 获取当前动画的标题
alert(mugeda.title);
// 获取当前动画的缩放、边距(单位:像素,动画坐标系)。
//
通常情况下,动画为通过等比或非等比的方式充满容器,adaption对象指示了动画
// 充满容器后,距离容器边缘的边距(adaption.marginLeft、
//
adaption.marginRight、adaption.marginTop、adaption.marginBottom),
//
负数代表动画被截取。配合在window上侦听resise事件,可以方便的将物体始终
// 定位在屏幕的边缘。
console.log(mugeda.adaption);
// 获取本次和上次渲染的时间换算成帧号差值(单位:帧)
// 即deltaFrame = (此次渲染的绝对时间 - 上次渲染的绝对时间)/ 帧率
console.log(mugeda.deltaFrame);
// 获取舞台所在的dom对象
console.log(mugeda.dom);
// 获取每一帧的时间(单位:毫秒)
console.log(mugeda.frameTime);
// 获取帧率
console.log(mugeda.rate);
// 获取舞台大小(单位:像素)
console.log(mugeda.width, mugeda.height);
对于主舞台、元件实例这样拥有时间轴的动画元素,都拥有对应的scene对象。通过操作scene对象,可以使用编程的方式,获取当前的播放位置、跳转播放位置、获取主舞台上的物体等操作。
对主舞台,直接通过下面的方式获取:
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
});
对元件实例,首先需要在舞台上对元件实例命名(例如“A”),然后通过下面的方式获取:
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
var symScene = scene.getObjectByName("A").scene;
});
scene对象包含了主舞台和元件实例时间轴和播放进度的信息。
// 获取当前播放的帧号
var currentFrameNumber = scene.currentId;
var currentFrameNumberDecimal = scene.currentDecimalId;
// 获取当前页号(对元件,始终返回0)
var currentPageIndex = scene.currentPageIndex;
// 获取当前播放是否暂停
var isPlaying = scene.playing;
// 获取scene对应的dom元素
var dom = scene.dom;
其中currentId为currentDecimalId的取整值。
其他话题:什么当前播放的帧号可以是小数?
在IDE中,如果将帧率设置为12,意味着可以以0.083秒的精度,编辑物体的变换位置。但在实际动画播放的时候,为增加流畅度,渲染器以尽可能低的时间间隔对屏幕进行重绘,如果重绘的时间间隔小于0.083秒,即小于IDE中设置的一帧的时间间隔,渲染器将对物体的变化插值,计算两帧之间变换的中间位置,将其绘于屏幕上,这个时候就出现了小数帧号。
scene.currentId、scene.currentDecimalId、mugeda.deltaFrame,配合后面介绍的enterframe事件,可以精确的知道动画的播放进度。
其他话题: currentId的取值是怎样的?
currentId的取值从0开始连续增加。和IDE时间轴下面的数字不一样,scene.currentId返回的值比IDE中时间轴下方的数字小1。
当主舞台上含有多个页时,页和页之间的时间轴在数据上是连接在一起的。例如,有两页,每页都有10帧。那么播放到第一页的时候,currentId取值为[0, 10),播放第二页的时候,currentId的取值为[10, 20)。
可以通过下面的代码,获取时间轴的长度和页的信息:
// 对主舞台
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
// 获取页数据
var pages = scene.pages;
// 获取页数
var pageLen = pages.length;
// 获取第一页的开始帧号
var frameIdOfFirstPage = pages[0].startFrame;
// 获取第一页的总帧数
var totalFramesOfFirstPage = pages[0].length;
});
// 对元件A
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
var symScene = scene.getObjectByName("A").scene;
// 获取元件帧数(元件没有页的概念,所有只有pages[0]有效)
var length = symScene.pages[0].length;
});
在IDE中,可以为关键帧命名,从而在行为中方便的跳转到命名帧。下面函数提供了命名帧到实际帧号的转换。
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
// 获取名字为“开始录音”的帧的帧号
console.log(scene.getFrameidByName("开始录音"));
});
当主舞台或者元件实例重绘前,引发enterframe事件。在事件的回调中,可以操作动画,改变物体的位置,或调整将动画重定向到其他帧。
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
scene.addEventListener("enterframe", function(){
// 打出当前播放的帧号,this -> 当前的scene对象
console.log(scene.currentId);
});
});
scene包含系列控制播放进程的方法,此外,scene代表舞台或者元件实例,管理着舞台或元件实例容器中的所有子物体。
在主舞台scene或元件实例scene上使用下面的方法,可以控制他们的播放进程:
scene.pause(); // 暂停
scene.play(); // 继续播放
scene.gotoAndPlay(frame); // 跳转到帧并播放(frame支持帧号或帧名)
scene.gotoAndPause(frame); // 跳转到帧并暂停(frame取值同上)
scene.nextPage(); // 跳转到下一页的开头
scene.prevPage(); // 跳转到上一页的开头
scene.gotoPage(pageIdx); // 跳转到指定页的开头
scene.gotoAndPlay(frame, pageIdx); //
跳转到相对于某页的某帧并继续播放
scene.gotoAndPause(frame, pageIdx); // 跳转到相对于某页的某帧并暂停
其他话题:如何控制在gotoPage被调用时候的翻页效果?
通常情况下,gotoPage的翻页效果,和IDE翻页选项卡中的翻页效果一致。然而,当某些情况下,需要在代码中动态的控制翻页效果时,可以通过下面的代码控制:
scene.gotoPage(pageIdx, options);
options的取值控制翻页效果,形式如下:
var options = {
transition: "", // 过渡效果
exit: "", // 退出效果
duration: 1, // 过渡时间
};
过渡效果的取值为:
ladder(平移)
cover(覆盖)
appear(出现)
fadein(淡入)
box(三维翻转)
flip(门轴翻转)
退出效果的取值为:
none(无)
zoomout(缩小)
fadeout(淡出)
zoomout(放大)
fadeout(缩小淡出)
box(三维翻转)
flip(门轴翻转)
其中,当过渡效果为
box
或flip
时,退出效果只可以是box
或flip
。过渡时间的单位是毫秒,必须大于等于1。
三个参数可以省略一个或多个。
可以通过代码,将一小段时间轴标记为片段,将动画的播放范围限定在片段中。如下:
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
// 将主舞台的第0帧到第15帧标为片段1,循环播放
scene.setSegment("片段1", 0, 15, true);
// 将主舞台的第16帧到第30帧标为片段2,不循环播放
scene.setSegment("片段2", 16, 30, false);
// 播放第二个片段
scene.playSegment("片段2");
});
舞台和元件作为容器,包含一系列的动画元素。在IDE中,可以为物体命名,下面的代码通过名字查找到舞台上的元件实例A中的物体B。
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
var symA = scene.getObjectByName("A");
var symAScene = symA.scene;
var objectB = symAScene.getObjectByName("B");
});
上述例子允许反遍历(由子元素寻找父元素),例如:
symAScene.object === symA;
symAScene.parentScene === scene;
symAscene.thisAni === mugeda;
scene.thisAni === mugeda;
symA.currentScene === scene;
objectB.currentScene === symScene;
mugeda.addEventListener("renderready", function(){
var scene = mugeda.scene;
// 为元件1创建新的实例,并增加到主舞台
var aObject = mugeda.createInstanceOfSymbol("元件1");
scene.appendChild(aObject);
//然后可以将它添加到舞台上
//scene.appendChild(aObject, behaindAObject, pageIndex);
//第二个参数behaindAObject是舞台上某个动画元素,这个参数也可以是null
//第三个参数是页面的编号
// 删除刚刚加入的物体
scene.removeChild(aObject);
});
aObject对象是舞台上动画元素(例如:图片、文字、组、元件实例)的抽象,每一个动画元素,都有对应的aObject对象。
在IDE中,可以在属性面板中为物体命名。同一个scene对象中(主舞台或元件实例),物体的名称是唯一的。要获取命名物体的aObject对象,可以在包含命名物体的scene上:
var aObject = scene.getObjectByName("命名物体的名字");
动画元素可以被复制:
var aObjectCloned = aObject.clone();
//然后可以将它添加到舞台上
//scene.appendChild(aObjectCloned, behaindAObject, pageIndex);
//第二个参数behaindAObject是舞台上某个动画元素,这个参数也可以是null
//第三个参数是页面的编号
var aObjectSymbol = mugeda.createInstanceOfSymbol("元件1");
//如果元件里有一个名为“元素1”的文本,可以配合aObject的api来修改文本值: aObjectSymbol.scene.getObjectByName('元素1').text = '新值'
aObject包含一系列属性控制动画元素的变换:
// 可读写属性
aObject.dom // 获取或改变aObject对应的dom元素
aObject.width // 获取或改变aObject的宽度
aObject.height // 获取或改变aObject的高度
aObject.rotate // 获取或改变aObject的旋转角度(弧度)
aObject.visible // 获取或改变aObject的可见性
aObject.text // 对文本元素,获取或改变aObject对应的文字
aObject.alpha // 获取或改变aObject的透明度
aObject.pers // 获取或改变aObject透视角(角度)
aObject.x // 获取或改变aObject的参考点在舞台/元件空间的横坐标
aObject.left // 获取或改变aObject的左边界在舞台/元件空间的横坐标
aObject.top // 获取或改变aObject的上边界在舞台/元件空间的纵坐标
aObject.rotateCenterX //
获取或改变aObject的参考点相对物体左边界的距离
aObject.scaleX // 获取或改变aObject在横坐标方向上的缩放值
aObject.rotateX //
获取或改变aObject在空间坐标系中沿横轴旋转值(弧度)
aObject.y // 获取或改变aObject的参考点在舞台/元件空间的纵坐标
aObject.right // 获取或改变aObject的右边界在舞台/元件空间的横坐标
aObject.bottom // 获取或改变aObject的下边界在舞台/元件空间的纵坐标
aObject.rotateCenterY //
获取或改变aObject的参考点相对物体上边界的距离
aObject.scaleY // 获取或改变aObject在纵坐标方向上的缩放值
aObject.rotateY //
获取或改变aObject在空间坐标系中沿竖轴旋转值(弧度)
aObject.url // 对于具有动作为“链接”的物体,获取或设置链接目标
// 只读属性
aObject.name // 获取物体的名字
aObject.scene // 对元件实例,获取它的scene对象
aObject.currentScene // 获取物体所在的scene对象
aObject.thisAni // 获取物体所在的mugeda对象
aObject.getRealVisible // 获取物体的真实可见性
aObject.audio // 获取音频元素的audio DOM对象
aObject.video // 首次播放视频后,可获取视频元素的video DOM对象
其他话题:物体的变换过程是这样的?
变换过程是这样的:
对于一个物体,在没有做任何变换的情况下,处于舞台/元件坐标系的左上角
(0,0)
的位置。移动物体,使得物体的参考点处于舞台/元件坐标系的
(aObject.x,aObject.y)
位置,此时。以
(aObject.x,aObject.y)
为中心点,对物体做(aObject.scaleX,aObject.scaleY)
的缩放。此时,物体的大小变为宽为aObject.width
,高为aObject.height
。物体的左、上、右、下边界,分别离舞台/元件坐标系的左上角的距离为aObject.left
、aObject.top
、aObject.right
、aObject.bottom
。以
(aObject.x,aObject.y)
为中心点,沿着空间坐标系的竖轴,做aObject.rotateY
旋转。以
(aObject.x,aObject.y)
为中心点,沿着空间坐标系的横轴,做aObject.rotateX
旋转。以
(aObject.x,aObject.y)
为中心点,沿着空间坐标系垂直屏幕方向,做aObject.rotate
旋转。对物体做视角为
aObject.pers
的透视变换。其他话题:
visible
、时间轴上物体的生命周期、getRealVisible
的关系在IDE中,物体的可见范围,由该物体在时间轴上的生命周期决定。而当
visible
设置为false
时,物体在生命周期范围内也不可见;若visible
设置为true
,则物体在生命周期内可见,在生命周期外不可见。因此,生命周期和
visible
属性共同决定物体是否可见。在生命周期内,visible
属性决定物体是否可见,而在生命周期外,物体永远不可见。对于由
scene.appendChild
加入的物体,由于没有生命周期,只由visible
属性控制其可见性。若要获取一个物体的最终可见性,只需要读取它的
getRealVisible
属性就可以了。其他话题:物体定位时候的坐标系是怎样的?
在Mugeda动画系统中,舞台、元件、组内的物体,都是以物体上上一层舞台、元件实例、组的左上角为定位圆点进行定位。举例来说,如果舞台上,距离坐标原点
(10,10)
的位置放置了元件实例,而双击元件实例,里面的图片距离左上角的距离是(20,20)
,此时读取物体对应aObject
的left
和top
值都为20。
可以在aObject上绑定绝大多数的鼠标/触摸事件:touchstart
、touchmove
、touchend
、mousedown
、mousemove
、mouseup
、click
、dblclick
、mouseover
、blur
、focus
。此外,还提供inputstart
、inputmove
、inputend
三个事件。在PC上,这三个事件对应于mousedown
、mousemove
、mouseup
,在手机和平板上,对应于touchstart
、touchmove
、touchend
事件、click
事件经过处理,已经不会有300ms的延迟问题。使用如下:
aObject.addEventListener("click", function(e){
// this指向aObject
// 提供inputX和inputY属性,获取相对于舞台的坐标值
var x = e.inputX;
var y = e.inputY;
提供e.preventDefault、e.stopPropagation、e.stopImmediatePropagation
e.stopPropagation();
});
其他话题:aObject的dom属性有什么用?
在Mugeda渲染器中,除遮罩以外,其他的动画元素都对应于dom树中的一个dom元素。得到dom元素后,可以采取操作dom元素的方式,是它具有其他行为。
例如,下面的代码,为文本对象对应的dom(是一个div)增加`contentEditable`属性,使得用户可以输入文本对象的内容:
var aObject = scene.getObjectByName("文字对象1");
var dom = aObject.dom;
dom.setAttribute("contentEditable", "true");
下面的例子,是组(名字:textG)中包含一个文本输入框(名字:textA)。通过插入一个textArea,并将原来的文本输入框隐藏,使得原先的文本输入框的位置变成了多行文本输入框:
var text = '<textarea style="position: absolute; left:0; top:0;width:100%; height:100%; outline: none; background: transparent;border-radius: 0; border: 0;"></textarea>';
var node = document.createElement('div');
node.innerHTML = text;
// 把原先的输入框隐藏
mugeda.scene.getObjectByName('textA').visible = false;
// 将textarea加入组中,它为决定定位,宽、高100%,因此能撑满整个组。
mugeda.scene.getObjectByName('textG').dom.appendChild(node.firstChild);
在微信中,经常需要定义微信转发的标题、描述、转发地址。除了在IDE的文档信息中填写这些信息以外,还可以通过代码动态的更改这些值,代码如下:
// 在renderready后
defineWechatParameters({
url_callback: function(){
return "http://www.abc.com/";
},
img_url: "转发缩略图地址",
timelineTitle: "朋友圈的描述",
desc: "转发的描述",
title: "转发的标题"
});
上述函数可以多次调用,每调用一次,用新值覆盖旧值。上述4个参数可以省略1~3个。
Mugeda渲染器提供通用的信息提示函数,代码如下:
Mugine.Utils.Toast.info('提示文字', {type:'toast'});
Mugine.Utils.Toast.info('提示文字', {type:'info'});
通过定义一个函数,可以自定义微信昵称组件的显示文字,如果是在在微信中,函数参数为微信昵称,否则为空。可以返回任何文本值。示例代码如下:
// 格式化微信昵称,只显示前6个字符
window.mugeda_nickname_callback = function(wxNickName) {
return wxNickName ? wxNickName.substring(0,6) : '没有昵称';
}
// 显示其它App登录信息中的昵称
window.mugeda_nickname_callback = function() {
return window.xxxUserInfo.nickName;
}
同自定义昵称,可以自定义微信头像组件中的图片,代码如下:
// 显示其它App登录信息中的头像
window.mugeda_avatar_callback = function() {
return window.xxxUserInfo.avatarUrl;
}
可以把作品中的分享信息注册到其它App分享功能中,和上文中微信转发不同的是,微信转发是为了在微信转发中自定义分享信息,而这个回调函数是为了把作品中的分享信息绑定到其它的分享方式中。
// 使用作品中的分享信息更新特定App内的分享信息
window.mugeda_avatar_callback = function(data) {
// { shareTitle, timelineTitle, desc, link, imgUrl } = data
xxx.updateAppMessageShareData({
title: data.shareTitle,
desc: data.desc,
link: data.link,
imgUrl: data.imgUrl
});
}
可以通过在作品播放前对浏览环境进行检查,然后停止作品的播放,对用户进行提醒或者强制跳转。
// 不支持微信的判断
mugeda.addEventListener('renderready', function(evt) {
if (navigator.userAgent.toLowerCase().indexOf('micromessenger') > -1) {
evt.stopLoad();
alert("不知道微信浏览器,请复制链接到浏览器打开。");
}
});
// 当把作品嵌入App内是,可以判断作品是否是在App内打开的
mugeda.addEventListener('renderready', function(evt) {
if (!xxx || !xxx.isClient()) {
// 停止作品的播放
evt.stopLoad();
alert("请在xxxApp内打开该作品!");
}
});