Web Components 核心机制与自定义元素生命周期详解

本文档详细解析了 Web Components 的核心机制,重点介绍了自定义元素(Custom Elements)的生命周期回调(connectedCallback, disconnectedCallback, adoptedCallback, attributeChangedCallback)及其在 DOM 移动时的行为差异,特别是新增的 connectedMoveCallback 用于状态保持。文档还涵盖了自定义元素的注册方法(包括自主元素与自定义内置元素的区别)、作用域自定义元素注册表(Scoped Registries)的创建与使用以解决名称冲突,以及通过 Shadow DOM 和 HTML 模板构建可复用组件的示例实现。

READ

Web Components 是一套允许开发者创建可复用自定义元素的技术集合,其核心机制包括自定义元素(Custom Elements)、Shadow DOM 和 HTML 模板(HTML Templates)。

  • 自定义元素:通过 JavaScript API 定义自定义元素及其行为。
  • Shadow DOM:将封装的“影子”DOM 树附加到元素上,保持样式和 ID 的私有性,避免与文档其他部分冲突。
  • HTML 模板:使用 <template> 和 <slot> 元素编写不立即显示的标记模板,作为自定义元素结构的基础。

基本实现流程包括:创建包含功能的类、使用 CustomElementRegistry.define() 注册元素、可选地附加 Shadow DOM 以及定义 HTML 模板。

来源1

自定义元素生命周期回调

自定义元素在注册后,浏览器会在特定交互时调用类中的生命周期回调方法。开发者可以通过实现这些方法来响应元素状态变化。

核心回调方法

  • connectedCallback():每次元素添加到文档时调用。规范建议尽可能在此回调中实现自定义元素的初始化,而非在构造函数中。
  • disconnectedCallback():每次元素从文档中移除时调用。
  • adoptedCallback():每次元素移动到新的文档时调用。
  • attributeChangedCallback(name, oldValue, newValue):当元素的属性被添加、移除、更改或替换时调用。需配合 static observedAttributes 数组使用。

示例代码

class MyCustomElement extends HTMLElement {
  static observedAttributes = ["color", "size"];

  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);

构造函数限制

在构造函数中,可以设置初始状态、默认值、注册事件监听器或创建 Shadow Root。但此时不应检查元素的属性或子节点,也不应添加新的属性或子节点。

状态保持的移动:connectedMoveCallback

当自定义元素在 DOM 中移动时(例如通过 Element.moveBefore() 或 Node.insertBefore()),通常会触发 disconnectedCallback() 和 connectedCallback()。如果这些回调用于初始化或清理代码,移动操作可能导致状态问题(如意外删除仍需要的数据)。

解决方案

定义 connectedMoveCallback() 生命周期回调。当使用 Element.moveBefore() 移动元素时,浏览器将调用 connectedMoveCallback() 而不是 connectedCallback() 和 disconnectedCallback()。

  • 如果希望完全阻止移动时的连接/断开回调,可以定义一个空的 connectedMoveCallback()。
  • 也可以在此回调中实现自定义的移动处理逻辑。
class MyComponent {
  connectedMoveCallback() {
    console.log("Custom move-handling logic here.");
  }
}

注意:connectedMoveCallback 仅在通过 Element.moveBefore() 移动元素时触发,其他移动方法(如 insertBefore)仍会触发标准的连接/断开回调。

注册自定义元素

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

参数说明

  • name:元素名称。必须以小写字母开头,包含连字符(-),并符合规范中定义的合法名称规则。
  • constructor:自定义元素的构造函数。
  • options(可选):仅用于“自定义内置元素”(Customized Built-in Elements)。包含 extends 属性,指定要扩展的内置元素名称。

注册示例

自主自定义元素(Autonomous Custom Element):

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

自定义内置元素(Customized Built-in Element):

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

使用方式

  • 自主元素:像标准 HTML 元素一样直接使用标签名,如 <popup-info>。
  • 自定义内置元素:使用标准元素标签,并通过 is 属性指定自定义元素名称,如 <p is="word-count">。

作用域自定义元素注册表(Scoped Custom Element Registries)

全局注册表(Window.customElements)要求所有自定义元素名称在全页范围内唯一。当多个库可能定义同名元素时,会产生冲突。作用域注册表允许为特定的 DOM 子树(如 Shadow Root)创建独立的注册表,解决名称冲突问题。

创建与关联

  1. 创建注册表:使用 new CustomElementRegistry() 创建。
  2. 注册元素:在作用域注册表上使用 define() 方法。
  3. 关联到 Shadow Root:
    • 创建时关联:在 Element.attachShadow() 的选项中传入 customElementRegistry。
    • 创建后关联:调用 CustomElementRegistry.initialize(shadowRoot)。

示例代码

// 1. 创建作用域注册表
const myRegistry = new CustomElementRegistry();

myRegistry.define(
  "my-element",
  class extends HTMLElement {
    connectedCallback() {
      this.textContent = "Hello from scoped registry!";
    }
  }
);

// 2. 创建宿主元素并关联注册表
const host = document.createElement("div");
document.body.appendChild(host);

const shadow = host.attachShadow({
  mode: "open",
  customElementRegistry: myRegistry,
});

// 3. 在 Shadow DOM 中使用自定义元素
shadow.innerHTML = "<my-element></my-element>";

限制

作用域注册表不支持 extends 选项(即不能用于创建自定义内置元素)。尝试使用会抛出 NotSupportedError。

实现示例:自主自定义元素

以下示例展示了一个名为 <popup-info> 的自主自定义元素。它接受 img 和 data-text 属性,显示图标,并在图标聚焦时弹出信息框。

关键实现步骤

  1. 继承 HTMLElement:定义类 PopupInfo。
  2. connectedCallback 中构建 DOM:
    • 附加 Shadow Root (attachShadow)。
    • 创建内部结构(wrapper, icon, info, img)。
    • 读取属性 (getAttribute) 并设置内容。
    • 创建并附加 <style> 元素定义 Shadow DOM 样式。
  3. 注册元素:调用 customElements.define("popup-info", PopupInfo)。

样式与外部资源

  • 内部样式:直接在 connectedCallback 中创建 <style> 元素并插入 Shadow DOM。
  • 外部样式:可创建 <link> 元素并插入 Shadow DOM。注意 <link> 不会阻塞 Shadow Root 的绘制,可能导致短暂未样式化内容(FOUC)。现代浏览器对共享或相同文本的 <style> 标签有性能优化,使得内部样式性能与外部样式相近。

自定义内置元素示例

示例展示了扩展 <ul> 元素创建 <expanding-list> 的实现。该类继承 HTMLUListElement,在 connectedCallback 中查询子元素,为包含嵌套 <ul> 的 <li> 添加点击事件以切换显示状态,并修改 DOM 结构以支持交互。

来源2

Conversation

评论

正在加载评论