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.

whenDefined() は CustomElementRegistry インターフェイスのメソッドで、指定した名前の要素が定義されたときに解決されるプロミス (Promise) を返します。

構文

js
customElements.whenDefined(name): Promise<CustomElementConstructor>;

引数

name

カスタム要素の名前。

返値

指定された名前のカスタム要素が定義された時に、カスタム要素のコンストラクターで履行されるプロミス (Promise) です。（そのようなカスタム要素が既に定義されている場合、返されるプロミスは直ちに履行されます。）

例外

例外 説明
SyntaxError 指定された名前が有効なカスタム要素名でなかった場合、プロミスは SyntaxError で拒否されます。

例

以下の例では、 whenDefined() を用いてメニューを生成するカスタム要素が定義されたタイミングを検出しています。実際にメニューコンテンツの表示準備が完了するまでは、メニューはプレースホルダーのコンテンツを表示します。

html
<nav id="menu-container">
  <div class="menu-placeholder">Loading...</div>
  <nav-menu>
    <menu-item>Item 1</menu-item>
    <menu-item>Item 2</menu-item>
    ...
    <menu-item>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() {
  const promises = [...undefinedElements].map((button) =>
    customElements.whenDefined(button.localName),
  );

  // すべての子がアップグレードされるまで待つ
  await Promise.all(promises);
  // それからプレースホルダーを削除
  container.removeChild(placeholder);
}

removePlaceholder();

仕様書

Specification
HTML
# dom-customelementregistry-whendefined-dev

ブラウザーの互換性