大网数据广告活动
Web 标准与前端开发

CustomElementRegistry: initialize() method

· 52CE 我爱测

The **`initialize()`** method of the CustomElementRegistry interface associates this registry with a DOM subtree, setting the Element.customElementRegistry of each inclusive descendant that doesn't already have one, and attempting to upgrade any custom elements found.

Web Components

The initialize() method of the CustomElementRegistry interface associates this registry with a DOM subtree, setting the Element.customElementRegistry of each inclusive descendant that doesn't already have one, and attempting to upgrade any custom elements found.

Syntax

initialize(root)

Parameters

  • root
    • : A Node object (typically a Document, ShadowRoot, or Element) whose inclusive descendants will be associated with this registry.

Return value

None (undefined).

Exceptions

  • NotSupportedError DOMException
    • : Thrown if this CustomElementRegistry is not scoped (i.e., not created with new CustomElementRegistry()) and either root is a Document node or root's node document's Document.customElementRegistry is not this CustomElementRegistry.

Description

When initialize() is called, it walks through the inclusive descendants of root in tree order. For each element (or Document/ShadowRoot at the root) that has a null Element.customElementRegistry, it sets that registry to this CustomElementRegistry. It then attempts to upgrade each element whose customElementRegistry matches this registry.

Once a node's customElementRegistry is set to a CustomElementRegistry object, it cannot be changed. This means initialize() can only set the registry on nodes where it is still null. However, it will still attempt to upgrade any element whose customElementRegistry already matches this registry, not just elements that were freshly assigned.

Nodes have a null custom element registry in several situations, including:

  • Documents created by DOMImplementation.createHTMLDocument(), whose custom element registry is null by default. Elements created within such documents also have null registries.
  • Shadow roots created with customElementRegistry set to null via Element.attachShadow().
  • Declarative shadow roots created from a template element with the shadowrootcustomelementregistry attribute, which instructs the HTML parser to leave the shadow root's custom element registry as null.

Examples

Initializing a shadow root with a scoped registry

This example creates a shadow root without a custom element registry, adds HTML containing a custom element, and then calls initialize() to associate a scoped registry. The <my-element> element is upgraded when initialize() sets the registry on the shadow root and its descendants.

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

const host = document.createElement("div");
document.body.appendChild(host);

// Create the shadow DOM structure without a registry
const shadow = host.attachShadow({
  mode: "open",
  customElementRegistry: null,
});
shadow.innerHTML = "<my-element></my-element>";

// Later, associate the scoped registry and upgrade custom elements
myRegistry.initialize(shadow);

console.log(shadow.querySelector("my-element").textContent);
// "Hello from scoped registry!"

Specifications

Browser compatibility

See also

  • Using custom elements
  • CustomElementRegistry.CustomElementRegistry() constructor
  • CustomElementRegistry.define()
  • CustomElementRegistry.upgrade()

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。