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