Web Components

Web Components 是一套不同的技术,允许你创建可重用的自定义元素——其功能封装在代码的其余部分之外——并在你的 Web 应用程序中使用它们。

概念和用法

作为开发者,我们都知道尽可能地重用代码是一个好主意。传统上,对于自定义标记结构来说,这并不容易——想想你有时必须编写的复杂 HTML(以及相关的样式和脚本)来渲染自定义 UI 控件,以及如果不小心,多次使用它们如何使你的页面变得一团糟。

Web Components 旨在解决此类问题——它由三种主要技术组成,这些技术可以一起使用来创建具有封装功能的多功能自定义元素,这些元素可以在任何你想要的地方重用,而无需担心代码冲突。

自定义元素

一组 JavaScript API,允许你定义自定义元素及其行为,然后可以根据需要在你的用户界面中使用。

Shadow DOM

一组 JavaScript API,用于将封装的“影子”DOM 树附加到元素——它与主文档 DOM 分开渲染——并控制相关功能。通过这种方式,你可以将元素的功能保持私有,以便可以对其进行脚本编写和样式化,而无需担心与文档的其他部分发生冲突。

HTML 模板

<template><slot> 元素使你能够编写在渲染页面中不显示的标记模板。然后,可以多次重复使用这些模板作为自定义元素结构的基础。

实现 Web Components 的基本方法通常如下所示

  1. 创建一个类,在其中使用 class 语法指定你的 Web Components 功能。
  2. 使用 CustomElementRegistry.define() 方法注册你的新自定义元素,将要定义的元素名称、指定其功能的类或函数以及可选的继承元素作为参数传递。
  3. 如果需要,使用 Element.attachShadow() 方法将 Shadow DOM 附加到自定义元素。使用常规 DOM 方法将子元素、事件侦听器等添加到 Shadow DOM。
  4. 如果需要,使用 <template><slot> 定义 HTML 模板。同样,使用常规 DOM 方法克隆模板并将其附加到你的 Shadow DOM。
  5. 在页面上的任何位置使用你的自定义元素,就像使用任何常规 HTML 元素一样。

指南

使用自定义元素

本指南展示了如何使用自定义元素的功能创建简单的 Web Components,以及如何查看生命周期回调和一些其他更高级的功能。

使用 Shadow DOM

本指南介绍了 Shadow DOM 的基础知识,展示了如何将 Shadow DOM 附加到元素、添加到 Shadow DOM 树、对其进行样式化等等。

使用模板和插槽

本指南展示了如何使用 <template><slot> 元素定义可重用的 HTML 结构,然后在你的 Web Components 中使用该结构。

参考

自定义元素

CustomElementRegistry

包含与自定义元素相关的功能,最值得注意的是 CustomElementRegistry.define() 方法,用于注册新的自定义元素,以便随后可以在你的文档中使用它们。

Window.customElements

返回对 CustomElementRegistry 对象的引用。

生命周期回调

在自定义元素的类定义中定义的特殊回调函数,它们会影响自定义元素的行为

connectedCallback()

当自定义元素首次连接到文档的 DOM 时调用。

disconnectedCallback()

当自定义元素与文档的 DOM 断开连接时调用。

adoptedCallback()

当自定义元素移动到新文档时调用。

attributeChangedCallback()

当自定义元素的其中一个属性被添加、移除或更改时调用。

用于创建自定义内置元素的扩展

定义了以下扩展

全局 HTML 属性 is

允许你指定标准 HTML 元素应如何表现得像注册的自定义内置元素。

Document.createElement() 方法的“is”选项

允许你创建标准 HTML 元素的实例,该实例的行为类似于给定的注册自定义内置元素。

CSS 伪类

与自定义元素相关的伪类

:defined

匹配任何已定义的元素,包括使用 CustomElementRegistry.define() 定义的内置元素和自定义元素。

:host

选择包含其使用的 CSS 的 Shadow DOM 的影子宿主。

:host()

选择包含其使用的 CSS 的 Shadow DOM 的影子宿主(以便你可以从其 Shadow DOM 内部选择自定义元素)——但前提是作为函数参数给出的选择器与影子宿主匹配。

:host-context()

选择包含其使用的 CSS 的 Shadow DOM 的影子宿主(以便你可以从其 Shadow DOM 内部选择自定义元素)——但前提是作为函数参数给出的选择器与影子宿主在 DOM 层次结构中所处位置的祖先匹配。

:state()

匹配处于指定自定义状态的自定义元素。更准确地说,它匹配匿名自定义元素,其中指定的状态存在于元素的 CustomStateSet 中。

CSS 伪元素

与自定义元素相关的伪元素

::part

表示 影子树 中任何具有匹配 part 属性的元素。

Shadow DOM

ShadowRoot

表示 Shadow DOM 子树的根节点。

Element 扩展

与 Shadow DOM 相关的 Element 接口扩展

  • Element.attachShadow() 方法将 Shadow DOM 树附加到指定的元素。
  • Element.shadowRoot 属性返回附加到指定元素的 Shadow Root,如果未附加 Shadow Root,则返回 null
相关的 Node 添加

与 Shadow DOM 相关的 Node 接口添加

  • Node.getRootNode() 方法返回上下文对象的根,如果可用,则可选地包括 Shadow Root。
  • Node.isConnected 属性返回一个布尔值,指示 Node 是否连接(直接或间接)到上下文对象,例如,在普通 DOM 的情况下为 Document 对象,在 Shadow DOM 的情况下为 ShadowRoot
Event 扩展

与 Shadow DOM 相关的 Event 接口扩展

Event.composed

如果事件将跨 Shadow DOM 边界传播到标准 DOM,则返回 true,否则返回 false

Event.composedPath

返回事件的路径(将在其上调用侦听器的对象)。如果 Shadow Root 是使用 ShadowRoot.mode closed 创建的,则不包括 Shadow 树中的节点。

HTML 模板

<template>

包含在初始加载包含文档时未渲染的 HTML 片段,但可以使用 JavaScript 在运行时显示,主要用作自定义元素结构的基础。关联的 DOM 接口是 HTMLTemplateElement

<slot>

Web Components 内部的占位符,你可以用自己的标记填充它,这让你可以创建单独的 DOM 树并将它们一起呈现。关联的 DOM 接口是 HTMLSlotElement

全局 HTML 属性 slot

将 Shadow DOM 影子树中的插槽分配给元素。

Element.assignedSlot

一个只读属性,返回插入此元素的 <slot> 的引用。

Text.assignedSlot

一个只读属性,返回插入此文本节点的 <slot> 的引用。

Element 扩展

与插槽相关的Element接口扩展

Element.slot

返回附加到元素的 Shadow DOM 插槽的名称。

CSS 伪元素

与插槽相关的伪元素

::slotted

匹配插入到插槽中的任何内容。

The slotchange 事件

当某个插槽中包含的节点发生更改时,在HTMLSlotElement 实例(<slot> 元素)上触发。

示例

我们正在我们的web-components-examples GitHub 仓库中构建许多示例。随着时间的推移,将添加更多内容。

规范

规范
HTML 标准
# the-template-element
DOM 标准
# interface-shadowroot

浏览器兼容性

html.elements.template

BCD 表格仅在浏览器中加载

api.ShadowRoot

BCD 表格仅在浏览器中加载