Mugeda API的整体结构

Mugeda API整体上分为三个层次:mugeda对象、scene对象、aObject。

每个mugeda对象与单个动画对应,是访问单个动画的入口。通过访问mugeda对象,可以得到mugeda的总体信息。如:大小、标题。动画中,每个时间轴对应于scene对象,主舞台和元件实例都有对应的scene对象。通过操作scene,可以获取事件轴的信息,对播放位置做跳转。每个动画物体和aObject对象相对应,控制aObject,就可以控制物体的位置、透明度、可见性。


mugeda对象

mugeda对象是整个API的最顶层命名空间


mugeda对象的获取

在脚本编辑器中,mugeda对象已经注入,可以直接在代码中写mugeda使用。

如果将动画嵌入网页,按照动画加载前和动画加载后,获取mugeda对象的方式不一样。

1.动画加载前
如果需要在动画加载前获取mugeda对象,可以通过在动画所在的document上设置侦听的方式获取。

document.addEventListener('mugedaReady', function(){
var mugeda = window['Mugeda']['currentAni'];
});

如果网页中嵌入了多个动画,每个动画都会引发上面的回调函数。

2.动画加载后
如果需要在动画加载后获取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直接嵌入网页中。

1.静态载入
在每个动画导出包中,都包含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>


2.动态插入
在不允许直接修改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对象的事件

mugeda对象包含动画加载过程中的事件,如下代码所示:

var mugeda = window["Mugeda"]["currentAni"];
    mugeda.addEventListener("scriptready", function(){
    // 当动画脚本加载完成后引发回调,this指向mugeda对象(下同)。
});


mugeda.addEventListener("imageready", function(){
    // 当动画预加载图片完成后引发回调。
});

mugeda.addEventListener("renderready", function(){
    // 当动画准备完成,开始播放前的那一刻引发回调。
});

mugeda.addEventListener("click", function(){
    // 在舞台上侦听点击事件
});

其他话题:动画在显示加载界面时,到底在加载什么?

动画需要加载必要的文件后才可以正常播放:
1.js文件:在脚本窗口中输入的脚本、通过“导入”,“脚本”对话框加入的脚本,播放器的依赖文件的脚本。

2.图片:需要预先加载一部分图片(目前是预先加载第一页的图片),以免渲染开始动画时,图片没有加载而出现空白画面。
加载时,图片和脚本并行加载。当所有脚本加载完成,在mugeda对象上引发scriptready事件,此时,可以访问到所有的脚本;当所有图片加载完成后,引发imageready事件。当两个时间都引发后,引发renderready事件。


mugeda对象的属性

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对象。通过操作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对象的属性

scene对象包含了主舞台和元件实例时间轴和播放进度的信息。

1.获取当前播放位置和状态

// 获取当前播放的帧号
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)。

2.获取时间轴的信息
可以通过下面的代码,获取时间轴的长度和页的信息:

// 对主舞台
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;
});

3.获取命名帧的实际帧号
在IDE中,可以为关键帧命名,从而在行为中方便的跳转到命名帧。下面函数提供了命名帧到实际帧号的转换。

mugeda.addEventListener("renderready", function(){
    var scene = mugeda.scene;
    // 获取名字为“开始录音”的帧的帧号
    console.log(scene.getFrameidByName("开始录音"));
});

scene的事件

当主舞台或者元件实例重绘前,引发enterframe事件。在事件的回调中,可以操作动画,改变物体的位置,或调整将动画重定向到其他帧。

mugeda.addEventListener("renderready", function(){
    var scene = mugeda.scene;
    scene.addEventListener("enterframe", function(){
        // 打出当前播放的帧号,this -&gt; 当前的scene对象
        console.log(scene.currentId);
    });
});

scene的方法

scene包含系列控制播放进程的方法,此外,scene代表舞台或者元件实例,管理着舞台或元件实例容器中的所有子物体。

1.控制播放进程
在主舞台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。

三个参数可以省略一个或多个。

2.播放片段
可以通过代码,将一小段时间轴标记为片段,将动画的播放范围限定在片段中。如下:

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");
});

3.物体遍历
舞台和元件作为容器,包含一系列的动画元素。在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;

4.增删物体

mugeda.addEventListener("renderready", function(){
    var scene = mugeda.scene;
    // 为元件1创建新的实例,并增加到主舞台
    var aObject = mugeda.createInstanceOfSymbol("元件1");
    scene.appendChild(aObject);

    // 删除刚刚加入的物体
    scene.removeChild(aObject);
});

aObject对象

aObject对象是舞台上动画元素(例如:图片、文字、组、元件实例)的抽象,每一个动画元素,都有对应的aObject对象。


获取aObject对象

1.获取动画中,已有物体的aObject对象

在IDE中,可以在属性面板中为物体命名。同一个scene对象中(主舞台或元件实例),物体的名称是唯一的。要获取命名物体的aObject对象,可以在包含命名物体的scene上:

var aObject = scene.getObjectByName("命名物体的名字");

2.复制已有的aObject对象
动画元素可以被复制:

var aObjectCloned = aObject.clone();

3.使用元件产生元件实例:

var aObjectSymbol = mugeda.createInstanceOfSymbol("元件1");

aObject对象的属性

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 // 获取物体的真实可见性

其他话题:物体的变换过程是这样的?
变换过程是这样的:
对于一个物体,在没有做任何变换的情况下,处于舞台/元件坐标系的左上角(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的事件

可以在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);

观看本节视频教程:
http://cdn1.mugeda.com/course/3/3.9/3.9.1.mp4