MugedaAPI整体结构 · Mugeda百科全书——专业版图文介绍

# MugedaAPI的整体结构 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 -> 当前的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