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 属性匹配。

• 在 内定义一个