自定义元素 v1 - 可重复使用的网络组件

借助自定义元素,网络开发者可以定义新的 HTML 标记、扩展现有标记并创建可重复使用的网络组件。

借助自定义元素,网站开发者可以创建新的 HTML 标记、增强现有 HTML 标记,或者扩展其他开发者编写的组件。API 是 Web 组件的基础。它提供了一种基于 Web 标准的方法,仅使用原始的 JS/HTML/CSS 来创建可重复使用的组件。其结果是代码更精简且模块化,并且在我们的应用中的可重用性更好。

浏览器提供了一个用于实现结构化网络应用的良好工具。它叫做 HTML。您可能已经对它有所了解!它是一种声明式、可移植、受广泛支持且易于使用的工具。HTML 虽然很伟大,但其词汇和可扩展性却相当有限。HTML 现行标准一直缺乏自动关联 JS 行为和标记的方法,直到今天,情况才有所改观。

自定义元素使 HTML 变得现代化;补充了缺少的部件,并将结构与行为相结合。如果 HTML 无法为问题提供解决方案,我们可以创建自定义元素来解决。自定义元素可以教浏览器一些新技巧,同时保留 HTML 的优势

定义新元素

要定义新的 HTML 元素,我们需要 JavaScript 的帮助!

customElements 全局性用于定义自定义元素,并让浏览器学习新的标记。使用您要创建的标记名称调用 customElements.define(),并调用可扩展基本 HTMLElement 的 JavaScript class

示例 - 定义移动抽屉面板 <app-drawer>

class AppDrawer extends HTMLElement {...}
window.customElements.define('app-drawer', AppDrawer);

// Or use an anonymous class if you don't want a named constructor in current scope.
window.customElements.define('app-drawer', class extends HTMLElement {...});

用法示例:

<app-drawer></app-drawer>

请务必注意,自定义元素与 <div> 或任何其他元素的使用没有区别。可以在页面上声明 JavaScript 动态创建的实例,可添加事件监听器,诸如此类。请继续阅读,了解更多示例。

定义元素的 JavaScript API

自定义元素的功能使用 ES2015 class 进行定义,后者扩展了 HTMLElement。扩展 HTMLElement 可确保自定义元素继承整个 DOM API,这意味着您添加到类中的任何属性/方法都会成为元素的 DOM 接口的一部分。本质上,使用该类为您的代码创建一个公共 JavaScript API

示例 - 定义 <app-drawer> 的 DOM 接口:

class AppDrawer extends HTMLElement {

  // A getter/setter for an open property.
  get open() {
    return this.hasAttribute('open');
  }

  set open(val) {
    // Reflect the value of the open property as an HTML attribute.
    if (val) {
      this.setAttribute('open', '');
    } else {
      this.removeAttribute('open');
    }
    this.toggleDrawer();
  }

  // A getter/setter for a disabled property.
  get disabled() {
    return this.hasAttribute('disabled');
  }

  set disabled(val) {
    // Reflect the value of the disabled property as an HTML attribute.
    if (val) {
      this.setAttribute('disabled', '');
    } else {
      this.removeAttribute('disabled');
    }
  }

  // Can define constructor arguments if you wish.
  constructor() {
    // If you define a constructor, always call super() first!
    // This is specific to CE and required by the spec.
    super();

    // Setup a click listener on <app-drawer> itself.
    this.addEventListener('click', e => {
      // Don't toggle the drawer if it's disabled.
      if (this.disabled) {
        return;
      }
      this.toggleDrawer();
    });
  }

  toggleDrawer() {
    // ...
  }
}

customElements.define('app-drawer', AppDrawer);

在本例中,我们创建了一个具有 open 属性、disabled 属性和 toggleDrawer() 方法的抽屉式导航栏。它还以 HTML 属性来反映属性

自定义元素有一个超赞功能,即:类定义中的 this 引用 DOM 元素自身,亦即类的实例。在本示例中,this 是指 <app-drawer>。这 (😉) 就是元素向自身添加 click 监听器的方式!您不限于事件监听器。 完整的 DOM API 在元素代码内提供。使用 this 访问元素的属性、检查其子项 (this.children)、查询节点 (this.querySelectorAll('.items')) 等。

有关创建自定义元素的规则

  1. 自定义元素的名称必须包含短划线 (-)。因此,<x-tags><my-element><my-awesome-app> 均为有效名称,而 <tabs><foo_bar> 则不是。这一要求使得 HTML 解析器能够区分自定义元素和常规元素。它还可确保向 HTML 添加新标记时的向前兼容性。
  2. 您不能多次注册同一代码。否则,系统会抛出 DOMException。让浏览器了解新标记后,它就这样定了下来。不可收回。
  3. 自定义元素不能自我封闭,因为 HTML 仅允许少数元素自我封闭。必须编写封闭标记 (<app-drawer></app-drawer>)。

自定义元素回应

自定义元素可以定义特殊生命周期钩子,以便在其存续的特定时间内运行代码。这称为自定义元素响应

名称 调用时机
constructor 创建或升级了元素的实例。用于初始化状态、设置事件监听器或创建 Shadow DOM。 如需了解可在 constructor 中执行的操作的相关限制,请参阅规范
connectedCallback 每次元素插入到 DOM 时都会调用。这对于运行设置代码(例如提取资源或渲染)非常有用。通常,您应将工作推迟到该时间。
disconnectedCallback 元素每次从 DOM 中移除时都会调用。这对于运行清理代码很有用。
attributeChangedCallback(attrName, oldVal, newVal) 在添加、移除、更新或替换观察到的属性时调用。解析器创建元素时,或者升级时,也会调用它来获取初始值。注意:只有 observedAttributes 属性中列出的属性才会收到此回调。
adoptedCallback 自定义元素已移至新的 document(例如,有人调用了 document.adoptNode(el))。

响应回调是同步的。如果有人对您的元素调用 el.setAttribute(),浏览器将立即调用 attributeChangedCallback()。同理,从 DOM 中移除元素(例如用户调用 el.remove())后,您会立即收到 disconnectedCallback()

示例:向 <app-drawer> 添加自定义元素回应:

class AppDrawer extends HTMLElement {
  constructor() {
    super(); // always call super() first in the constructor.
    // ...
  }

  connectedCallback() {
    // ...
  }

  disconnectedCallback() {
    // ...
  }

  attributeChangedCallback(attrName, oldVal, newVal) {
    // ...
  }
}

必要时应定义响应。如果您的元素足够复杂,并在 connectedCallback() 中打开 IndexedDB 的连接,请在 disconnectedCallback() 中执行所需清理工作。但请务必小心!您不能认为您的元素任何时候都能从 DOM 中正常移除。例如,如果用户关闭了标签页,disconnectedCallback() 将无法调用。

属性和特性

将属性映射为特性

HTML 属性通常以 HTML 属性的形式将其值反映到 DOM。例如,在 JS 中更改 hiddenid 的值时:

div.id = 'my-id';
div.hidden = true;

值将作为属性应用到活动 DOM:

<div id="my-id" hidden>

这称为“将属性映射为特性”。几乎所有的 HTML 属性都会如此。为什么呢?属性也可用于以声明方式配置元素,且无障碍功能和 CSS 选择器等某些 API 依赖于属性工作。

如果您想要让元素的 DOM 表示法与其 JavaScript 状态保持同步,映射属性非常有用。您可能想要映射属性的另一个原因是,用户定义的样式在 JS 状态变更时应用。

回顾我们的 <app-drawer>。此组件的用户可能会希望其灰色显示和/或停用,以避免用户交互:

app-drawer[disabled] {
  opacity: 0.5;
  pointer-events: none;
}

disabled 属性在 JS 中发生更改时,我们希望将该属性添加到 DOM 中,以便用户的选择器匹配。元素可以通过将值映射到同名属性来提供该行为:

get disabled() {
  return this.hasAttribute('disabled');
}

set disabled(val) {
  // Reflect the value of `disabled` as an attribute.
  if (val) {
    this.setAttribute('disabled', '');
  } else {
    this.removeAttribute('disabled');
  }
  this.toggleDrawer();
}

观察属性的更改

HTML 属性是用户声明初始状态的一种便捷方式:

<app-drawer open disabled></app-drawer>

元素可通过定义 attributeChangedCallback 来对属性的更改作出响应。对于 observedAttributes 数组中列出的每一属性更改,浏览器都将调用此方法。

class AppDrawer extends HTMLElement {
  // ...

  static get observedAttributes() {
    return ['disabled', 'open'];
  }

  get disabled() {
    return this.hasAttribute('disabled');
  }

  set disabled(val) {
    if (val) {
      this.setAttribute('disabled', '');
    } else {
      this.removeAttribute('disabled');
    }
  }

  // Only called for the disabled and open attributes due to observedAttributes
  attributeChangedCallback(name, oldValue, newValue) {
    // When the drawer is disabled, update keyboard/screen reader behavior.
    if (this.disabled) {
      this.setAttribute('tabindex', '-1');
      this.setAttribute('aria-disabled', 'true');
    } else {
      this.setAttribute('tabindex', '0');
      this.setAttribute('aria-disabled', 'false');
    }
    // TODO: also react to the open attribute changing.
  }
}

在此示例中,当 disabled 属性更改时,我们在 <app-drawer> 上设置其他属性。虽然我们这里没有这样做,您也可以使用 attributeChangedCallback 来让 JS 属性与其属性同步

元素升级

渐进式增强 HTML

我们已经了解到,自定义元素通过调用 customElements.define() 进行定义。但这并不意味着您必须一次性定义并注册自定义元素。

自定义元素可以在定义注册之前使用

渐进式增强是自定义元素的一项特点。换句话说,您可以在页面声明多个 <app-drawer> 元素,并在等待较长的时间之后才调用 customElements.define('app-drawer', ...)。之所以会这样,原因是浏览器会因为存在未知标记而采用不同方式处理潜在自定义元素。调用 define() 并向现有元素赋予类定义的过程称为“元素升级”。

如需了解标记名称何时获得定义,您可以使用 window.customElements.whenDefined()。它会返回一个 Promise,该 Promise 会在元素获得定义时解析。

customElements.whenDefined('app-drawer').then(() => {
  console.log('app-drawer defined');
});

示例 - 推迟生效时间,直至一组子元素升级

<share-buttons>
  <social-button type="twitter"><a href="...">Twitter</a></social-button>
  <social-button type="fb"><a href="...">Facebook</a></social-button>
  <social-button type="plus"><a href="...">G+</a></social-button>
</share-buttons>
// Fetch all the children of <share-buttons> that are not defined yet.
let undefinedButtons = buttons.querySelectorAll(':not(:defined)');

let promises = [...undefinedButtons].map((socialButton) => {
  return customElements.whenDefined(socialButton.localName);
});

// Wait for all the social-buttons to be upgraded.
Promise.all(promises).then(() => {
  // All social-button children are ready.
});

元素定义的内容

自定义元素可以通过在元素代码中使用 DOM API 来管理其自身的内容。回应功能非常适合此用途。

示例 - 使用一些默认 HTML 来创建元素:

customElements.define('x-foo-with-markup', class extends HTMLElement {
  connectedCallback() {
    this.innerHTML = "<b>I'm an x-foo-with-markup!</b>";
  }
  // ...
});

声明此标记将产生:

<x-foo-with-markup>
  <b>I'm an x-foo-with-markup!</b>
</x-foo-with-markup>

// TODO:DevSite - 代码示例已移除,因为它使用内联事件处理脚本

创建使用 Shadow DOM 的元素

Shadow DOM 提供了一种方法,可让元素以独立于页面其余部分的方式拥有和渲染 DOM 并设置其样式。您甚至可以使用一个标记来隐藏整个应用:

<!-- chat-app's implementation details are hidden away in Shadow DOM. -->
<chat-app></chat-app>

如需在自定义元素中使用 Shadow DOM,请在 constructor 内调用 this.attachShadow

let tmpl = document.createElement('template');
tmpl.innerHTML = `
  <style>:host { ... }</style> <!-- look ma, scoped styles -->
  <b>I'm in shadow dom!</b>
  <slot></slot>
`;

customElements.define('x-foo-shadowdom', class extends HTMLElement {
  constructor() {
    super(); // always call super() first in the constructor.

    // Attach a shadow root to the element.
    let shadowRoot = this.attachShadow({mode: 'open'});
    shadowRoot.appendChild(tmpl.content.cloneNode(true));
  }
  // ...
});

用法示例:

<x-foo-shadowdom>
  <p><b>User's</b> custom text</p>
</x-foo-shadowdom>

<!-- renders as -->
<x-foo-shadowdom>
  #shadow-root
  <b>I'm in shadow dom!</b>
  <slot></slot> <!-- slotted content appears here -->
</x-foo-shadowdom>

用户的自定义文本

// TODO:DevSite - 代码示例已移除,因为它使用内联事件处理脚本

通过 <template> 创建元素

对于不熟悉的用户,您可以使用 <template> 元素声明 DOM 的 fragment,这些 fragment 会在页面加载时被解析、休眠,并稍后可在运行时激活。它是 Web 组件家族中的另一个 API 原语。模板是声明自定义元素结构的理想占位符

示例:注册带有使用 <template> 创建的 Shadow DOM 内容的元素:

<template id="x-foo-from-template">
  <style>
    p { color: green; }
  </style>
  <p>I'm in Shadow DOM. My markup was stamped from a &lt;template&gt;.</p>
</template>

<script>
  let tmpl = document.querySelector('#x-foo-from-template');
  // If your code is inside of an HTML Import you'll need to change the above line to:
  // let tmpl = document.currentScript.ownerDocument.querySelector('#x-foo-from-template');

  customElements.define('x-foo-from-template', class extends HTMLElement {
    constructor() {
      super(); // always call super() first in the constructor.
      let shadowRoot = this.attachShadow({mode: 'open'});
      shadowRoot.appendChild(tmpl.content.cloneNode(true));
    }
    // ...
  });
</script>

这几行代码实现了丰富的功能。我们来了解一些主要方面:

  1. 我们在 HTML 中定义新的元素:<x-foo-from-template>
  2. 元素的 Shadow DOM 使用 <template> 创建
  3. 由于是 Shadow DOM,元素的 DOM 局限于元素本地
  4. 由于是 Shadow DOM,元素的内部 CSS 作用域限于元素内

I'm in Shadow DOM. My markup was stamped from a <template>.

// TODO:DevSite - 代码示例已移除,因为它使用内联事件处理脚本

设置自定义元素的样式

即使您的元素使用 Shadow DOM 定义了自身的样式,用户仍可通过其自己的页面来设置自定义元素的样式。它们称为“用户定义样式”。

<!-- user-defined styling -->
<style>
  app-drawer {
    display: flex;
  }
  panel-item {
    transition: opacity 400ms ease-in-out;
    opacity: 0.3;
    flex: 1;
    text-align: center;
    border-radius: 50%;
  }
  panel-item:hover {
    opacity: 1.0;
    background: rgb(255, 0, 255);
    color: white;
  }
  app-panel > panel-item {
    padding: 5px;
    list-style: none;
    margin: 0 7px;
  }
</style>

<app-drawer>
  <panel-item>Do</panel-item>
  <panel-item>Re</panel-item>
  <panel-item>Mi</panel-item>
</app-drawer>

您可能会问自己,如果元素在 Shadow DOM 中定义了样式,CSS 特异性如何起作用。在特异性方面,用户样式优先。它们始终会替换元素定义的样式。请参阅创建使用 Shadow DOM 的元素部分。

预设置未注册元素的样式

在元素升级之前,您可以在 CSS 中使用 :defined 伪类定位到该元素。这对于预设置元素样式而言很有用。例如,您可能想要通过隐藏未定义的组件并使其在获得定义时淡入,以防止布局或其他视觉 FOUC。

示例 - 在定义 <app-drawer> 之前将其隐藏:

app-drawer:not(:defined) {
  /* Pre-style, give layout, replicate app-drawer's eventual styles, etc. */
  display: inline-block;
  height: 100vh;
  opacity: 0;
  transition: opacity 0.3s ease-in-out;
}

<app-drawer> 获得定义后,选择器 (app-drawer:not(:defined)) 不再匹配。

扩展元素

Custom Elements API 对创建新的 HTML 元素非常有用,但也可用于扩展其他自定义元素,甚至是浏览器的内置 HTML。

扩展自定义元素

扩展其他自定义元素可通过扩展其类定义来实现。

示例 - 创建扩展 <app-drawer><fancy-app-drawer>

class FancyDrawer extends AppDrawer {
  constructor() {
    super(); // always call super() first in the constructor. This also calls the extended class' constructor.
    // ...
  }

  toggleDrawer() {
    // Possibly different toggle implementation?
    // Use ES2015 if you need to call the parent method.
    // super.toggleDrawer()
  }

  anotherMethod() {
    // ...
  }
}

customElements.define('fancy-app-drawer', FancyDrawer);

扩展原生 HTML 元素

假设您想要创建一个更漂亮的 <button>。除了复制 <button> 的行为和功能,更好的选择是使用自定义元素逐渐增补现有元素。

自定义内置元素是指扩展浏览器的内置 HTML 标记的自定义元素。扩展现有元素的主要好处是获得其所有功能(DOM 属性、方法、无障碍功能)。编写渐进式 Web 应用的最佳方法是逐渐增补现有 HTML 元素

如需扩展元素,您需要创建继承自正确 DOM 接口的类定义。例如,扩展 <button> 的自定义元素需要从 HTMLButtonElement 而不是 HTMLElement 继承。同样,扩展 <img> 的元素需要扩展 HTMLImageElement

示例 - 扩展 <button>

// See https://html.spec.whatwg.org/multipage/indices.html#element-interfaces
// for the list of other DOM interfaces.
class FancyButton extends HTMLButtonElement {
  constructor() {
    super(); // always call super() first in the constructor.
    this.addEventListener('click', e => this.drawRipple(e.offsetX, e.offsetY));
  }

  // Material design ripple animation.
  drawRipple(x, y) {
    let div = document.createElement('div');
    div.classList.add('ripple');
    this.appendChild(div);
    div.style.top = `${y - div.clientHeight/2}px`;
    div.style.left = `${x - div.clientWidth/2}px`;
    div.style.backgroundColor = 'currentColor';
    div.classList.add('run');
    div.addEventListener('transitionend', (e) => div.remove());
  }
}

customElements.define('fancy-button', FancyButton, {extends: 'button'});

请注意,扩展原生元素时,对 define() 的调用会稍有不同。第三个必需参数用于告知浏览器您要扩展哪个代码。这很有必要,因为许多 HTML 标记均使用同一 DOM 接口。<section><address><em>(以及其他一些组件)都共用 HTMLElement<q><blockquote> 共用 HTMLQuoteElement;等等。指定 {extends: 'blockquote'} 可让浏览器知道您要创建的是增强型 <blockquote>,而不是 <q>。如需查看 HTML DOM 接口的完整列表,请参阅 HTML 规范

自定义内置元素的使用方可以通过多种方式使用它。他们可以通过在原生标记中添加 is="" 属性来声明它:

<!-- This <button> is a fancy button. -->
<button is="fancy-button" disabled>Fancy button!</button>

在 JavaScript 中创建实例:

// Custom elements overload createElement() to support the is="" attribute.
let button = document.createElement('button', {is: 'fancy-button'});
button.textContent = 'Fancy button!';
button.disabled = true;
document.body.appendChild(button);

或者使用 new 运算符:

let button = new FancyButton();
button.textContent = 'Fancy button!';
button.disabled = true;

下面是扩展 <img> 的另一个示例。

示例 - 扩展 <img>

customElements.define('bigger-img', class extends Image {
  // Give img default size if users don't specify.
  constructor(width=50, height=50) {
    super(width * 10, height * 10);
  }
}, {extends: 'img'});

用户声明此组件为:

<!-- This <img> is a bigger img. -->
<img is="bigger-img" width="15" height="20">

或者在 JavaScript 中创建实例:

const BiggerImage = customElements.get('bigger-img');
const image = new BiggerImage(15, 20); // pass constructor values like so.
console.assert(image.width === 150);
console.assert(image.height === 200);

其他详细信息

未知元素与未定义的自定义元素

HTML 使用起来较为宽松和灵活。例如,在页面上声明 <randomtagthatdoesntexist>,浏览器将非常乐意接受它。为什么非标准代码可以生效?答案是 HTML 规范允许这样。规范未定义的元素会被解析为 HTMLUnknownElement

自定义元素则并非如此。如果在创建时使用有效的名称(包含“-”),则潜在的自定义元素将解析为 HTMLElement。您可以在支持自定义元素的浏览器中核实这一点。启动控制台:Ctrl+Shift+J(在 Mac 上为 Cmd+Opt+J),然后粘贴以下代码行:

// "tabs" is not a valid custom element name
document.createElement('tabs') instanceof HTMLUnknownElement === true

// "x-tabs" is a valid custom element name
document.createElement('x-tabs') instanceof HTMLElement === true

API 参考文档

customElements 全局变量定义了处理自定义元素的实用方法。

define(tagName, constructor, options)

在浏览器中定义新的自定义元素。

示例

customElements.define('my-app', class extends HTMLElement { ... });
customElements.define(
    'fancy-button', class extends HTMLButtonElement { ... }, {extends: 'button'});

get(tagName)

在给定有效的自定义元素标记名称的情况下,返回元素的构造函数。如果未注册任何元素定义,则返回 undefined

示例

let Drawer = customElements.get('app-drawer');
let drawer = new Drawer();

whenDefined(tagName)

如果定义了自定义元素,则返回可解析的 Promise。如果元素已定义,则立即得到解析。如果标记名称并非有效自定义元素名称,则拒绝。

示例

customElements.whenDefined('app-drawer').then(() => {
  console.log('ready!');
});

历史记录和浏览器支持

如果您最近几年持续关注网络组件,您应知道 Chrome 36+ 实施的自定义元素 API 版本使用了 document.registerElement() 而不是 customElements.define()。这现在被视为已弃用的标准版本 v0。customElements.define() 成为现行标准并逐步获得各大浏览器厂商的支持。这称为自定义元素 v1。

如果您恰好对旧版 v0 规范感兴趣,请参阅 html5rocks 文章

浏览器支持

Chrome 54(状态)、Safari 10.1(状态)和 Firefox 63(状态)具有自定义元素 v1。Edge 已开始开发

如需检测自定义元素,请检查是否存在 window.customElements

const supportsCustomElementsV1 = 'customElements' in window;

polyfill

在浏览器提供广泛支持前,自定义元素 v1 有一个独立的 polyfill 可供使用。不过,我们建议您使用 webcomponents.js 加载器以最佳方式加载 Web 组件 polyfill。加载器使用功能检测来异步加载浏览器所需的必要的多功能插件。

安装:

npm install --save @webcomponents/webcomponentsjs

用法:

<!-- Use the custom element on the page. -->
<my-element></my-element>

<!-- Load polyfills; note that "loader" will load these async -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js" defer></script>

<!-- Load a custom element definitions in `waitFor` and return a promise -->
<script type="module">
  function loadScript(src) {
    return new Promise(function(resolve, reject) {
      const script = document.createElement('script');
      script.src = src;
      script.onload = resolve;
      script.onerror = reject;
      document.head.appendChild(script);
    });
  }

  WebComponents.waitFor(() => {
    // At this point we are guaranteed that all required polyfills have
    // loaded, and can use web components APIs.
    // Next, load element definitions that call `customElements.define`.
    // Note: returning a promise causes the custom elements
    // polyfill to wait until all definitions are loaded and then upgrade
    // the document in one batch, for better performance.
    return loadScript('my-element.js');
  });
</script>

总结

自定义元素提供了一种新工具,可让我们在浏览器中定义新 HTML 标记并创建可重用的组件。将它们与 Shadow DOM 和 <template> 等新平台原语结合使用,我们可开始实现网络组件的宏大图景:

  • 创建和扩展可重复使用组件的跨浏览器(网络标准)。
  • 无需库或框架即可使用。原生 JS/HTML 太棒了!
  • 提供熟悉的编程模型。仅需使用 DOM/CSS/HTML。
  • 与其他网络平台功能良好匹配(Shadow DOM、<template>、CSS 自定义属性等)
  • 与浏览器的 DevTools 紧密集成。
  • 利用现有的无障碍功能。