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

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

原文：/knowledge/crawler-128dad7015d08448fa9d58dd3fb7536c0346b36f34c37932173093fef304a78e

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

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

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

[来源1](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)

## 自定义元素生命周期回调

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

### 核心回调方法

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

### 示例代码

```javascript
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()`。
*   也可以在此回调中实现自定义的移动处理逻辑。

```javascript
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）：**
```javascript
customElements.define("popup-info", PopupInfo);
```

**自定义内置元素（Customized Built-in Element）：**
```javascript
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)`。

### 示例代码

```javascript
// 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](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)
