請使用本文,了解如何為 HTML5 Canvas 建立自訂組件。

Animate CC 隨附預設組件集。然而,這些對您的專案來說,是不夠的。這個主題會協助您了解如何建立適用於 Animate CC 的自訂 HTML5 組件。

組件定義包含下列三個主要部分:

  • 中繼資料:提供有關顯示名稱、版本、可設定的屬性集、圖示等組件的資訊。這會擷取在名為 components.js 的檔案中。您可以將組件群組為類別,這個檔案可讓您為類別中的所有組件提供中繼資料。
  • 來源:提供有關實際組件來源的資訊。當您預覽或發佈使用組件的影片時,這會在執行階段嵌入。
  • 資源:提供有關如 JavaScript 元件庫或 CSS 等任何執行階段相依項,或是執行階段資源和圖示的資訊。資源可以在 Animate 編寫環境中使用。

註解:

此外,組件定義也具有與當地語系化相關的資源。

componentsJS
自訂組件類別的範例資料夾設定

Animate CC 會檢查下列資料夾是否存在任何自訂 HTML5 組件,並在啟動時載入組件:

• Windows:

<AppData>/Local/Adobe/Adobe Animate CC 2017/en_US/Configuration/HTML5Components

 

• MAC:

 

~/Library/Application Support/Adobe/Animate CC 2017/en_US/Configuration/HTML5Components/

註解:

上述資料夾路徑適用於美國英文。如果您使用任何其他語言的 Animate,請尋找您的語言特定資料夾名稱,取代 en_US。

對於包含檔案 components.js 的位置內的每個資料夾,Animate CC 會建立類別,並載入其中的所有組件。

組件中繼資料

組件的中繼資料會擷取在名為 components.js 的檔案,該檔案位於 HTML5Components 目錄的個別資料夾中。

metadata-code
視訊組件的範例中繼資料。

Components.js

Components.js

是包含下列區段的 JSON 檔案:

  • 類別:這個組件集在「組件」面板中的名稱,可以當地語系化。
  • 組件:其中每個項目包含組件中繼資料的陣列。上面範例的陣列只有一個元素。中繼資料具有下列區段:

名稱

必要

說明

ClassName

來源檔案中指定之組件的類別名稱。類別名稱支援一個命名空間層級,例如 Video。

 

Version

組件的版本號碼。這可做為未來組件升級之用。不過,目前並未定義流程。

Source

組件主要來源檔案的相對路徑。下一章節提供更多有關來源包含哪些項目的詳細資料。

Icon

組件圖示的相對路徑。在建立組件 (連同其名稱) 的任何實體時,這個圖示可在組件面板和舞台上使用。若什麼也沒有提供,將會使用預設圖示。

您可以指定要載入之圖示的 png 名稱 (通常為 32x32)。或者,如果您要支援淺色 UI 和深色 UI 的不同圖示,請以下列命名慣例提供兩個 .png。

 

custom_icon_N.png – 深色 UI 的圖示

custom_icon_D.png – 淺色 UI 的圖示

 

然後,只指定名稱「custom_icon」做為這個欄位的值。根據目前的使用者設定,將會自動附加字尾。

Dimensions

組件實體的預設大小。每當使用者將「組件」面板中的組件拖放到舞台時,就會建立新的實體。這個欄位會指定組件實體的預設初始大小。值應為陣列 [寬度, 高度]。若未指定值,則 Animate 會選擇預設大小。此外,Animate 會限制大小必須在 [2,2] 到 [1000, 1000] 範圍內。

Dependencies

組件的相依項集。這是陣列,其中每個項目會提供本機來源的相對路徑 (索引鍵 = “src”) 和 CDN 路徑 (索引鍵 = ’cdn’)。CDN 路徑並非強制性。當您在發佈設定中使用裝載的元件庫時,就會使用這個路徑。否則,當您預覽或發佈時,將會使用本機來源。

 

請記下上面範例 (video) 中使用的相對路徑。它會從上一個層級載入相依項,這讓我們可以在多個組件集之間共享某些相依項。

 

Properties

這是屬性的陣列。當您在舞台上建立這個組件的任何實體時,這裡設定的屬性集會自動出現在 PI 中。這個組件的使用者可以在 Animate CC 中設定那些屬性,而所設定的屬性會在組件實體化期間,於執行階段提供使用。

 

每個屬性項目都會包含下列索引鍵:

  1. name:PI 中所顯示、這個屬性的名稱。這應為易於了解的名稱,可以當地語系化。
  2. variable:這個屬性所使用的內部名稱。設定的值將會在執行階段與這個變數名稱一起提供使用。稍後的章節將會提供更多詳細資料。
  3. Type:這指定了屬性的類型。Animate CC 允許下列類型:
    1. Boolean - PI 中的核取方塊
    2. Number - PI 中的數字方塊
    3. String - PI 中的文字方塊
    4. List - 允許使用者設定值的陣列。
    5. Collection - 允許使用者設定 <索引鍵, 值> 配對的清單。(請見下拉式清單方塊)
    6. File Path - 允許使用者瀏覽並選取任何本機檔案。字串值會在執行階段提供。檔案會自動複製在 assets 資料夾的已發佈輸出中,並且相對路徑會在執行階段提供使用。
    7. Image Path - 允許使用者瀏覽並選取任何影像。檔案會自動複製在所設定影像資料夾的已發佈輸出中,並且相對路徑會在執行階段提供使用。
    8. Video Content Path – 允許使用者瀏覽並選取任何網頁格式視訊來源 (mp4、ogg、ogv、webm)。所設定的資源會複製到 videos 資料夾的已發佈輸出中。
    9. Color - PI 中的檢色器

4. Default:屬性的預設值。預設值的類型應與屬性類型相同。

組件來源

每個組件都應具有相關聯的來源檔案,以提供程式碼來處理下列作業:

  • 在執行階段使用設定的屬性值集來建立組件實體
  • 分離及附加至 DOM
  • 每個影格中的屬性更新

這裡會提供基底類別,並且檔案 anwidget.js 中的公用程式函數將有助於輕鬆地開發自訂組件。這個介面會在未來進行增強,但仍具有回溯相容性。目前僅支援 DOM 架構的組件,不過,對 Canvas 架構組件的支援將會延伸。目前僅支援 Widget,不過,架構將會延伸,以支援附加行為 (非 UI 組件)。

檔案 anwidget.js 位於您首次執行的資料夾中 HTML5Components/sdk 資料夾底下。它提供適用於自訂組件的基底類別 AnWidget ,以及用來登錄自訂組件的公用程式方法 $.anwidget(<className>, {Object Prototype})。目前的實作使用 jQuery,因此,每當您使用 Widget 提供的服務,總是會增加 jQuery 做為相依項。不過,如果您不希望在 jQuery 增加隱含的相依項,您可能必須在沒有 jQuery 提供與 Widget 相同的介面的情況下實作 Component 類別。

 

AnWidget
HTML 範本

html 預設包含下列區段 (排除預先載入程式 div):

animation_container
預設 HTML 區段 (排除預先載入程式 div)

請注意,上面的圖表說明元素增加到 DOM 的順序。因此,dom_overlay_container div 會顯示在畫布上方。

註解:

請勿變更 dom_overlay_container div 的 ID,因為在第一個版本中,有幾個功能需要用到這個 ID,例如程式碼片段。

如先前的圖表所示,dom_overlay_container div 是以重疊的形式顯示在畫布上方。若要確保滑鼠事件也正確地套用到基本畫布,請將 CSS 屬性 {pointer-events: none} 用於這個 div,以便將滑鼠事件套用到基礎畫布。在 Animate CC 中,您專案中設定的所有組件實體都會實體化,並且附加做為這個 dom_overlay_container div 的子系。組件實體的相對順序會在執行階段進行維護,但目前所有組件實體會一律以重疊的形式顯示。請在執行階段為所有組件實體設定 {pointer-events: all},好讓組件實體也會收到滑鼠事件。

組件週期

component_lifecycle
組件週期

  1. 為容器建構 DOM 時,會建立組件實體。

  2. 當播放磁頭到達使用組件實體的影格時,實體會附加到 DOM。然後,在執行階段附加每個刻度上呼叫的更新處理常式。此時,組件也會以父元素上的下列事件資料 {id: id_of_the_instance} 觸發事件 attached

  3. 每次更新回呼都會更新屬性。刻度處理常式期間會一次快取並套用所有屬性更新。目前,自訂屬性補間動畫不受支援。只會更新如變形和可見度等基本屬性。

  4. 當播放磁頭到達移除組件實體的影格時,就會將它從 DOM 拆離。這次,父元素上會觸發 detached 事件。

基底類別名為 $.AnWidget,並且提供下列覆寫:

名稱

強制性

說明

getCreateOptions()

傳回組件實體化期間組件所要套用的任何選項。一般覆寫通常會使用全域變數 _widgetID,藉此用這個來指派唯一 ID 給每個實體。下一章節中的範例會解釋用法。

getCreateString()

傳回用於 DOM 實體建立的字串。這個字串會傳遞至 jQuery,以建立稍後附加到基底 DOM 的實際 DOM 元素。

 

例如,若是影像組件,這個應該會傳回「<image>」。

 

在執行階段會建立元素,並且 jQuery 包裝函式的參考會儲存在組件實體中,如下所示:

 

this._element =  $(this.getCreateElement())

 

// this._element – 所建立基礎 DOM 元素的 jQuery 包裝函式。

 

此外,我們也可以建立複合元素,範例章節將會提供詳細資料。

getProperties()

傳回可設定的 CSS 屬性名稱的陣列。一般來說,這會與您在 components.json 中設定的所有屬性相符

 

例如,若是視訊組件,這個陣列會包含下列項目:

 

["left", "top", "width", "height", "position", "transform-origin", "transform"]

getAttributes()

傳回可設定的 attributes 陣列。一般來說,這會與您允許在 components.json 中設定的所有特質相符

 

例如,若是視訊組件,這個陣列會包含下列項目:

 

["id", "src", "controls", "autoplay", "loop", "class"]

attach(parent)

每當組件實體要附加到「父」DOM 元素時,都會呼叫這個函數。

 

預設實作會執行下列內容 (及一些其他資料):

 

// Appends the element to the parent DOM

$(parent).append(this._element);

 

//Stores the ref in this._$this

this._$this = $(this._element);

 

//Calls force update to apply all properties

this.update(true);

this._attached = true;

 

//Triggers the attached event on parent

$(parent).trigger("attached", this.getEventData("attached"))

 

您不需要覆寫這個函數。不過,若是複合元素,可能必須加以覆寫。範例章節將會提供更多詳細資料。

 

注意:您可以使用 this._superApply(arguments),從任何覆寫呼叫任何基底類別方法。

detach()

每當組件實體要從 DOM 中移除時,都會呼叫這個函數。預設實作會執行下列內容:

 

//Removes the element from the DOM

this._$this.remove();

//Triggers the detached event on parent

$(parent).trigger("detached", this.getEventData("detached"));

setProperty(k,v)

這個函數可用來設定實體的任何屬性。針對每個已變更屬性呼叫 update() 每個影格期間,會一次快取並套用這些變更。

update(force)

當組件是 DOM 的一部分且可見時,每個影格都會呼叫這個函數。預設實作會套用所有已變更 (或 force 參數為 true) 的 CSS 屬性和特質。

show()

顯示元素實體。您通常不需要覆寫這個,但若是複合元素,則必須加以覆寫。

hide()

隱藏元素實體。您通常不需要覆寫這個,但若是複合元素,則必須加以覆寫。

getEventData(e)

針對具有名稱「e」的事件傳回任何自訂資料。預設實作會針對附加事件和拆離事件傳遞資料 {id: instance_id}

destroy()

當組件實體從 DOM 拆離時,釋放記憶體。您通常不需要覆寫這個。

applyProperties(e)

可用來將 CSS 屬性套用到 jQuery 包裝函式 e 的輔助程式 API。

applyAttributes(e)

可用來將特質套用到 jQuery 包裝函式 e 的輔助程式 API。

當地語系化

類別字串、組件顯示名稱和屬性名稱都可以當地語系化。請在組件資料夾底下、具有名稱 locale 的資料夾中建立名為 strings.json 的檔案。針對需要當地語系化的所有字串提供索引鍵值配對,並將索引鍵用於 components.js。對於其他地區,您必須在 locale 資料夾底下的對應資料夾中提供字串。

localization
.json 字串

封裝和散佈自訂的 HTML5 組件

Animate 開發人員或設計人員可以提供立即可用的封裝組件,讓動畫人員能安裝和使用組件,而不需撰寫程式碼。先前,動畫人員必須了解檔案結構、進行程式設計,然後手動將檔案移到特定資料夾,才能啟用 HTML5 擴充功能。

必要條件

封裝您的組件之前,請以來源的中繼資料和組件的目標路徑建立 MXI 檔案。例如:

<file source="jquery-ui-1.12.0" destination="$FLASH\HTML5Components\jQueryUI\" file-type="ordinary" />

必須有這份來源和目標檔案資訊,才能啟用擴充功能公用程式,如此,才能正確地安裝您的組件。

封裝組件

若要封裝 HTML5 自訂組件,請執行下列步驟:

  1. 若要建立 MXI 檔案,請使用文字編輯器輸入類似範例abc.mxi檔案的內容,並以 MXI 副檔名來儲存。

    Download

    下載

  2. 在資料夾中增加您的 MXI 組件檔案和另 2 個關聯的檔案。

    Add-MXI-file-to-component
  3. 使用 CC 擴充功能簽署工具 (ZXPSignCmd.exe) 建立 ZXP 副檔名的 zip 檔案。在 ZXP Sign Command 工具中使用下列命令,即可建立 ZXP 檔案:

    1. 使用 -selfSignedCert 選項建立自我簽署的憑證。

    如果您已有憑證,可以跳過此步驟。

    Self-signature
    ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12

    FileName.p12 檔案隨即在目前資料夾中產生。

    2. 使用下列命令簽署擴充功能:

    Create-ZXP-file
    ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password

    projectName 是擴充功能專案的名稱。在目前資料夾中,隨即產生名為 projectName.zxp 的檔案。

散佈組件

您可以將這個 projectName.zxp 封裝組件檔案散佈給任何 Animate 使用者。

註解:

Adobe 建議您透過 Adobe Add-ons 網站散佈您的產品。您可以公開 (免費或付費) 或私下 (免費提供給指名的使用者) 散佈附加元件。深入了解私下共享產品

安裝散佈的組件

Animate 設計人員或開發人員可以使用「管理擴充功能」公用程式來安裝散佈的 ZXP 檔案組件。

如需詳細資訊,請參閱安裝散佈的組件

此産品由 Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License 授權  Creative Commons 條款未涵蓋 Twitter™ 與 Facebook 文章。

法律說明   |   線上隱私權政策