CustomElementRegistry: upgrade() Methode

Syntax

upgrade(root)

Parameter

root

Eine Node-Instanz mit schattenhaltigen Nachfahr-Elementen, die aktualisiert werden sollen. Wenn es keine nachrüstbaren Nachfahr-Elemente gibt, wird kein Fehler geworfen.

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 noch nicht mit der entsprechenden CustomElementRegistry registriert wurde, existiert das Element als ein undefiniertes, einfaches HTMLElement. Es sieht aus und verhält sich wie jedes unbekannte Element — es hat kein spezielles Verhalten, keine Lebenszyklus-Callbacks oder benutzerdefinierten Prototyp-Methoden.

Upgraden ist der Prozess des nachträglichen Hochstufens eines solchen Elements zu einem vollwertigen benutzerdefinierten Element, sobald seine Definition verfügbar wird. Wenn ein Element aktualisiert wird:

1. Sein Prototyp wird auf die registrierte benutzerdefinierte Elementklasse umgestellt, die mit define() registriert wurde.
2. Sein connectedCallback() und alle anderen anwendbaren Lebenszyklus-Callbacks werden aufgerufen.
3. Wenn die Klasse observedAttributes definiert, wird für jedes Attribut, das bereits einen Wert hat, der attributeChangedCallback() aufgerufen.

Normalerweise werden Elemente automatisch aufgerüstet, wenn ihre Definition über define() registriert wird, aber 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-Unterbaum existieren (z. B. Elemente, die über Document.createElement() erstellt oder in einen 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