This page was translated from English by the community. Learn more and join the MDN Web Docs community.

Web Components

Web Components 是一套不同的技术，允许您创建可重用的定制元素（它们的功能封装在您的代码之外）并且在您的web应用中使用它们。

概念和使用

作为开发者，我们都知道尽可能多的重用代码是一个好主意。这对于自定义标记结构来说通常不是那么容易 — 想想复杂的HTML（以及相关的样式和脚本），有时您不得不写代码来呈现自定义UI控件，并且如果您不小心的话，多次使用它们会使您的页面变得一团糟。

Web Components旨在解决这些问题 — 它由三项主要技术组成，它们可以一起使用来创建封装功能的定制元素，可以在你喜欢的任何地方重用，不必担心代码冲突。

  • Custom elements（自定义元素）：一组JavaScript API，允许您定义custom elements及其行为，然后可以在您的用户界面中按照需要使用它们。
  • Shadow DOM（影子DOM）：一组JavaScript API，用于将封装的“影子”DOM树附加到元素（与主文档DOM分开呈现）并控制其关联的功能。通过这种方式，您可以保持元素的功能私有，这样它们就可以被脚本化和样式化，而不用担心与文档的其他部分发生冲突。
  • HTML templates（HTML模板）： <template> 和 <slot> 元素使您可以编写不在呈现页面中显示的标记模板。然后它们可以作为自定义元素结构的基础被多次重用。

实现web component的基本方法通常如下所示：

  1. 创建一个类或函数来指定web组件的功能，如果使用类，请使用 ECMAScript 2015 的类语法(参阅类获取更多信息)。
  2. 使用 CustomElementRegistry.define() 方法注册您的新自定义元素 ，并向其传递要定义的元素名称、指定元素功能的类、以及可选的其所继承自的元素。
  3. 如果需要的话，使用Element.attachShadow() 方法将一个shadow DOM附加到自定义元素上。使用通常的DOM方法向shadow DOM中添加子元素、事件监听器等等。
  4. 如果需要的话，使用 <template> 和<slot> 定义一个HTML模板。再次使用常规DOM方法克隆模板并将其附加到您的shadow DOM中。
  5. 在页面任何您喜欢的位置使用自定义元素，就像使用常规HTML元素那样。

教程

Using custom elements
介绍如何使用自定义元素的功能来创建简单的 web components，以及生命周期回调和其他更高级的功能。
Using shadow DOM
介绍 shadow DOM 的基础知识，展示如何向元素中附加shadow DOM，添加到shadow DOM树，添加样式等等。
Using templates and slots
介绍如何使用<template> 和 <slot> 元素定义可重用的HTML结构，然后在Web components中使用该结构。

参考

Custom elements

CustomElementRegistry
包含自定义元素相关功能，最值得注意的是 CustomElementRegistry.define() 方法用来注册新的自定义元素，这样就可以在文档中使用它们。
Window.customElements
返回 CustomElementRegistry 对象的引用。
生命周期回调
定义在自定义元素的类定义中的特殊回调函数，影响其行为：
  • connectedCallback: 当自定义元素第一次被连接到文档DOM时被调用。
  • disconnectedCallback: 当自定义元素与文档DOM断开连接时被调用。
  • adoptedCallback: 当自定义元素被移动到新文档时被调用。
  • attributeChangedCallback: 当自定义元素的一个属性被增加、移除或更改时被调用。
创建自定义内置元素的扩展
  • is 全局 HTML 属性：允许您指定一个标准HTML元素应该表现得像一个已注册的自定义内置元素。
  • Document.createElement() 方法的“is”选项：允许您创建一个标准HTML元素的实例，表现得像一个给定的已注册的自定义内置元素。
CSS 伪类
与自定义元素特别相关的伪类：
  • :defined: 匹配任何已定义的元素，包括内置元素和使用CustomElementRegistry.define()定义的自定义元素。
  • :host: 选择 shadow DOM 的 shadow host ，内容是它内部使用的 CSS（ containing the CSS it is used inside ）。
  • :host(): 选择 shadow DOM 的 shadow host ，内容是它内部使用的 CSS （这样您可以从 shadow DOM 内部选择自定义元素）— 但只匹配给定方法的选择器的 shadow host 元素。
  • :host-context(): 选择 shadow DOM 的 shadow host ，内容是它内部使用的 CSS （这样您可以从 shadow DOM 内部选择自定义元素）— 但只匹配给定方法的选择器匹配元素的子 shadow host 元素。

Shadow DOM

ShadowRoot
表示shadow DOM子树的根节点。
DocumentOrShadowRoot
定义了可在文档和shadow根中使用的功能的mixin。
Element extensions
与shadow DOM有关的Element 接口的扩展:
Node 相关拓展
与 shadow DOM 相关的 Node 接口的拓展:
  • Node.getRootNode() 方法返回上下文对象的根，可以选择包含shadow root，如果可用的话。
  • Node.isConnected 属性返回一个布尔值表示节点是否连接（直接或间接）到上下文对象。例如，在普通DOM的情况下为Document 对象，或者在shadow DOM的情况下为 ShadowRoot 。
Event 拓展
与shadow DOM相关的Event 接口的扩展：
  • Event.composed: 返回 Boolean 它表明事件是否会通过shadow DOM边界传播到标准DOM。
  • 返回事件的路径（侦听器将被调用的对象）。如果shadow root是使用ShadowRoot.mode为closed创建的，则不包括shadow树中的节点。

HTML templates

<template>
包含一个HTML片段，不会在文档初始化时渲染。但是可以在运行时使用JavaScript显示。主要用作自定义元素结构的基础。关联的DOM接口是HTMLTemplateElement。
<slot>
web component中的一个占位符，你可以填充自己的标记，这样你就可以创建单独的DOM树并将它们呈现在一起。关联的DOM接口是HTMLSlotElement。
The slot global HTML attribute
将在shadow DOM树中的插槽分配给一个元素。
Slotable
由 Element 和 Text 节点实现的mixin，定义了允许它们成为 <slot> 元素内容的特性。mixin定义了一个属性， Slotable.assignedSlot (en-US)，返回节点所插入的插槽的引用。
Element extensions
与插槽相关的Element接口的扩展：
  • Element.slot: 返回附加到元素上的shadow DOM插槽的名字。
CSS pseudo-elements
slots特别相关的伪元素:
  • ::slotted: 匹配任何已经插入一个slot的内容。
The slotchange event
当插槽中的节点改变时在 HTMLSlotElement 实例（<slot> 元素）上触发。

例子

在 web-components-examples，我们正在构建一些例子。以后会添加更多。

规范

Specification Status Comment
HTML Living Standard
<template> element		 Living Standard The definition of <template>.
HTML Living Standard
custom elements		 Living Standard The definition of HTML Custom Elements.
DOM
shadow trees		 Living Standard The definition of Shadow DOM.
HTML Imports Working Draft Initial HTML Imports definition.
Shadow DOM Obsolete Initial Shadow DOM definition.

浏览器兼容性

通常来说:

  • Firefox(版本63)、Chrome和Opera都默认支持Web组件。
  • Safari支持许多web组件特性，但比上述浏览器少。
  • Edge正在开发一个实现。

要获得特定特性的详细浏览器支持，您必须参考上面列出的参考页面。

另见

  • webcomponents.org — site featuring web components examples, tutorials, and other information.
  • Hybrids — Open source web components library, which favors plain objects and pure functions over class and this syntax. It provides a simple and functional API for creating custom elements.
  • Polymer — Google's web components framework — a set of polyfills, enhancements, and examples. Currently the easiest way to use web components cross-browser.
  • Snuggsi.es — Easy Web Components in ~1kB Including polyfill — All you need is a browser and basic understanding of HTML, CSS, and JavaScript classes to be productive.
  • Slim.js — Open source web components library — a high-performant library for rapid and easy component authoring; extensible and pluggable and cross-framework compatible.
  • Smart.js — Web Components library with simple API for creating cross-browser custom elements.
  • Stencil — Toolchain for building reusable, scalable design systems in web components.