HTMLTemplateElement.shadowRootCustomElementRegistry — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTemplateElement.shadowRootCustomElementRegistry

Beschreibung

Die Eigenschaft shadowRootCustomElementRegistry des Interfaces HTMLTemplateElement ist die gespiegelte (reflektierte) Form des Inhaltsattributs shadowrootcustomelementregistry. Wird sie gelesen, liefert sie den Attributwert; wird sie gesetzt, schreibt sie das Attribut. Lesen und Schreiben über JavaScript entspricht also getAttribute()/setAttribute() für dieses Attribut.

Das Attribut gehört zu den Scoped Custom Element Registries und wirkt nur zusammen mit deklarativem Shadow DOM, also bei einem <template shadowrootmode="open|closed">. Ist es gesetzt, erzeugt der HTML-Parser die Shadow Root mit customElementRegistry === null: Die Shadow Root verwendet dann nicht automatisch die globale Registry (window.customElements). Stattdessen kann man ihr später per CustomElementRegistry.prototype.initialize() eine eigene, mit new CustomElementRegistry() erzeugte Registry zuweisen. Bis dahin bleiben enthaltene Custom Elements unaufgewertet (nicht „upgraded“).

Einsatzfall: Server-gerendertes HTML mit Web-Komponenten, deren Unterelemente in einer eigenen, isolierten Registry definiert werden sollen – etwa um Namenskonflikte zwischen mehreren Komponentenbibliotheken oder Versionen auf derselben Seite zu vermeiden. Maßgeblich ist das Vorhandensein des Attributs beim Parsen; ein nachträgliches Ändern der Eigenschaft beeinflusst bereits erzeugte Shadow Roots nicht.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des Attributs shadowrootcustomelementregistry (üblicherweise ein leerer String, wenn das Attribut ohne Wert gesetzt ist). Beim Setzen wird der Wert als Attribut geschrieben.

Beispiele

Attribut über die Eigenschaft lesen und setzen

const template = document.createElement('template');
template.setAttribute('shadowrootmode', 'open');

// Attribut über die gespiegelte Eigenschaft setzen
template.shadowRootCustomElementRegistry = '';

console.log(template.hasAttribute('shadowrootcustomelementregistry'));
console.log(template.outerHTML);

true <template shadowrootmode="open" shadowrootcustomelementregistry=""></template>

Deklarative Shadow Root mit eigener Registry initialisieren

const host = document.createElement('div');

// setHTMLUnsafe() verarbeitet deklaratives Shadow DOM (innerHTML nicht!)
host.setHTMLUnsafe(`
  <template shadowrootmode="open" shadowrootcustomelementregistry>
    <my-badge></my-badge>
  </template>`);

const shadow = host.shadowRoot;
console.log(shadow.customElementRegistry); // noch keine Registry

// Isolierte Registry nur für diese Shadow Root
const registry = new CustomElementRegistry();
registry.define('my-badge', class extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Scoped!';
  }
});

registry.initialize(shadow);
document.body.append(host);

console.log(shadow.customElementRegistry === registry);
console.log(shadow.querySelector('my-badge').textContent);

null true Scoped!

Feature-Erkennung vor der Nutzung

const supportsScopedRegistry =
  'shadowRootCustomElementRegistry' in HTMLTemplateElement.prototype &&
  typeof CustomElementRegistry.prototype.initialize === 'function';

if (supportsScopedRegistry) {
  console.log('Scoped Custom Element Registries verfügbar');
} else {
  // Fallback: Elemente in der globalen Registry definieren
  console.log('Fallback auf window.customElements');
}

Scoped Custom Element Registries verfügbar (bzw. Fallback-Meldung)

// Wichtig · Fallstricke

Nur beim Parsen wirksam: Das Attribut wird ausschließlich ausgewertet, wenn der HTML-Parser aus dem <template shadowrootmode> eine Shadow Root erzeugt. Ein Setzen der Eigenschaft an einem bereits geparsten oder per createElement() erzeugten Template legt keine Shadow Root an und ändert keine bestehende.
innerHTML reicht nicht: element.innerHTML verarbeitet kein deklaratives Shadow DOM. Nutze Element.prototype.setHTMLUnsafe() bzw. Document.parseHTMLUnsafe() – mit Vorsicht bei nicht vertrauenswürdigen Inhalten (XSS-Risiko, da unsanitisiert).
Ohne initialize() kein Upgrade: Solange der Shadow Root keine Registry zugewiesen wurde (customElementRegistry === null), werden enthaltene Custom Elements nicht aufgewertet – auch nicht durch Definitionen in window.customElements.
Kompatibilität: Sehr neue Funktion (Scoped Custom Element Registries), noch nicht in allen Browsern verfügbar; Firefox unterstützt sie derzeit nicht. Immer per Feature-Erkennung absichern. Nicht unterstützende Browser ignorieren das Attribut und verwenden die globale Registry.
Das imperative Gegenstück ist die Option customElementRegistry in Element.prototype.attachShadow().

Siehe auch

HTMLTemplateElement.shadowRootDelegatesFocus HTMLTemplateElement.shadowRootSlotAssignment HTMLTemplateElement.shadowRootClonable HTMLTemplateElement.shadowRootSerializable HTMLTemplateElement.shadowRootMode