使用手冊 取消

建立自訂組件:範例

 

請使用本文,了解範例 HTML5 自訂組件。

本文說明如何建立自訂組件。第一個範例說明影像組件 (也隨附於 Animate),以及了解架構的程序和開發過程中牽涉到的步驟。第二個範例說明如何包裝任何現有的 UI 組件 (例如 jQueryUI) 並匯入 Animate 內。

  1. 建立 DOM 影像組件

    建立名為 My Components 的類別。

    a. 首次執行時,在 <HTML5Components> 資料夾底下建立名為 mycomponents 的資料夾。

    b. 下載附加的 myimage.zip 檔案,並將內容解壓縮到

        mycomponents 資料夾之下。

    下載

    c. 重新啟動 Animate。

mycomponents 資料夾內的目錄結構
mycomponents 資料夾內的目錄結構

您現在應該會在組件資料夾中看到名為「My Components」的新類別,並且底下有個新組件,名為「My Image」。您可以將這個組件拖放到舞台上,設定影像來源屬性並發佈影片,以觀察自訂組件實際執行的情形。 

組件中繼資料 - components.js

Components.js 程式碼
Components.js

請注意,類別設定為 CATEGORY_MY_COMPONENTS。每個屬性的名稱也使用類似的索引鍵。這是類別名稱的當地語系化字串。如果您從 locale 資料夾開啟 strings.json,將會看到下列項目。

編輯這個檔案時,最常見的錯誤就是陣列的最後一個元素存在不必要的結尾逗號。

類別詳細資料
類別詳細資料

圖示欄位的值設定為 Sp_Image_Sm。如果移至資源資料夾,您會在底下發現兩個具有前置詞 Sp_Image_Sm 的 png,如下所示。

圖示欄位的值
圖示欄位的值

這些是深色和淺色 UI 的圖示。

components.json 中「source」欄位的值設定為「src/myimage.js」。 

(function($) {
// Register a component with the className: my.Image,
// and prototype with the following overrides
// getCreateOptions
// getCreateString
// getProperties
// getAttributes
$.anwidget(&quot;my.Image&quot;, {
options: {
'visible': true,
'position': 'absolute'
},
_props: [&quot;left&quot;, &quot;top&quot;, &quot;width&quot;, &quot;height&quot;, &quot;position&quot;, &quot;transform-origin&quot;, &quot;transform&quot;],
_attrs: [&quot;id&quot;, &quot;src&quot;, &quot;alt&quot;, &quot;class&quot;, &quot;border&quot;],
// Return a unique ID with the prefix image
// _widgetID is a global declared in anwidget
// This id is used only if the user has not set any instance ID for the component in Animate
// Otherwise the user configured name is used
getCreateOptions: function() {
return $.extend(this.options, { 'id': &quot;image&quot; + _widgetID++ });
},
// Return the string for creating the DOM element
// For image we just need to create the <img> tag
getCreateString: function() {
return &quot;<img>&quot;;
},
// Set of configurable properties
getProperties: function() {
return this._props;
},
// Set of configurable attributes
getAttributes: function() {
return this._attrs;
}
});
})(jQuery);
(function($) { // Register a component with the className: my.Image, // and prototype with the following overrides // getCreateOptions // getCreateString // getProperties // getAttributes $.anwidget(&quot;my.Image&quot;, { options: { 'visible': true, 'position': 'absolute' }, _props: [&quot;left&quot;, &quot;top&quot;, &quot;width&quot;, &quot;height&quot;, &quot;position&quot;, &quot;transform-origin&quot;, &quot;transform&quot;], _attrs: [&quot;id&quot;, &quot;src&quot;, &quot;alt&quot;, &quot;class&quot;, &quot;border&quot;], // Return a unique ID with the prefix image // _widgetID is a global declared in anwidget // This id is used only if the user has not set any instance ID for the component in Animate // Otherwise the user configured name is used getCreateOptions: function() { return $.extend(this.options, { 'id': &quot;image&quot; + _widgetID++ }); }, // Return the string for creating the DOM element // For image we just need to create the <img> tag getCreateString: function() { return &quot;<img>&quot;; }, // Set of configurable properties getProperties: function() { return this._props; }, // Set of configurable attributes getAttributes: function() { return this._attrs; } }); })(jQuery);
(function($) {    

// Register a component with the className: my.Image,
 // and prototype with the following overrides 
 // getCreateOptions
 // getCreateString
 // getProperties
 // getAttributes
    $.anwidget(&quot;my.Image&quot;, {
         options: {
   'visible': true,
   'position': 'absolute'
         },
  _props: [&quot;left&quot;, &quot;top&quot;, &quot;width&quot;, &quot;height&quot;, &quot;position&quot;, &quot;transform-origin&quot;, &quot;transform&quot;],
  
_attrs: [&quot;id&quot;, &quot;src&quot;, &quot;alt&quot;, &quot;class&quot;, &quot;border&quot;],
  
// Return a unique ID with the prefix image
  // _widgetID is a global declared in anwidget
  // This id is used only if the user has not set any instance ID for the component in Animate
  // Otherwise the user configured name is used
  getCreateOptions: function() {
   return $.extend(this.options, { 'id': &quot;image&quot; + _widgetID++ });
  },
  
// Return the string for creating the DOM element
  // For image we just need to create the <img> tag
  getCreateString: function() {
   return &quot;<img>&quot;;
  },
  
// Set of configurable properties
  getProperties: function() {
   return this._props;
  },
  
// Set of configurable attributes
  getAttributes: function() {
   return this._attrs;
  }    
 });   
})(jQuery);

您可以依照程式碼中的註解執行,以便輕鬆地了解程式碼。 

請隨意查看 Animate 所隨附、其他組件的來源。在大多數的情況下,您可以使用其中一個組件當做起點,然後針對自己的需求進行設定。

包裝 jQuery-UI 組件

本節說明如何包裝 jQuery-UI Widget 並在 Animate 中使用。相同的概念可以用來包裝任何其他 UI 架構中的現有組件。

請了解 Animate 內已包裝的 DatePicker 組件,此組件為 jQuery-UI Widget。請下載並解壓縮下列封存的內容,做為參考之用。

下載

解壓縮的內容結構
解壓縮的內容結構

名為 jquery-ui-1.12.0 的資料夾是 jQuery UI 架構的來源,其中包含原始 DatePicker Widget 及其他資源,例如影像和 css,可像任何其他 HTML5 組件一樣,包裝這些項目並用在 Animate 中。僅為本機預覽所需,當您在「發佈設定」中使用「裝載的元件庫」時,可以選擇使用 cdn 來下載相關來源。 

Components.js 程式碼
Components.js

預設有兩個相依項,jQuery 和 anwidget.js。由於 anwidget.js 不在 CDN 上,因此,我們也沒有任何 CDN 項目。

下一個項目集可用於從 jquery UI 載入 datepicker Widget 所需的其他資源。如果您要從任何其他元件庫包裝任何 Widget,可以同樣方式指定相依項集。組件初始化之前,就會先下載這些相依項。

在屬性區段中,我們只公開過一個名為 label 的屬性,這是繫結至日期選取器組件的 label 屬性。同樣地,我們也可以公開其他希望使用者能在 Animate 編寫環境中設定的屬性。在執行階段,這些屬性都能當做索引鍵值配對,在實體的 options 陣列中使用。我們可以擷取設定的值,然後在執行階段套用該值。

主要來源檔案:src/datepicker.js。
主要來源檔案:src/datepicker.js。

不同於範例的區段

  1. getCreateString:

    jQuery-UI 中的日期選取器 Widget 會取得這類輸入文字元素,然後在執行階段轉換成日期選取器元素。因此,我們會跟著初始化 DOM。

  2. attach:

    我們必須覆寫這個 Widget 的這個功能。每當元素附加到 DOM 時,都會呼叫這個 API。然而,由於基礎執行階段 (在這個案例中為 createjs) 運作方式的緣故,在影格範圍期間可能會多次呼叫這個 API。

    請記住基礎元素的附加狀態,然後呼叫基底類別的 attach API (使用 this._superApply(arguments))。若是第一次將元素附加到父輩 DOM,請使用基礎 jQuery-UI Widget 的呼叫,將組件的 DOM 轉換成日期選取器。請參閱 - https://jqueryui.com/datepicker/

    大多數的 javascript Widget 都以類似的方式運作。您可以使用相同的技術來包裝所選的任何組件,並以相同方式帶入 Animate

  3. Update:我們會覆寫更新並將 css 屬性套用到容器 div,然後將特質套用到實際的 DOM 元素。

    當您覆寫 attach、detach 或 update 等 API 時,請評估基底類別的預設實作,並適時呼叫基底實作,否則,組件初始化可能會失敗。

更快、更輕鬆地獲得協助

新的使用者?