CustomElementRegistry: upgrade()-Methode

Syntax

upgrade(root)

Parameter

root

Eine Node-Instanz mit untergeordneten Elementen mit Shadow DOM, die aktualisiert werden sollen. Wenn keine untergeordneten Elemente 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 Tag-Namen verwenden, der einem benutzerdefinierten Element entspricht (z. B. <my-element>). Wenn die Klasse des benutzerdefinierten Elements zum Zeitpunkt der Erstellung noch nicht in der entsprechenden CustomElementRegistry registriert ist, liegt das Element als undefiniertes, einfaches HTMLElement vor. Es sieht aus und verhält sich wie jedes unbekannte Element – ohne besonderes Verhalten, Lifecycle-Callbacks oder benutzerdefinierte Prototypmethoden.

Bei der Aktualisierung wird ein solches Element nachträglich zu einem vollwertigen benutzerdefinierten Element, sobald seine Definition verfügbar ist. Wenn ein Element aktualisiert wird:

1. Sein Konstruktor wird aufgerufen. Darin weist der Aufruf von super() dem Element den Prototyp der mit define() registrierten Klasse des benutzerdefinierten Elements zu.
2. Wenn die Klasse observedAttributes definiert, wird attributeChangedCallback() für jedes Attribut aufgerufen, das bereits einen Wert hat.
3. Wenn das Element bereits verbunden ist, wird sein connectedCallback() aufgerufen.
4. Die Callbacks formAssociatedCallback() und/oder formDisabledCallback() werden aufgerufen, wenn die jeweiligen Bedingungen erfüllt sind.

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

Beispiele

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