建立自訂 HTML5 組件

搜尋

上次更新時間 2023年5月24日

Animate

開啟應用程式

Adobe Animate 使用手冊

Animate 簡介

動畫

互動

工作區和工作流程

多媒體和視訊

平台

匯出與發佈

疑難排解

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

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

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

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

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

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

• Windows：

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

• MAC：

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

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

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

組件中繼資料

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

Components.js

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

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

名稱	必要	說明
ClassName	是	Class 來源檔案中指定之組件的名稱。類別名稱支援一個命名空間層級，例如 Video。
Version	否	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 中設定那些屬性，而所設定的屬性會在組件實體化期間，於執行階段提供使用。每個屬性項目都會包含下列索引鍵： name：PI 中所顯示、這個屬性的名稱。這應為易於了解的名稱，可以當地語系化。 variable：這個屬性所使用的內部名稱。設定的值將會在執行階段與這個變數名稱一起提供使用。稍後的章節將會提供更多詳細資料。 Type：這指定了屬性的類型。Animate 允許下列類型： Boolean - PI 中的核取方塊 Number - PI 中的數字方塊 String - PI 中的文字方塊 List - 允許使用者設定值的陣列。 Collection - 允許使用者設定 <索引鍵, 值> 配對的清單。(請見下拉式清單方塊) File Path - 允許使用者瀏覽並選取任何本機檔案。字串值會在執行階段提供。檔案會自動複製在 assets 資料夾的已發佈輸出中，並且相對路徑會在執行階段提供使用。 Image Path - 允許使用者瀏覽並選取任何影像。檔案會自動複製在所設定影像資料夾的已發佈輸出中，並且相對路徑會在執行階段提供使用。 Video Content Path – 允許使用者瀏覽並選取任何網頁格式視訊來源 (mp4、 ogg 、 ogv 、 webm )。所設定的資源會複製到 videos 資料夾的已發佈輸出中。 Color - PI 中的檢色器 Default：屬性的預設值。預設值的類型應與屬性類型相同。

組件來源

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

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

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

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

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 中，您專案中設定的所有組件實體都會實體化，並且附加做為這個 dom_overlay_container div 的子系。組件實體的相對順序會在執行階段進行維護，但目前所有組件實體會一律以重疊的形式顯示。請在執行階段為所有組件實體設定 {pointer-events: all}，好讓組件實體也會收到滑鼠事件。

組件週期

為容器建構 DOM 時，會建立組件實體。
當播放磁頭到達使用組件實體的影格時，實體會附加到 DOM。然後，在執行階段附加每個刻度上呼叫的更新處理常式。此時，組件也會以父元素上的下列事件資料 {id: id_of_the_instance} 觸發事件 attached。
每次更新回呼都會更新屬性。刻度處理常式期間會一次快取並套用所有屬性更新。目前，自訂屬性補間動畫不受支援。只會更新如變形和可見度等基本屬性。
當播放磁頭到達移除組件實體的影格時，就會將它從 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 資料夾底下的對應資料夾中提供字串。

封裝和散佈自訂的 HTML5 組件

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

必要條件

開發人員建立的任何組件。按一下這裡以取得有關建立組件的指示。
CC 擴充功能簽署工具包。

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

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

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

封裝組件

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

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

下載

取得檔案
下載範例 abc.mxi 檔案。
在資料夾中增加您的 MXI 組件檔案和另 2 個關聯的檔案。
使用 CC 擴充功能簽署工具 (ZXPSignCmd.exe) 建立 ZXP 副檔名的 zip 檔案。在 ZXP Sign Command 工具中使用下列命令，即可建立 ZXP 檔案：

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

如果您已有憑證，可以跳過此步驟。
ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
```
ZXPSignCmd -selfSignedCert US NY MyCompany MyCommonName password FileName.p12
```
FileName.p12 檔案隨即在目前資料夾中產生。

2. 使用下列命令簽署擴充功能：
ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
```
ZXPSignCmd -sign projectName projectName.zxp FileName.p12 password
```
projectName 是擴充功能專案的名稱。在目前資料夾中，隨即產生名為 projectName.zxp 的檔案。