CustomElementRegistry: upgrade()-Methode

Syntax

upgrade(root)

Parameter

root

Eine Node-Instanz mit schattenbaumhaltigen Nachfahrenelementen, die aktualisiert werden sollen. Wenn es keine Nachfahrenelemente gibt, die aktualisiert werden können, wird kein Fehler ausgelöst.

Rückgabewert

Keiner (undefined).

Beschreibung

Wenn ein HTML-Element geparst oder erstellt wird, kann es einen Tagnamen verwenden, der einem benutzerdefinierten Element entspricht (z. B. <my-element>). Wenn die Klasse des benutzerdefinierten Elements zum Zeitpunkt der Erstellung des Elements noch nicht bei der entsprechenden CustomElementRegistry registriert wurde, existiert das Element als undefiniertes, einfaches HTMLElement. Es sieht aus und verhält sich wie jedes unbekannte Element — es verfügt über kein spezielles Verhalten, keine Lebenszyklus-Callbacks und keine benutzerdefinierten Prototypmethoden.

Aktualisierung ist der Prozess, ein solches Element rückwirkend zu einem vollwertigen benutzerdefinierten Element hochzustufen, sobald seine Definition verfügbar wird. Wenn ein Element aktualisiert wird:

1. Sein Prototyp wird gegen die Klasse des benutzerdefinierten Elements ausgetauscht, die mit define() registriert wurde.
2. Sein connectedCallback() sowie alle anderen zutreffenden Lebenszyklus-Callbacks werden aufgerufen.
3. Wenn die Klasse observedAttributes definiert, wird der attributeChangedCallback() für jedes Attribut aufgerufen, das bereits einen Wert hat.

Normalerweise werden Elemente automatisch aktualisiert, wenn ihre Definition über define() registriert wird, jedoch nur, wenn sie bereits mit dem Dokument verbunden sind. Die upgrade()-Methode ist nützlich, wenn Sie Elemente aktualisieren müssen, die in einem getrennten DOM-Teilbaum existieren (zum Beispiel Elemente, die über Document.createElement() erstellt oder in ein DocumentFragment geparst wurden), bevor sie in das Dokument eingefügt werden.

Beispiele

Übernommen aus der HTML-Spezifikation:

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

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

console.assert(!(el instanceof SpiderMan)); // not yet upgraded

customElements.upgrade(el);
console.assert(el instanceof SpiderMan); // upgraded!

Spezifikationen

Browser-Kompatibilität