CustomElementRegistry.whenDefined()

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

構文

Promise<> customElements.whenDefined(name);

引数

name
カスタムエレメントの名前。

返り値

カスタムエレメントが定義されたとき、Promiseundefined に解決します。カスタムエレメントがすでに定義済みであった場合、promise は即座に解決されます。

例外

例外 説明
SyntaxError 与えられた名前が有効なカスタムエレメントの名前出ない場合、promise は SyntaxError で reject します。

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

<nav id="menu-container">
  <div class="menu-placeholder">読み込み中...</div>
  <nav-menu>
    <menu-item>Item 1</menu-item>
    <menu-item>Item 2</menu-item>
     ...
    <menu-item>Item N</menu-item>
  </nav-menu>
</nav>
const container = document.getElementById('menu-container');
const placeholder = container.querySelector('.menu-placeholder');
// まだ定義されていないメニューの子供を取得する
const undefinedElements = container.querySelectorAll(':not(:defined)');

const promises = [...undefinedElements].map(
  button => customElements.whenDefined(button.localName)
);

// すべての子供が更新されるまで待ち、
// プレースホルダーを削除する。
await Promise.all(promises);
container.removeChild(placeholder);

仕様

仕様 状態 コメント
HTML Living Standard
customElements.whenDefined() の定義
現行の標準 初期定義

ブラウザ互換性

BCD tables only load in the browser