Document.customElementRegistry — Eigenschaft · JavaScript-Referenz

Signatur

get Document.customElementRegistry

Beschreibung

Die schreibgeschützte Eigenschaft customElementRegistry von Document liefert die Registry für benutzerdefinierte Elemente (Custom Elements), die für dieses Dokument gilt. In dieser Registry wird nachgeschlagen, wenn der Parser oder document.createElement() auf einen Tag-Namen wie <my-button> trifft.

In einem normalen Dokument, das in einem Fenster angezeigt wird, ist das die globale Registry. Die Eigenschaft gibt dann dasselbe Objekt zurück wie window.customElements. Dokumente ohne Browsing-Kontext haben dagegen standardmäßig keine Registry, und die Eigenschaft gibt null zurück. Das betrifft zum Beispiel Dokumente aus document.implementation.createHTMLDocument(), aus DOMParser oder aus XMLHttpRequest. In solchen Dokumenten werden benutzerdefinierte Elemente nicht aktualisiert (upgrade).

Die Eigenschaft gehört zur Funktion Scoped Custom Element Registries. Damit lassen sich mit new CustomElementRegistry() eigene, voneinander getrennte Registries anlegen und an Shadow Roots oder einzelne Elemente binden. So können verschiedene Bibliotheken denselben Tag-Namen verwenden, ohne sich in die Quere zu kommen. document.customElementRegistry zeigt dabei, welche Registry auf Dokumentebene gilt. Element.customElementRegistry und ShadowRoot.customElementRegistry zeigen die Registry eines einzelnen Knotens bzw. einer Shadow Root.

Rückgabewert

Typ

CustomElementRegistry | null

Beschreibung

Die dem Dokument zugeordnete CustomElementRegistry oder null, wenn das Dokument keine Registry hat (z. B. Dokumente ohne Browsing-Kontext).

Beispiele

Globale Registry des aktuellen Dokuments prüfen

// Im Hauptdokument ist das die globale Registry
const registry = document.customElementRegistry;

console.log(registry === window.customElements);
console.log(registry instanceof CustomElementRegistry);

true true

Dokumente ohne Browsing-Kontext haben keine Registry

const fremdesDoc = document.implementation.createHTMLDocument('Vorlage');
console.log(fremdesDoc.customElementRegistry);

const geparst = new DOMParser().parseFromString('<my-card></my-card>', 'text/html');
console.log(geparst.customElementRegistry);
// <my-card> wird hier nicht aktualisiert, auch wenn es global definiert ist
console.log(geparst.querySelector('my-card').constructor.name);

null null HTMLElement

Funktionserkennung mit Rückfall auf window.customElements

// Liefert die Registry, die für das Dokument gilt
const getRegistry = (doc = document) =>
  'customElementRegistry' in doc ? doc.customElementRegistry : window.customElements;

class HelloBadge extends HTMLElement {
  connectedCallback() {
    this.textContent = `Hallo, ${this.getAttribute('name') ?? 'Welt'}!`;
  }
}

const registry = getRegistry();
if (registry && !registry.get('hello-badge')) {
  registry.define('hello-badge', HelloBadge);
}

await registry.whenDefined('hello-badge');
console.log('hello-badge ist bereit');

hello-badge ist bereit

Dokument-Registry mit einer eigenen Shadow-Root-Registry vergleichen

if ('customElementRegistry' in Document.prototype) {
  const lokal = new CustomElementRegistry();
  lokal.define('x-item', class extends HTMLElement {});

  const host = document.createElement('div');
  const shadow = host.attachShadow({ mode: 'open', customElementRegistry: lokal });
  document.body.append(host);

  console.log(shadow.customElementRegistry === lokal);
  console.log(document.customElementRegistry === lokal);
  console.log(document.customElementRegistry.get('x-item'));
}

true false undefined

// Wichtig · Fallstricke

Browserunterstützung: Die Eigenschaft gehört zu den neuen Scoped Custom Element Registries und wird noch nicht überall unterstützt. Prüfe vorher mit 'customElementRegistry' in document, ob sie vorhanden ist, und greife sonst auf window.customElements zurück.
Auf null prüfen: Bei Dokumenten aus DOMParser, createHTMLDocument() oder XMLHttpRequest ist der Wert null. Wer direkt doc.customElementRegistry.define() aufruft, bekommt dann einen TypeError.
Schreibgeschützt: Eine Zuweisung an die Eigenschaft hat keine Wirkung (im strict mode wird ein TypeError ausgelöst). Einem Dokument oder Teilbaum ohne Registry weist du eine Registry mit CustomElementRegistry.prototype.initialize() zu.
Definitionen in einer eigenen Registry (new CustomElementRegistry()) tauchen nicht in document.customElementRegistry auf. Welche Registry für ein Element gilt, zeigt element.customElementRegistry.

Siehe auch

Document.lastElementChild Document.childElementCount Document.firstElementChild Document.implementation Document.rootElement