Signatur
Beschreibung
Die schreibgeschützte Eigenschaft customElementRegistry eines ShadowRoot zeigt an, welche Registry für benutzerdefinierte Elemente innerhalb dieses Shadow-Baums gilt. Sie gehört zur Funktion Scoped Custom Element Registries. Damit können verschiedene Komponenten denselben Tag-Namen (z. B. <my-button>) mit unterschiedlichen Klassen verwenden, ohne sich in der globalen Registry window.customElements gegenseitig in die Quere zu kommen.
Eine eigene Registry legen Sie mit new CustomElementRegistry() an und übergeben sie beim Erzeugen des Shadow Root über element.attachShadow({ mode, customElementRegistry }). Elemente, die danach im Shadow-Baum geparst oder erzeugt werden (z. B. über innerHTML), werden mit dieser Registry aufgewertet (Upgrade). Ohne die Option erbt der Shadow Root die Registry des Dokuments, in der Regel also window.customElements.
Der Wert ist null, wenn für den Shadow Root noch keine Registry festgelegt wurde. Das passiert etwa bei deklarativem Shadow DOM mit dem Attribut shadowrootcustomelementregistry. Mit registry.initialize(shadowRoot) lässt sich eine Registry nachträglich zuweisen. Danach liefert die Eigenschaft dieses Objekt.
Die Eigenschaft hilft vor allem beim Debuggen, bei der Funktionserkennung und in Bibliotheken, die prüfen müssen, in welchem Bereich (Scope) ein Tag-Name aufgelöst wird.
Rückgabewert
CustomElementRegistry: entweder eine eigene, bereichsbezogene Registry, die globale window.customElements oder null, falls keine festgelegt ist.Beispiele
Eigene Registry für einen Shadow Root verwenden
// Eigene Registry nur für diese Komponente
const registry = new CustomElementRegistry();
class FancyButton extends HTMLElement {
connectedCallback() {
this.textContent = 'Fancy!';
}
}
registry.define('my-button', FancyButton);
const host = document.createElement('div');
document.body.append(host);
const shadow = host.attachShadow({ mode: 'open', customElementRegistry: registry });
shadow.innerHTML = '<my-button></my-button>';
console.log(shadow.customElementRegistry === registry);
console.log(shadow.querySelector('my-button') instanceof FancyButton);
// Global ist 'my-button' nicht definiert
console.log(customElements.get('my-button'));Standardfall: globale Registry wird geerbt
const host = document.createElement('section');
const shadow = host.attachShadow({ mode: 'open' });
console.log(shadow.customElementRegistry === window.customElements);Deklaratives Shadow DOM nachträglich initialisieren
// HTML:
// <div id="host">
// <template shadowrootmode="open" shadowrootcustomelementregistry>
// <x-card></x-card>
// </template>
// </div>
const shadow = document.getElementById('host').shadowRoot;
console.log(shadow.customElementRegistry); // noch keine Registry
const registry = new CustomElementRegistry();
registry.define('x-card', class extends HTMLElement {});
registry.initialize(shadow);
console.log(shadow.customElementRegistry === registry);Funktionserkennung mit Rückfall
const supportsScoped =
'customElementRegistry' in ShadowRoot.prototype &&
typeof CustomElementRegistry === 'function' &&
(() => { try { new CustomElementRegistry(); return true; } catch { return false; } })();
const createShadow = (host) => supportsScoped
? host.attachShadow({ mode: 'open', customElementRegistry: new CustomElementRegistry() })
: host.attachShadow({ mode: 'open' }); // Rückfall: globale Registry
const shadow = createShadow(document.createElement('div'));
console.log(supportsScoped, shadow.customElementRegistry);// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung wie
shadow.customElementRegistry = reghat keine Wirkung und löst im Strict Mode einenTypeErroraus. Legen Sie die Registry überattachShadow()fest oder beinullüberCustomElementRegistry.prototype.initialize(). - Browser-Unterstützung: Scoped Custom Element Registries sind neu und noch nicht Baseline. In älteren Browsern fehlt die Eigenschaft (
undefined), undnew CustomElementRegistry()wirft einenTypeError. Prüfen Sie die Unterstützung daher immer vorab oder verwenden Sie ein Polyfill (z. B.@webcomponents/scoped-custom-element-registry). - Prüfen Sie nicht nur auf
undefined: Der Wertnullist in unterstützenden Browsern ein gültiger Zustand und bedeutet „noch keine Registry festgelegt“. - Elemente, die vor dem Festlegen der Registry im Shadow-Baum stehen, bleiben zunächst undefiniert (
:not(:defined)). Sie werden erst aufgewertet, wenn eine passende Definition verfügbar ist. document.createElement()verwendet ohne Option die Registry des Dokuments. Für bereichsbezogene Elemente gibt es die Option{ customElementRegistry }, oder Sie erzeugen die Elemente perinnerHTMLdirekt im Shadow Root.