Polymer - 自定義元素

Polymer 是一個允許使用標準 HTML 元素建立自定義元素的框架。自定義 Web 元素提供以下功能：

它提供與類關聯的自定義元素名稱。
當您更改自定義元素例項的狀態時，它將請求生命週期回撥。
如果更改例項上的屬性，則將請求回撥。

您可以使用 ES6 類定義自定義元素，並且類可以與自定義元素關聯，如下面的程式碼所示。

//ElementDemo class is extending the HTMLElement 
class ElementDemo extends HTMLElement { 
   // code here
};

//link the new class with an element name
window.customElements.define('element-demo', ElementDemo);

自定義元素可以用作標準元素，如下所示：

<element-demo></element-demo>

注意 - 自定義元素名稱應以小寫字母開頭，並在名稱之間包含一個短橫線。

自定義元素生命週期

自定義元素生命週期提供一組自定義元素反應，這些反應負責元素生命週期的變化，並在下表中定義。

序號	反應及描述
1	constructor 當您建立元素或定義先前建立的元素時，將呼叫此元素反應。
2	connectedCallback 當您將元素新增到文件時，將呼叫此元素反應。
3	disconnectedCallback 當您從文件中刪除元素時，將呼叫此元素反應。
4	attributeChangedCallback 每當您更改、追加、刪除或替換文件中的元素時，都會呼叫此元素反應。

元素升級

我們可以根據規範在定義自定義元素之前使用它們，並且透過向該元素新增定義，任何現有元素例項都將升級到自定義類。

自定義元素狀態包含以下值：

uncustomized - 有效的自定義元素名稱是內建元素或未知元素，無法成為自定義元素。
undefined - 元素可以具有有效的自定義元素名稱，但無法定義。
custom - 元素可以具有有效的自定義元素名稱，可以定義和升級。
failed - 嘗試升級無效類的失敗元素。

定義元素

可以透過建立一個擴充套件 Polymer.Element 的類來定義自定義元素，並將該類傳遞給 customElements.define 方法。該類包含 is getter 方法，該方法返回自定義元素的 HTML 標籤名稱。例如：

//ElementDemo class is extending the Polymer.Element 
class ElementDemo extends Polymer.Element {
   static get is() { return 'element-demo'; }
   static get properties() {
      . . .
      . . .
   }
   constructor(){
      super();
      . . .
      . . .
   }
   . . .
   . . .
}

//Associate the new class with an element name
window.customElements.define(ElementDemo.is, ElementDemo);

// create an instance with createElement
var el1 = document.createElement('element-demo');

匯入和 API

可以透過指定以下三個 HTML 匯入來定義 Polymer 元素：

polymer-element.html - 它指定 Polymer.Element 基類。
legacy-element.html - 它使用 Polymer.LegacyElement 基類擴充套件 Polymer.Element 並新增 1.x 相容的舊版 API。它還透過定義舊版 Polymer() 工廠方法來建立混合元素。
polymer.html - 它包含 Polymer 基類以及包含在 1.x polymer.html 中的輔助元素。

在主 HTML 文件中定義元素

您可以使用 HTMLImports.whenReady() 函式在主 HTML 文件中定義元素。

示例

以下示例顯示如何在主 HTML 文件中定義元素。建立一個 index.html 檔案並新增以下程式碼。

<!doctype html>
<html lang = "en">
   <head>
      <title>Polymer Example</title>
      <script src = "bower_components/webcomponentsjs/webcomponents-lite.js"></script>
      <link rel = "import" href = "bower_components/polymer/polymer.html">
      <link rel = "import" href = "define-element.html">
   </head>
   
   <body>
      <define-element></define-element>
   </body>
</html>

現在建立一個名為 define-element.html 的自定義元素幷包含以下程式碼。

<dom-module id = "define-element">
   <template>
      <h2>Welcome to Tutorialspoint!!!</h2>
   </template>
   
   <script>
      HTMLImports.whenReady(function(){
         Polymer ({
            is: "define-element"
         })
      })  
   </script>
</dom-module>

輸出

要執行應用程式，請導航到已建立的專案目錄並執行以下命令。

polymer serve

現在開啟瀏覽器並導航到 http://127.0.0.1:8081/。輸出如下所示。

定義舊版元素

舊版元素可用於使用 Polymer 函式註冊元素，該函式採用新元素的原型。原型應包含 is，該原型定義自定義元素的 HTML 標籤名稱。

示例

//registering an element
ElementDemo = Polymer ({
   is: 'element-demo',
   
   //it is a legecy callback, called when the element has been created
   created: function() {
     this.textContent = 'Hello World!!!';
   }
});

//'createElement' is used to create an instance
var myelement1 = document.createElement('element-demo');

//use the constructor create an instance
var myelement2 = new ElementDemo();

生命週期回撥

生命週期回撥用於完成Polymer.Element類的內建功能的任務。Polymer 使用 ready 回撥，該回調將在 Polymer 完成建立和初始化 DOM 元素時呼叫。

以下是 Polymer.js 中舊版回撥的列表。

created - 在設定屬性值和初始化本地 DOM 之前建立元素時呼叫。
ready - 在設定屬性值和初始化本地 DOM 之後建立元素時呼叫。
attached - 將元素附加到文件後呼叫，並且在元素的整個生命週期中可以多次呼叫。
detached - 從文件中分離元素後呼叫，並且在元素的整個生命週期中可以多次呼叫。
attributeChanged - 當元素的屬性發生更改時呼叫，它儲存與宣告的屬性不相容的屬性更改。

宣告屬性

可以在元素上宣告屬性以新增預設值和其他特定功能到資料系統中，並且可以使用它們來指定以下功能：

它指定屬性型別和預設值。
當屬性值發生更改時，它呼叫觀察者方法。
它指定只讀狀態以阻止對屬性值的意外更改。
它支援雙向資料繫結，當您更改屬性值時會觸發事件。
它是一個計算屬性，它根據其他屬性動態計算值。
當您更改屬性值時，它會更新並反映相應的屬性值。

下表顯示了屬性物件支援的每個屬性的鍵。

序號	鍵及描述	型別
1	type 它從屬性反序列化，該屬性的型別使用型別的建構函式確定。	constructor (Boolean, Date, Number, String, Array 或 Object)
2	value 它指定屬性的預設值，如果它是函式，則它使用返回值作為屬性的預設值。	布林值、數字、字串或函式。
3	reflectToAttribute 如果此鍵設定為 true，則它會在主機節點上設定相應的屬性。如果將屬性值設定為布林值，則可以將其建立為標準 HTML 布林屬性。	布林值
4	readOnly 如果此鍵設定為 true，則不能透過賦值或資料繫結直接設定屬性。	布林值
5	notify 如果此鍵設定為 true，則可以使用該屬性進行雙向資料繫結，並且當您更改屬性時，將觸發 property-name-changed 事件。	布林值
6	computed 您可以透過呼叫方法來計算引數的值（無論何時更改），並且值將簡化為方法名稱和引數列表。	字串
7	observer 當屬性值更改時，呼叫簡化值為方法名稱的方法。	字串

屬性反序列化

根據指定的型別反序列化與例項上屬性匹配的屬性名稱以及元素例項上的相同屬性名稱（如果在屬性物件中配置了該屬性）。

如果在屬性物件中沒有定義其他屬性選項，則可以直接將指定的型別設定為屬性的值；否則，它將向屬性配置物件中的 type 鍵提供值。

配置布林屬性

布林屬性可以透過將其設定為 false 從標記進行配置，如果將其設定為 true，則不能從標記進行配置，因為帶有或不帶值的屬性都等於 true。因此，它被稱為 Web 平臺中屬性的標準行為。

物件和陣列屬性可以透過以 JSON 格式傳遞它們來配置，如下所示：

<element-demo player = '{ "name": "Sachin", "country": "India" }'></element-demo>

配置預設屬性值

可以使用屬性物件中的 value 欄位配置預設屬性，它可以是原始值，也可以是返回值的函式。

示例

以下示例描述瞭如何在屬性物件中配置預設屬性值。

<link rel = "import" href = "../../bower_components/polymer/polymer-element.html">

//it specifies the start of an element's local DOM
<dom-module id="polymer-app">
   <template>
      <style>
         :host {
            color:#33ACC9;
         }
      </style>
      <h2>Hello...[[myval]]!</h2>	
   </template>

   <script>
      //cusom element extending the Polymer.Element class
      class PolymerApp extends Polymer.Element {
         static get is() { return 'polymer-app'; }
         static get properties() {
            return {
               myval: {
                  type: String,
                  //displaying this value on screen
                  value: 'Welcome to Tutorialspoint;!!!'
               },
               data: {
                  type: Object,
                  notify: true,
                  value: function() { return {}; }
               }
            }
         }
      }
      window.customElements.define(PolymerApp.is, PolymerApp);
   </script>
</dom-module>

輸出

執行如前例所示的應用程式，並導航到 http://127.0.0.1:8000/。輸出如下所示。

Polymer Configure Default Property Value

只讀屬性

您可以透過在屬性物件中將 readOnly 標誌設定為 true 來避免對生成的資料進行意外更改。元素使用約定 _setProperty(value) 的 setter 來更改屬性值。

示例

以下示例描述了在屬性物件中使用只讀屬性。建立一個 index.html 檔案並在其中新增以下程式碼

<!doctype html>
<html>
   <head>
      <title>Polymer Example</title>
      <script src = "bower_components/webcomponentsjs/webcomponents-lite.js"></script>
    
      <link rel = "import" href = "bower_components/polymer/polymer.html">
      <link rel = "import" href = "my-element.html">
   </head>
   
   <body>
      <my-element></my-element>
   </body>
</html>

現在，建立另一個名為 my-element.html 的檔案幷包含以下程式碼。

<link rel = "import" href = "bower_components/polymer/polymer-element.html">
<link rel = "import" href = "prop-element.html">

//it specifies the start of an element's local DOM
<dom-module id = "my-element">
   <template>
      <prop-element my-prop = "{{demoProp}}"></prop-element>
      <p>Present value: <span>{{demoProp}}</span></p>
   </template>

   <script>
      Polymer ({
         is: "my-element", properties: {
            demoProp: String
         }
      });
   </script>
</dom-module>

接下來，建立一個名為 prop-element.html 的檔案並新增以下程式碼。

//it specifies the start of an element's local DOM
<dom-module id="prop-element">
   <template>
      <button on-click="onClickFunc">Change value</button>
   </template>
   
   <script>
      Polymer ({
         is: "prop-element", properties: {
            myProp: {
               type: String,
               notify: true,
               readOnly: true,
               value: 'This is initial value...'
            }
         },
         onClickFunc: function(){
            this._setMyProp('This is new value after clicking the button...');
         }
      });
   </script>
</dom-module>

輸出

執行如前例所示的應用程式，並導航到 http://127.0.0.1:8081/。輸出如下所示。

單擊按鈕後，它將更改值，如下面的螢幕截圖所示。

將屬性反映到屬性

可以透過在屬性配置物件中的屬性上將 reflectToAttribute 設定為 true 來與屬性值同步 HTML 屬性。

屬性序列化

在將屬性反射或繫結到屬性時，可以將屬性值序列化為屬性，並且預設情況下，可以根據值的當前型別序列化值。

字串 - 無需序列化。
日期或數字 - 使用 toString 序列化值。
布林值 - 將顯示的無值屬性設定為 true 或 false。
陣列或物件 - 使用 JSON.stringify 序列化值。

列印頁面