WebComponents指南

June 23, 2022

tips

兼容性：https://caniuse.com/custom-elementsv1
网址：https://www.webcomponents.org/
网站上面有一些 webComponents 写的组件（npm），和 polyfill 等资源，还是比较实用的
MDN：https://developer.mozilla.org/docs/Web/Web_Components
Standard：https://html.spec.whatwg.org/multipage/custom-elements.html

我们自定义的元素是直接继承 HTMLElement 的，所以根据需要查阅https://developer.mozilla.org/docs/Web/API/HTMLElement

入门

本篇仅介绍 Autonomous custom elements，即直接继承 HTMLElement 类
此类自定义元素可直接作为 html 标签使用，如：<my-element>

class MyElement extends HTMLElement {}
customElements.define("my-element", MyElement);

另一种则是 Customized built-in elements，继承其它特定的 HTML 元素
需要通过 is 属性指定，如：<button is="plastic-button">Click Me!</button>

class PlasticButton extends HTMLButtonElement {}
customElements.define("plastic-button", PlasticButton, { extends: "button" });

定义元素

自定义的元素名称不分大小写，且必须包含连字符-，避免与原生元素冲突。如果我们指定的名称无效，会报 SyntaxError 错误。
标准描述的允许的自定义元素名称：https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
API 参见：https://developer.mozilla.org/docs/Web/API/Window/customElements

customElements.define("my-element", class extends HTMLElement {...}) 后还可以通过 customElements.get('my-element') 获取这个类

CustomElementRegistry 接口向开发者暴露了管理自定义元素的接口，该接口提供全局变量 customElements 暴露

WebComponents 提供了 template 标签，这个元素写在 html 中不会被渲染（相当于 display: none），可以提供给 WebComponents 作为模板。

`:defined` 伪类

CSS 提供伪类 :defined 来表示任何已定义的元素。包括所有浏览器内置标准元素以及已成功定义的自定义元素。

例如

css

my-element:not(:defined) {
}

my-element:defined {
}

upgrade：浏览器将自定义标签从未识别到解析为自定义元素的过程

可以配合 customElements.whenDefined(name) 方法使用。

customElements.whenDefined("my-element").then(() => {
    // my-element is now defined
});

Shadow DOM

Shadow DOM 是独立的 API（指不是和 Custom Element 绑定的 API），允许将隐藏的 DOM 树（Shadow DOM Tree）附加到常规的 DOM 树中。
自定义元素本身是一个常规 DOM 节点。Element.attachShadow() 方法可将一个 Shadow Root 附加至此节点上，此时当前节点就成为一个 Shadow Host。

注意：CustomElement 与 ShadowRoot 及其子节点都是独立的 DOM 节点。

const shadowRoot = element.attachShadow({ mode: "open" });
const shadowRoot = element.attachShadow({ mode: "closed" });

// 如果设置为 open，则元素的 shadowRoot 属性指向该 shadowRoot
console.assert(shadowRoot, element.shadowRoot);

Shadow DOM 与文档的主 DOM 树分开渲染。因此 Shadow DOM 内部的样式表局限在其内部，不会影响外部元素。（除了 :focus-within）

注：样式表包括 <style> 和 <link rel="stylesheet" href="" />

在 Shadow DOM 内部的 <style> 标签内可以通过 :host 选择器表示自身。

CSS scoping

:host 或 :host() 选择器。选中当前自定义元素，参数可用于更具体地选中自定义元素。
:host-context() 选择器。选中当前自定义元素，当且仅当自定义元素是参数所选中的元素的子元素。

例如：

css

:host([data-dark-theme]) {
    display: inline-block;
    color: black;
    background: white;
}

:host-context(body[data-dark-theme]) {
    color: white;
    background: black;
}

注意：自定义元素继承自 HTMLElement，其默认 style 与 HTMLSpanElement 相同（简单来说就是要注意 :host 默认具有 display:inline）

::slotted() 伪元素可用于选中通过插槽（slot）插入 shadow tree 的节点，并设置其样式。

CSS shadow parts

CSS shadow parts 模块定义了 ::part()伪元素，可设置在 shadow host 上。通过这个伪元素可以将 shadow host 的选定元素暴露给外部页面来应用样式。

默认情况下，shadow tree 中的元素只能在自己的 shadow root 内进行样式设置。CSS shadow parts 模块允许在构成自定义元素的 <template> 子元素上包含一个 part 属性，通过 ::part() 伪元素将 shadow tree 节点暴露给外部样式设置。

ShadowRoot 接口还有一些其它属性：如 adoptedStyleSheets 和 styleSheets。
就像 Document 接口的同名属性一样，可以用于操纵样式表
此处不展开说明

插槽

插槽允许将自定义元素中的常规 DOM 节点（myElement.innerHTML）渲染至 ShadowDOM 中（myElement.shadowRoot.innerHTML）

在自定义标签内部的标签，指定 slot 属性为某一插槽名。

html

<my-element>
    <div slot="foo"></div>
    <div slot="foo"></div>
</my-element>

在模板（Shadow DOM）中，用 <slot> 占位标签，指定 name 属性为该插槽名，则渲染时占位标签（在渲染上）替换为所有对应传入的标签（但在实际 DOM 树中的位置不变）。

html

<template>
    <p>example</p>
    <slot name="foo"></slot>
</template>

渲染表现如下

html

<p>example</p>
<slot name="foo">
    <div slot="foo"></div>
    <div slot="foo"></div>
</slot>

上面演示的是具名插槽，如果模板（Shadow DOM）中存在 <slot> 元素而未指定插槽名，则这个插槽被替换为自定义标签内部所有未指定 slot 属性的元素。

其实相当于插槽名为空字符串。未指定 slot="..." 则相当于 slot="" （空字符串）；
而模板中未指定 <slot name="..."> （即<slot>）则相当于<slot name="">（空字符串）。

被插入元素的 Element.assignedSlot 属性返回其插入到的 HTMLSlotElement 元素。
而插槽元素的 HTMLSlotElement.assignedElements({flatten:false/true}) 和 HTMLSlotElement.assignedNodes({flatten:false/true}) 则方法可以分别获取插槽中插入的节点和元素集合

flatten: true 选项可用于拍平一层 slot 嵌套
flatten: true/false 区别的演示，参见此处

插槽中的直接节点（即不包括子节点）改变时（包括第一次插入），插槽元素触发 slotchange

模板（Shadow DOM）中还允许使用 ::slotted() 伪元素选中因插槽插入而渲染的元素（而不是模板中兜底的元素）

生命周期

生命周期函数的顺序如下：

constructor -> attributeChangedCallback -> connectedCallback -> disconnectedCallback -> adoptedCallback -> connectedCallback

constructor：当自定义标签 upgrade 为 custom element 时，被调用（无参数）
connectedCallback：每当 custom element 被插入文档 DOM 时，被调用（无参数）
disconnectedCallback：每当 custom element 从文档 DOM 中删除时，被调用（无参数）
adoptedCallback：每当 custom element 被移动到新的文档时，被调用（例如从主 document 移动到某个 iframe.contentDocument）
attributeChangedCallback: 每当 custom element：change, add, remove, replace 自身 attribute 时，被调用

根据规范，不应该在 constructor 里获取自定义元素（即 this）的 attribute 和子元素（因为在 upgrade 之前，它们根本不存在）

规范建议：

constructor 只用于设置值的初始状态或默认值、设置事件监听器、创建 shadow root
将工作尽可能推迟到 connectedCallback 回调（特别是获取资源和渲染操纵）。但要注意该回调是可以多次触发的，所以对于一些一次性的工作，需要额外的代码来防止多次运行

监听 attribute 变化

只有在静态属性 observedAttributes 数组中声明的 attribute 才能触发 attributeChangedCallback 回调

attributeChangedCallback 对每个变更的 attribute 依次触发，包括直接通过 html 提供的 attribute

/**
 * 注：typescript 没有提供这些生命周期函数的定义
 */
abstract class CustomElement {
    static observedAttributes?: string[];
    constructor() {}
    connectedCallback?(): void;
    disconnectedCallback?(): void;
    attributeChangedCallback?(name: string, oldVal: string | null, newVal: string | null): void;
    adoptedCallback?(oldDocument: Document, newDocument: Document): void;
}

class MyElement implements CustomElement {
    static get observedAttributes() {
        return ["foo", "bar"];
    }
    // 或者：
    // static observedAttributes = ["foo", "bar"];

    attributeChangedCallback(attr: string, oldVal: string | null, newVal: string | null) {
        switch (attr) {
            case "foo":
            // do something with 'foo' attribute

            case "bar":
            // do something with 'bar' attribute
        }
    }
}

注意事项

Event 接口新增 composed 属性和 composedPath 方法
当可冒泡的事件（bubbles 属性为 true）可从 Shadow DOM 传递到一般的 DOM 时
Event.composed 为 true，``Event.composedPath() 则返回一个 EventTarget 对象数组，表示将在其上调用事件侦听器的对象
对于 { mode: "open" }) 的 ShadowRoot，数组可包含其内部子节点，例如： [ p, ShadowRoot, open-shadow, body, html, HTMLDocument
对于 { mode: "close" }) 的 ShadowRoot，数组不含其内部子节点及 ShadowRoot 自身，例如：[ closed-shadow, body, html, HTMLDocument

自定义元素还允许与表单元素集成，参见：https://web.dev/articles/more-capable-form-controls

←Back to home