使用自定义元素

Web 组件的关键功能之一是能够创建自定义元素：即由 Web 开发人员定义行为的 HTML 元素，扩展了浏览器中可用的元素集。

本文介绍了自定义元素，并介绍了一些示例。

自定义元素类型

有两种类型的自定义元素

定制的内置元素继承自标准 HTML 元素，例如 HTMLImageElement 或 HTMLParagraphElement。它们的实现扩展了标准元素的某些实例的行为。

注意：请参阅 is 属性引用，了解自定义内置元素实现实际情况的注意事项。
自主自定义元素继承自 HTML 元素基类 HTMLElement。您必须从头开始实现其行为。

实现自定义元素

自定义元素实现为类，它扩展了 HTMLElement（对于自主元素）或您要定制的接口（对于定制的内置元素）。

以下是定制 <p> 元素的最小自定义元素的实现

class WordCount extends HTMLParagraphElement {
  constructor() {
    super();
  }
  // Element functionality written in here
}

以下是最小自主自定义元素的实现

class PopupInfo extends HTMLElement {
  constructor() {
    super();
  }
  // Element functionality written in here
}

在类构造函数中，您可以设置初始状态和默认值，注册事件监听器，并可能创建 Shadow DOM。此时，您不应该检查元素的属性或子元素，也不应该添加新的属性或子元素。有关构造函数和反应的完整要求集，请参阅自定义元素构造函数和反应的要求。

自定义元素生命周期回调

注册自定义元素后，浏览器将在页面中的代码以特定方式与您的自定义元素交互时调用您类的某些方法。通过提供这些方法的实现（规范称之为生命周期回调），您可以在响应这些事件时运行代码。

自定义元素生命周期回调包括

connectedCallback()：每次将元素添加到文档中时调用。规范建议，开发者应尽可能在该回调中实现自定义元素设置，而不是在构造函数中。
disconnectedCallback()：每次将元素从文档中移除时调用。
adoptedCallback()：每次将元素移动到新文档时调用。
attributeChangedCallback()：更改、添加、删除或替换属性时调用。有关此回调的更多详细信息，请参阅响应属性更改。

以下是一个记录这些生命周期事件的最小自定义元素

// Create a class for the element
class MyCustomElement extends HTMLElement {
  static observedAttributes = ["color", "size"];

  constructor() {
    // Always call super first in constructor
    super();
  }

  connectedCallback() {
    console.log("Custom element added to page.");
  }

  disconnectedCallback() {
    console.log("Custom element removed from page.");
  }

  adoptedCallback() {
    console.log("Custom element moved to new page.");
  }

  attributeChangedCallback(name, oldValue, newValue) {
    console.log(`Attribute ${name} has changed.`);
  }
}

customElements.define("my-custom-element", MyCustomElement);

注册自定义元素

要使自定义元素在页面中可用，请调用 define() 方法 Window.customElements。

define() 方法采用以下参数

name: 元素的名称。此名称必须以小写字母开头，包含连字符，并满足规范中列出的其他一些规则有效名称定义。
constructor: 自定义元素的构造函数。
options: 仅包含在定制的内置元素中，这是一个包含单个属性 extends 的对象，它是一个字符串，命名要扩展的内置元素。

例如，此代码注册了 WordCount 定制的内置元素

customElements.define("word-count", WordCount, { extends: "p" });

此代码注册了 PopupInfo 自主自定义元素

customElements.define("popup-info", PopupInfo);

使用自定义元素

定义并注册自定义元素后，您可以在代码中使用它。

要使用定制的内置元素，请使用内置元素，但将自定义名称作为 is 属性的值

html

<p is="word-count"></p>

要使用自主自定义元素，请像使用内置 HTML 元素一样使用自定义名称

html

<popup-info>
  <!-- content of the element -->
</popup-info>

响应属性更改

与内置元素一样，自定义元素可以使用 HTML 属性来配置元素的行为。要有效地使用属性，元素必须能够响应属性值的更改。为此，自定义元素需要将以下成员添加到实现自定义元素的类中

一个名为 observedAttributes 的静态属性。这必须是一个数组，包含元素需要更改通知的所有属性的名称。
attributeChangedCallback() 生命周期回调的实现。

每次添加、修改、删除或替换其名称在元素的 observedAttributes 属性中列出的属性时，就会调用 attributeChangedCallback() 回调。

回调传递三个参数

已更改的属性的名称。
属性的旧值。
属性的新值。

例如，此自主元素将观察 size 属性，并在更改时记录旧值和新值

// Create a class for the element
class MyCustomElement extends HTMLElement {
  static observedAttributes = ["size"];

  constructor() {
    super();
  }

  attributeChangedCallback(name, oldValue, newValue) {
    console.log(
      `Attribute ${name} has changed from ${oldValue} to ${newValue}.`,
    );
  }
}

customElements.define("my-custom-element", MyCustomElement);

请注意，如果元素的 HTML 声明包含观察到的属性，则 attributeChangedCallback() 将在属性初始化后被调用，即在第一次解析元素的声明时被调用。因此，在以下示例中，即使属性从未再次更改，attributeChangedCallback() 也会在解析 DOM 时被调用

html

<my-custom-element size="100"></my-custom-element>

有关显示 attributeChangedCallback() 用法的完整示例，请参阅本页中的生命周期回调。

自定义状态和自定义状态伪类 CSS 选择器

内置 HTML 元素可以具有不同的状态，例如“悬停”、“禁用”和“只读”。其中一些状态可以通过使用 HTML 或 JavaScript 作为属性设置，而另一些则是内部的，无法设置。无论是外部还是内部，这些状态通常都有对应的 CSS 伪类，可用于在元素处于特定状态时选择和设置其样式。

自主自定义元素（但不是基于内置元素的元素）也允许您定义状态并使用 :state() 伪类函数选择它们。以下代码展示了如何使用具有内部状态“collapsed”的自主自定义元素的示例来实现这一点。

collapsed 状态表示为一个布尔属性（具有 setter 和 getter 方法），它在元素外部不可见。为了使此状态在 CSS 中可选择，自定义元素首先在构造函数中调用 HTMLElement.attachInternals() 以附加一个 ElementInternals 对象，该对象反过来通过 ElementInternals.states 属性提供对 CustomStateSet 的访问。当状态为 true 时，（内部）折叠状态的 setter 将标识符 hidden 添加到 CustomStateSet 中，当状态为 false 时，将其移除。标识符只是一个字符串：在本例中，我们将其称为 hidden，但我们也可以将其称为 collapsed。

class MyCustomElement extends HTMLElement {
  constructor() {
    super();
    this._internals = this.attachInternals();
  }

  get collapsed() {
    return this._internals.states.has("hidden");
  }

  set collapsed(flag) {
    if (flag) {
      // Existence of identifier corresponds to "true"
      this._internals.states.add("hidden");
    } else {
      // Absence of identifier corresponds to "false"
      this._internals.states.delete("hidden");
    }
  }
}

// Register the custom element
customElements.define("my-custom-element", MyCustomElement);

我们可以使用添加到自定义元素的 CustomStateSet（this._internals.states）中的标识符来匹配元素的自定义状态。通过将标识符传递给 :state() 伪类，可以匹配此标识符。例如，在下面，我们选择 hidden 状态为 true（因此元素的 collapsed 状态）使用 :hidden 选择器，并删除边框。

css

my-custom-element {
  border: dashed red;
}
my-custom-element:state(hidden) {
  border: none;
}

:state() 伪类也可以在 :host() 伪类函数中使用，以匹配自定义元素的 Shadow DOM 内部的自定义状态自定义元素的 Shadow DOM 中的自定义状态。此外，:state() 伪类可以在 ::part() 伪元素之后使用，以匹配处于特定状态的自定义元素的 Shadow DOM 部分。

在 CustomStateSet 中有几个实时示例，展示了如何实现这一点。

示例

在本指南的其余部分，我们将介绍一些自定义元素示例。您可以在 web-components-examples 代码库中找到所有这些示例（以及更多示例）的源代码，并可以在 https://mdn.github.io/web-components-examples/ 上查看所有示例的实时运行。

自主自定义元素

首先，我们将介绍一个自主自定义元素。<popup-info> 自定义元素接受图像图标和文本字符串作为属性，并将图标嵌入到页面中。当图标获得焦点时，它会在弹出信息框中显示文本，以提供更多上下文信息。

首先，JavaScript 文件定义了一个名为 PopupInfo 的类，它扩展了 HTMLElement 类。

// Create a class for the element
class PopupInfo extends HTMLElement {
  constructor() {
    // Always call super first in constructor
    super();
  }

  connectedCallback() {
    // Create a shadow root
    const shadow = this.attachShadow({ mode: "open" });

    // Create spans
    const wrapper = document.createElement("span");
    wrapper.setAttribute("class", "wrapper");

    const icon = document.createElement("span");
    icon.setAttribute("class", "icon");
    icon.setAttribute("tabindex", 0);

    const info = document.createElement("span");
    info.setAttribute("class", "info");

    // Take attribute content and put it inside the info span
    const text = this.getAttribute("data-text");
    info.textContent = text;

    // Insert icon
    let imgUrl;
    if (this.hasAttribute("img")) {
      imgUrl = this.getAttribute("img");
    } else {
      imgUrl = "img/default.png";
    }

    const img = document.createElement("img");
    img.src = imgUrl;
    icon.appendChild(img);

    // Create some CSS to apply to the shadow dom
    const style = document.createElement("style");
    console.log(style.isConnected);

    style.textContent = `
      .wrapper {
        position: relative;
      }

      .info {
        font-size: 0.8rem;
        width: 200px;
        display: inline-block;
        border: 1px solid black;
        padding: 10px;
        background: white;
        border-radius: 10px;
        opacity: 0;
        transition: 0.6s all;
        position: absolute;
        bottom: 20px;
        left: 10px;
        z-index: 3;
      }

      img {
        width: 1.2rem;
      }

      .icon:hover + .info, .icon:focus + .info {
        opacity: 1;
      }
    `;

    // Attach the created elements to the shadow dom
    shadow.appendChild(style);
    console.log(style.isConnected);
    shadow.appendChild(wrapper);
    wrapper.appendChild(icon);
    wrapper.appendChild(info);
  }
}

类定义包含类的 constructor()，它始终以调用 super() 开始，以确保建立正确的原型链。

在 connectedCallback() 方法内部，我们定义了元素连接到 DOM 后将具有的所有功能。在本例中，我们将一个影子根附加到自定义元素，使用一些 DOM 操作来创建元素的内部影子 DOM 结构（然后将其附加到影子根），最后将一些 CSS 附加到影子根以对其进行样式化。我们不会在构造函数中完成这项工作，因为元素的属性在连接到 DOM 之前是不可用的。

最后，我们使用前面提到的 define() 方法在 CustomElementRegistry 中注册我们的自定义元素——在参数中，我们指定元素名称，然后指定定义其功能的类名。

customElements.define("popup-info", PopupInfo);

现在可以在我们的页面上使用它。在 HTML 中，我们像这样使用它：

html

<popup-info
  img="img/alt.png"
  data-text="Your card validation code (CVC)
  is an extra security feature — it is the last 3 or 4 numbers on the
  back of your card."></popup-info>

引用外部样式

在上面的示例中，我们使用 <style> 元素将样式应用于影子 DOM，但您可以使用 <link> 元素引用外部样式表。在本例中，我们将修改 <popup-info> 自定义元素以使用外部样式表。

以下是类定义：

// Create a class for the element
class PopupInfo extends HTMLElement {
  constructor() {
    // Always call super first in constructor
    super();
  }

  connectedCallback() {
    // Create a shadow root
    const shadow = this.attachShadow({ mode: "open" });

    // Create spans
    const wrapper = document.createElement("span");
    wrapper.setAttribute("class", "wrapper");

    const icon = document.createElement("span");
    icon.setAttribute("class", "icon");
    icon.setAttribute("tabindex", 0);

    const info = document.createElement("span");
    info.setAttribute("class", "info");

    // Take attribute content and put it inside the info span
    const text = this.getAttribute("data-text");
    info.textContent = text;

    // Insert icon
    let imgUrl;
    if (this.hasAttribute("img")) {
      imgUrl = this.getAttribute("img");
    } else {
      imgUrl = "img/default.png";
    }

    const img = document.createElement("img");
    img.src = imgUrl;
    icon.appendChild(img);

    // Apply external styles to the shadow dom
    const linkElem = document.createElement("link");
    linkElem.setAttribute("rel", "stylesheet");
    linkElem.setAttribute("href", "style.css");

    // Attach the created elements to the shadow dom
    shadow.appendChild(linkElem);
    shadow.appendChild(wrapper);
    wrapper.appendChild(icon);
    wrapper.appendChild(info);
  }
}

它与原始 <popup-info> 示例相同，只是我们使用 <link> 元素链接到外部样式表，我们将其添加到影子 DOM 中。

请注意，<link> 元素不会阻止影子根的绘制，因此在样式表加载时可能会出现未样式化内容的闪烁 (FOUC)。

许多现代浏览器为 <style> 标签实现了优化，这些标签要么是从公共节点克隆的，要么具有相同的文本，以允许它们共享单个后备样式表。使用此优化，外部和内部样式的性能应该相似。

自定义内置元素

现在，让我们看看自定义内置元素示例。此示例扩展了内置的 <ul> 元素，以支持扩展和折叠列表项。

注意：请参阅 is 属性引用，了解自定义内置元素实现实际情况的注意事项。

首先，我们定义元素的类：

// Create a class for the element
class ExpandingList extends HTMLUListElement {
  constructor() {
    // Always call super first in constructor
    // Return value from super() is a reference to this element
    self = super();
  }

  connectedCallback() {
    // Get ul and li elements that are a child of this custom ul element
    // li elements can be containers if they have uls within them
    const uls = Array.from(self.querySelectorAll("ul"));
    const lis = Array.from(self.querySelectorAll("li"));
    // Hide all child uls
    // These lists will be shown when the user clicks a higher level container
    uls.forEach((ul) => {
      ul.style.display = "none";
    });

    // Look through each li element in the ul
    lis.forEach((li) => {
      // If this li has a ul as a child, decorate it and add a click handler
      if (li.querySelectorAll("ul").length > 0) {
        // Add an attribute which can be used  by the style
        // to show an open or closed icon
        li.setAttribute("class", "closed");

        // Wrap the li element's text in a new span element
        // so we can assign style and event handlers to the span
        const childText = li.childNodes[0];
        const newSpan = document.createElement("span");

        // Copy text from li to span, set cursor style
        newSpan.textContent = childText.textContent;
        newSpan.style.cursor = "pointer";

        // Add click handler to this span
        newSpan.addEventListener("click", (e) => {
          // next sibling to the span should be the ul
          const nextul = e.target.nextElementSibling;

          // Toggle visible state and update class attribute on ul
          if (nextul.style.display == "block") {
            nextul.style.display = "none";
            nextul.parentNode.setAttribute("class", "closed");
          } else {
            nextul.style.display = "block";
            nextul.parentNode.setAttribute("class", "open");
          }
        });
        // Add the span and remove the bare text node from the li
        childText.parentNode.insertBefore(newSpan, childText);
        childText.parentNode.removeChild(childText);
      }
    });
  }
}

请注意，这次我们扩展了 HTMLUListElement，而不是 HTMLElement。这意味着我们获得了列表的默认行为，只需要实现我们自己的自定义项。

与以前一样，大部分代码都在 connectedCallback() 生命周期回调中。

接下来，我们使用 define() 方法注册元素，如前所述，只是这次它还包含一个选项对象，该对象详细说明了自定义元素继承自哪个元素：

customElements.define("expanding-list", ExpandingList, { extends: "ul" });

在 Web 文档中使用内置元素也略有不同：

html

<ul is="expanding-list">
  …
</ul>

您像往常一样使用 <ul> 元素，但在 is 属性中指定自定义元素的名称。

请注意，在这种情况下，我们必须确保定义自定义元素的脚本在 DOM 完全解析后执行，因为 connectedCallback() 在扩展列表添加到 DOM 后立即被调用，此时其子元素尚未添加，因此 querySelectorAll() 调用将找不到任何项。确保这一点的一种方法是将 defer 属性添加到包含脚本的行：

html

<script src="main.js" defer></script>

生命周期回调

到目前为止，我们只看到一个生命周期回调在起作用：connectedCallback()。在最后的示例 <custom-square> 中，我们将看到其他一些回调。<custom-square> 自主自定义元素绘制一个正方形，其大小和颜色由两个属性决定，名为 "size" 和 "color"。

在类构造函数中，我们将一个影子 DOM 附加到元素，然后将空的 <div> 和 <style> 元素附加到影子根：

constructor() {
  // Always call super first in constructor
  super();

  const shadow = this.attachShadow({ mode: "open" });

  const div = document.createElement("div");
  const style = document.createElement("style");
  shadow.appendChild(style);
  shadow.appendChild(div);
}

此示例中的关键函数是 updateStyle()——它接受一个元素，获取其影子根，找到其 <style> 元素，并将 width、height 和 background-color 添加到样式中。

function updateStyle(elem) {
  const shadow = elem.shadowRoot;
  shadow.querySelector("style").textContent = `
    div {
      width: ${elem.getAttribute("size")}px;
      height: ${elem.getAttribute("size")}px;
      background-color: ${elem.getAttribute("color")};
    }
  `;
}

实际更新由生命周期回调处理。connectedCallback() 每次元素添加到 DOM 时都会运行——在这里，我们运行 updateStyle() 函数以确保正方形的样式如其属性中定义的那样。

connectedCallback() {
  console.log("Custom square element added to page.");
  updateStyle(this);
}

disconnectedCallback() 和 adoptedCallback() 回调将消息记录到控制台，以通知我们元素何时从 DOM 中删除或移动到其他页面。

disconnectedCallback() {
  console.log("Custom square element removed from page.");
}

adoptedCallback() {
  console.log("Custom square element moved to new page.");
}

attributeChangedCallback() 回调在元素的某个属性以某种方式更改时运行。从其参数可以看出，可以单独作用于属性，查看它们的名称以及旧值和新值。但是，在本例中，我们只是再次运行 updateStyle() 函数，以确保正方形的样式根据新值更新。

attributeChangedCallback(name, oldValue, newValue) {
  console.log("Custom square element attributes changed.");
  updateStyle(this);
}

请注意，要使 attributeChangedCallback() 回调在属性更改时触发，您必须观察这些属性。这是通过在自定义元素类中指定 static get observedAttributes() 方法来完成的——这应该返回一个数组，其中包含要观察的属性的名称。

static get observedAttributes() {
  return ["color", "size"];
}