Polymer 快速指南

---

---

Polymer - 概述

Polymer.js 是 Google 建立的一個 JavaScript 庫，允許重用 HTML 元素來構建基於元件的應用程式。

Polymer 是一個由 Google 開發人員開發的開源 JavaScript 庫，最初於 2015 年 5 月 27 日釋出。穩定版本為 1.7.0，於 2016 年 9 月 29 日釋出。

為什麼要使用 Polymer.js？

• 它允許我們使用 HTML、CSS 和 JavaScript 輕鬆建立自己的自定義元素，為元素新增互動功能。

• 它由 Google 建立，提供與 Web 元件一起使用的跨瀏覽器相容應用程式。

• 它提供單向和雙向資料繫結。

• 它提供 Polymer 命令列介面，用於管理從簡單元件到複雜 Web 應用程式的專案。

Polymer.js 的特性

• 它是一個基於 Web 標準 API 構建的 JavaScript 庫，允許構建自定義 HTML 元素。

• 它提供 polyfills（Web 元件規範）用於建立我們自己的自定義和可重用元素。

• 它使用 Web 元件標準在 Web 文件和 Web 應用程式中建立可重用的部件。

• 它使用 Google Material Design 開發混合移動應用程式。

• 它透過網路分發自定義元素，使用者可以使用 HTML Imports 來使用這些元素。

Polymer - 安裝

在你的系統中配置 Polymer 很容易。以下是安裝 Polymer 的兩種方法。

• Polymer CLI（命令列介面）
• Bower

使用 Polymer CLI 安裝 Polymer

步驟 1 - 使用以下 npm 命令安裝 Polymer。

npm install -g polymer-cli@next

步驟 2 - 使用以下命令檢查安裝是否成功以及版本。

polymer --version

如果安裝成功，則會顯示版本為 -

步驟 3 - 建立一個你選擇的名稱的目錄，並切換到該目錄。

mkdir polymer-js 
cd polymer-js

步驟 4 - 要初始化你的專案，請在你的 *polymer-jsdirectory* 中執行以下命令。

polymer init

執行上述命令後，它將顯示類似以下內容 -

C:\polymer-js>polymer init 
? Which starter template would you like to use? 
   1) polymer-1-element - A simple Polymer 1.0 element template 
   2) polymer-2-element - A simple Polymer 2.0 element template 
   3) polymer-1-application - A simple Polymer 1.0 application template 
   4) polymer-2-application - A simple Polymer 2.0 application 
   5) polymer-1-starter-kit - A Polymer 1.x starter application template, with 
      navigation and "PRPL pattern" loading 
   6) polymer-2-starter-kit - A Polymer 2.x starter application template, with 
      navigation and "PRPL pattern" loading 
   7) shop - The "Shop" Progressive Web App demo
   Answer: 4   

步驟 5 - 從上面給出的選項中選擇 polymer-2-application。

現在，使用以下命令啟動你的專案。

polymer serve

使用 Bower 安裝 Polymer

步驟 1 - 要使用 Bower 方法從頭開始，請使用以下命令安裝 Bower。

npm install -g bower

步驟 2 - 使用以下命令安裝 Polymer。

npm install -g polymer-cli@next

步驟 3 - 使用以下命令檢查 Polymer 的安裝是否成功以及版本。

polymer --version

如果安裝成功，則會顯示版本為 -

0.18.0-pre.13.

步驟 4 - 要從 bower 安裝最新的 Polymer 2.0 RC 版本，請使用以下命令。

bower install Polymer/polymer#^2.0.0-rc.3

步驟 5 - 建立一個 **index.html** 檔案，並在 `` 標籤中新增以下程式碼。

<script src = "/bower_components/webcomponentsjs/webcomponentsloader.js"></script> 
// it loads the polyfills 

<link rel = "import" href = "/bower_components/polymer/polymer.html"> 
// it import Polymer 

步驟 6 - 使用以下命令啟動你的專案。

polymer serve 

構建以進行部署

要構建你的專案以進行部署，**polymer build** 命令是一種更簡單的方法，它將根據命令列標誌縮小、編譯或捆綁你的程式碼。

要建立可在所有瀏覽器上執行的通用構建，請使用以下命令。

polymer build --js-compile

上述命令將構建專案到 build/default，你可以使用以下命令啟動此目錄。

polymer serve build/default

Polymer 2.0 使用 ES6 和 HTML 自定義元素。最佳實踐是始終使用 ES6 來支援 ES6 的瀏覽器，並將 ES5 編譯為不支援 ES6 的舊瀏覽器。下表顯示了專案的最佳策略。

Polymer - 元素

Polymer 元素是一組視覺和非視覺元素，旨在與佈局、使用者互動、選擇和腳手架應用程式一起工作。這些包括從簡單的按鈕到具有簡潔視覺效果的對話方塊的所有內容。下表顯示了不同型別的 Polymer 元素。

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>

注意 - 自定義元素名稱應以小寫字母開頭，並在名稱之間包含破折號。

自定義元素生命週期

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

元素升級

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

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

• 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 - 當元素的屬性發生更改時呼叫它，它包含與宣告的屬性不相容的屬性更改。

宣告屬性

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

• 它指定屬性型別和預設值。

• 當屬性值發生更改時，它呼叫觀察者方法。

• 它指定只讀狀態以阻止對屬性值的意外更改。

• 它支援雙向資料繫結，當你更改屬性值時會觸發事件。

• 它是一個計算屬性，它根據其他屬性動態計算值。

• 當你更改屬性值時，它會更新並反映相應的屬性值。

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

屬性反序列化

如果屬性在 properties 物件中配置，則根據指定的型別以及元素例項上相同屬性名稱，反序列化與例項上某個屬性匹配的屬性名稱。

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

配置布林屬性

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

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

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

配置預設屬性值

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

示例

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

<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/**。輸出如下所示。

只讀屬性

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

示例

以下示例描述了在 properties 物件中使用只讀屬性。建立一個 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/**。輸出如下所示。

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

將屬性反映到屬性

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

屬性序列化

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

• **字串** - 無需序列化。

• **日期或數字** - 使用 toString 序列化值。

• **布林值** - 將顯示的無值屬性設定為 true 或 false。

• **陣列或物件** - 使用 JSON.stringify 序列化值。

Polymer - Shadow DOM 和樣式

Shadow DOM 是 DOM 的一個新屬性，用於構建元件。

示例

在下面的程式碼中，header 元件包含頁面標題和選單按鈕。

<header-demo>
   <header>
      <h1>
         <button>

Shadow DOM 允許在稱為 **shadow tree** 的作用域子樹中定位子元素。

<header-demo>
   #shadow-root
   <header>
      <h1>
      <button>

shadow-root 根被稱為 shadow tree 的頂部，附加到樹的元素被稱為 shadow host (header-demo)。此 shadow host 包含一個名為 shadowRoot 的屬性，該屬性指定 shadow root。shadow root 使用 host 屬性標識宿主元素。

Shadow DOM 和組合

如果 Shadow DOM 中有元素，則可以渲染 shadow tree 來代替元素的子元素。可以透過將 元素新增到 shadow tree 來渲染元素的子元素。

例如，對 使用以下 shadow tree。

<header>
   <h1><slot></slot></h1>
   <button>Menu</button>
</header>

將子元素新增到 元素，例如：

<header-demo>Shadow DOM</header-demo>

header 將 元素替換為上面指定的子元素，例如：

<header-demo>
   <header>
      <h1>Shadow DOM</h1>
      <button>Menu</button>
   </header>
</header-demo>

回退內容

當沒有節點分配給 slot 時，可以顯示回退內容。例如：

<my-element>
   #shadow-root
   <slot id = "myimgicon">
      <img src = "img-demo.png">
   </slot>
   <slot></slot>
<my-element>

您可以為元素提供您自己的圖示，例如：

<my-element>
   <img slot = "myimgicon" src = "warning.png">
<my-element>

多級分發

您可以將 slot 元素分配給一個 slot，這稱為多級分發。

例如，考慮如下所示的 shadow tree 的兩個級別：

<parent-element>
   #shadow-root
      <child-element>
      <!-- display the light DOM children of parent-element inside child-element -->
      <slot id = "parent-slot">
	  
   <child-element>
      #shadow-root
         <div>
            <!-- Render the light DOM children inside div by using child-element -->
            <slot id = "child-slot">

考慮以下程式碼：

<parent-element>
   <p>This is light DOM</p>
<parent-element>

扁平化樹的結構如下所示。

<parent-element>
   <child-element>
      <div>
         <slot id = "child-slot">
            <slot id = "parent-slot">
               <p>This is light DOM</p>

Shadow DOM 使用以下 Slot API 來檢查分發：

• **HTMLElement.assignedSlot** - 它為元素分配 slot，如果沒有將元素分配給 slot，則返回 null。

• **HTMLSlotElement.assignedNodes** - 它提供節點列表以及 slot，當您將 flatten 選項設定為 true 時，它返回分發的節點。

• **HTMLSlotElement.slotchange** - 當 slot 的分發節點發生變化時，此事件將觸發。

事件重新定位

它指定事件的目標，其中元素可以在與偵聽元素相同的範圍內表示。它提供來自自定義元素的事件，看起來像是來自自定義元素標籤的事件，而不是其中的元素。

示例

以下示例演示了在 Polymer.js 中使用事件重新定位。建立一個名為 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 = "retarget-event.html">
   </head>
   
   <body>
      <template id = "myapp" is = "dom-bind">
         <retarget-event on-tap = "clicky"></retarget-event>
      </template>
      
      <script>
         var myval = document.querySelector('#myapp');
         myval.clicky = function(e) {
            console.log("The retargeted result:", Polymer.dom(myval));
            console.log("Normal result:", e);
         };
      </script>
   </body>
</html>

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

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

//it specifies the start of an element's local DOM
<dom-module id = "retarget-event">

   <template>
      <span>Click on this text to see result in console...</span>
   </template>

   <script>
      Polymer ({
         is: 'retarget-event',
      });
   </script>
</dom-module>

輸出

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

polymer serve

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

單擊上面的文字並開啟控制檯，檢視如下面的螢幕截圖所示的重新定位事件。

Shadow DOM 樣式

您可以使用樣式屬性來設定 Shadow DOM 的樣式，這些樣式屬性從宿主繼承到 shadow tree。

示例

<style>
   .mydemo { background-color: grey; }
</style>

<my-element>
#shadow-root
   <style>
      //this div will have blue background color
      div { background-color: orange; }
   </style>
   <div class = "mydemo">Demo</div>

DOM 模板

可以使用 DOM 模板為元素建立 DOM 子樹。您可以為元素建立 shadow root，並透過將 DOM 模板新增到元素來將模板複製到 shadow tree。

DOM 模板可以透過兩種方式指定：

• 建立一個 元素，它應該與元素的名稱以及 id 屬性匹配。

• 在 內定義一個