You're viewing an older version of Polymer. Please see Polymer 3.0 for the latest.

要定义一个自定义元素,创建一个类扩展 Polymer.Element 并将该类传递给 customElements.define 方法。

按照规范,自定义元素的名称 必须以小写 ASCII 字母开头,并且必须包含连字符(-)

示例:

// 定义元素的类元素
class MyElement extends Polymer.Element {

  // 元素类能定义一些自定义元素的反应
  connectedCallback() {
    super.connectedCallback();
    console.log('my-element created!');
  }

  ready() {
    super.ready();
    this.textContent = 'I\'m a custom element!';
  }
}

// 将新类与一个元素名称相关联
customElements.define('my-element', MyElement);

// 用 createElement 创建一个实例:
var el1 = document.createElement('my-element');

// ... 或者使用构造方法:
var el2 = new MyElement();

如上所示,元素的类可以定义一些自定义元素反应的回调,如在 自定义元素生命周期 中所描述的那样。

You can leverage native subclassing support provided by ES6 to extend and customize existing elements defined using ES6 syntax:

// Subclass existing element
class MyElementSubclass extends MyElement {
  static get is() { return 'my-element-subclass'; }
  static get properties() { ... }
  constructor() {
    super();
    ...
  }
  ...
}

// Register custom element definition using standard platform API
customElements.define(MyElementSubclass.is, MyElementSubclass);

For more information on extending elements, see Extending other elements in Custom element concepts.

If you don't provide a template for your subclass, it inherits the superclass's template by default. To override this behavior, or modify the superclass template, override the subclass's template getter.

You can share code using mixins. You use a mixin to add new features on top of a base class:

class MyElementWithMixin extends MyMixin(Polymer.Element) {

}

This pattern may be easier to understand if you think of it as two steps:

// Create a new base class that adds MyMixin's features to Polymer.Element
const BaseClassWithMixin = MyMixin(Polymer.Element);

// Extend the new base class
class MyElementWithMixin extends BaseClassWithMixin { ... }

Because mixins are simply adding classes to the inheritance chain, all of the usual rules of inheritance apply.

For information on defining mixins, see Sharing code with class expression mixins in Custom element concepts.

There are three main HTML imports for defining Polymer elements:

Import Description
polymer-element.html Defines the Polymer.Element base class.
legacy-element.html Defines the Polymer.LegacyElementMixin base class, which can be used to add 1.x compatible legacy API to Polymer.Element. Also defines the legacy Polymer() factory method for creating hybrid elements. (Includes polymer-element.html.)
polymer.html Includes the previous imports plus the helper elements (custom-style, dom-bind, dom-if, and dom-repeat) that were included in the 1.x polymer.html bundle.

For the smallest footprint, use the polymer-element.html import and import any required helper elements separately.

If you need some of the backwards-compabile APIs from 1.x, you can use the Polymer.LegacyElement class as the base for 2.x class-style elements. You must still import any helper elements you use individually.

Use the polymer.html import for defining hybrid elements that can run under both 1.x and 2.x.

You can add hybrid behaviors to your class-style element using the Polymer.mixinBehavior function:

class XClass extends Polymer.mixinBehaviors([MyBehavior, MyBehavior2], Polymer.Element) {

  ...
}
customElements.define('x-class', XClass);

The mixinBehavior function also mixes in the Legacy APIs, the same as if you extended Polymer.LegacyElement. These APIs are required since hybrid behaviors depend on them.

You should only define elements from the main document when experimenting. In production, elements should always be defined in separate files and imported into your main document.

To define an element in your main HTML document, define the element from HTMLImports.whenReady(callback). callback is invoked when all imports in the document have finished loading.

<!DOCTYPE html>
<html>
  <head>
    <script src="bower_components/webcomponentsjs/webcomponents-lite.js">
    </script>
    <link rel="import" href="bower_components/polymer/polymer-element.html">
    <title>Defining a Polymer Element from the Main Document</title>
  </head>
  <body>
    <dom-module id="main-document-element">
      <template>
        <p>
          Hi! I'm a Polymer element that was defined in the
          main document!
        </p>
      </template>
      <script>
        HTMLImports.whenReady(function() {
          class MainDocumentElement extends Polymer.Element {

            static get is() { return 'main-document-element'; }

          }
          window.customElements.define(MainDocumentElement.is, MainDocumentElement);
        });
      </script>
    </dom-module>
    <main-document-element></main-document-element>
  </body>
</html>

Legacy elements can use the Polymer function to register an element. The function takes as its argument the prototype for the new element. The prototype must have an is property that specifies the HTML tag name for your custom element.

By specification, the custom element's name must start with an ASCII letter and contain a dash (-).

Example:

    // register an element
    MyElement = Polymer({

      is: 'my-element',

      // See below for lifecycle callbacks
      created: function() {
        this.textContent = 'My element!';
      }

    });

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

    // ... or with the constructor:
    var el2 = new MyElement();

The Polymer function registers the element with the browser and returns a constructor that can be used to create new instances of your element via code.

The Polymer function sets up the prototype chain for your custom element, chaining it to the Polymer Base prototype (which provides Polymer value-added features), so you cannot set up your own prototype chain. However, you can use behaviors to share code between elements.

The Polymer.Element class implements the standard Custom Element lifecycle callbacks to perform tasks necessary for Polymer's built-in features.

Polymer adds an extra callback, ready, which is invoked when Polymer has finished creating and initializing the element's DOM.

Legacy callback Description
created Called when the element has been created, but before property values are set and local DOM is initialized.

Use for one-time set-up before property values are set.

Equivalent to the native constructor.

ready Called after property values are set and local DOM is initialized.

Use for one-time configuration of your component after local DOM is initialized. (For configuration based on property values, it may be preferable to use an observer.)

attached Called after the element is attached to the document. Can be called multiple times during the lifetime of an element. The first attached callback is guaranteed not to fire until after ready.

Uses include adding document-level event listeners. (For listeners local to the element, you can use declarative event handling, such as annotated event listeners or the listeners object.)

Equivalent to native connectedCallback.

detached Called after the element is detached from the document. Can be called multiple times during the lifetime of an element.

Uses include removing event listeners added in attached.

Equivalent to native disconnectedCallback.

attributeChanged Called when one of the element's attributes is changed.

Use to handle attribute changes that don't correspond to declared properties. (For declared properties, Polymer handles attribute changes automatically as described in attribute deserialization.)

Equivalent to the native attributeChangedCallback.

Legacy elements can share code in the form of behaviors, which can define properties, lifecycle callbacks, event listeners, and other features.

For more information, see Behaviors in the Polymer 1.x docs.