# 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> </div> 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