CustomElementRegistry：whenDefined() 方法

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

CustomElementRegistry 接口的 whenDefined() 方法返回一个在具名元素被定义时兑现的 Promise。

语法

js
whenDefined(name)

参数

name

自定义元素的名称。

返回值

一个 Promise，会在使用给定名称定义自定义元素时兑现该自定义元素的构造函数。如果已经定义了给定名称的自定义元素，则 promise 立刻兑现。

如果名称不是有效的自定义元素名，则 promise 会以 SyntaxError DOMException 被拒绝。

示例

此示例使用 whenDefined() 来检测生成菜单的自定义元素何时被定义。这个菜单显示占位符内容一直到菜单内容已经准备好显示。

html
<nav id="menu-container">
  <div class="menu-placeholder">加载中……</div>
  <nav-menu>
    <menu-item>项目 1</menu-item>
    <menu-item>项目 2</menu-item>
    ……
    <menu-item>项目 N</menu-item>
  </nav-menu>
</nav>
js
const container = document.getElementById("menu-container");
const placeholder = container.querySelector(".menu-placeholder");
// 获取菜单中尚未被定义的所有子元素。
const undefinedElements = container.querySelectorAll(":not(:defined)");

async function removePlaceholder() {
  // 过滤出元素的唯一 localName
  const tags = new Set(
    [...undefinedElements].map((button) => button.localName),
  );
  const promises = [...tags].map((tag) => customElements.whenDefined(tag));

  // 等待所有的子元素升级
  await Promise.all(promises);
  // 然后移除占位符
  container.removeChild(placeholder);
}

removePlaceholder();

规范

Specification
HTML Standard
# dom-customelementregistry-whendefined-dev

浏览器兼容性

BCD tables only load in the browser