CustomElementRegistry: upgrade() メソッド

Baseline 広く利用可能

この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2020年1月以降、すべてのブラウザーで利用可能です。

もっと詳しく
完全な互換性情報を見る

upgrade() は CustomElementRegistry インターフェイスのメソッドで、 Node サブツリー内のすべてのシャドウを含むカスタム要素を、メイン文書に接続する前であってもアップグレードします。

構文

upgrade(root)

引数

root: アップグレードする、シャドウを含む子孫要素を持つ Node インスタンス。アップグレード可能な子孫要素がない場合、エラーは発生しません。

HTML 要素が構文解析または作成される際、カスタム要素に対応するタグ名（例: <my-element>）が使用されることがあります。要素が作成された時点で、そのカスタム要素のクラスが適切な CustomElementRegistry にまだ登録されていない場合、その要素は未定義の単純な HTMLElement として存在します。これは、他の未知の要素と同様に表示され、動作します。特別な動作やライフサイクルコールバック、独自のプロトタイプメソッドを持たないからです。

アップグレードとは、そのような要素の定義が利用できるようになった時点で、その要素を遡及的に本格的な独自の要素に昇格させるプロセスです。要素がアップグレードされると、次のようになります。

プロトタイプが、define() で登録されたカスタム要素のクラスに置き換えられます。
その connectedCallback() およびその他の適切なライフサイクルコールバックが呼び出されます。
クラスが observedAttributes を定義している場合、すでに値が示されているそれぞれの属性について、attributeChangedCallback() が呼び出されます。

通常、要素は define() を通じて定義が登録されると自動的にアップグレードされますが、これはその要素がすでに文書に接続されている場合に限られます。upgrade() メソッドは、文書に挿入される前に、接続されていない DOM サブツリー内にある要素（例えば、Document.createElement() によって作成された要素や、DocumentFragment の中に構文解析された要素など）をアップグレードする必要がある場合に役立ちます。

例

HTML 仕様書から取りました。

const el = document.createElement("spider-man");

class SpiderMan extends HTMLElement {}
customElements.define("spider-man", SpiderMan);

console.assert(!(el instanceof SpiderMan)); // まだアップグレードされていない

customElements.upgrade(el);
console.assert(el instanceof SpiderMan); // アップグレードされた