Benutzerdefinierte Elemente mit eingeschränkten Registrierungen verhalten lassen

Jayson Chen

Patrick Brosset

Veröffentlicht am 9. März 2026

Mit benutzerdefinierten Elementen können Web-App-Entwickler UI-Komponenten mit ihrem eigenen Verhalten erstellen, freigeben und wiederverwenden, was die Entwicklung vereinfacht. Wenn Ihre App jedoch verschiedene Gruppen benutzerdefinierter Elemente zusammenführt, kann es zu Problemen und Namenskonflikten kommen. Registrierungen für benutzerdefinierte Elemente mit Bereichsangabe lösen dieses Problem.

Das Microsoft Edge-Team hat an dieser Funktion gearbeitet und wir freuen uns, bekanntgeben zu können, dass bereichsbezogene benutzerdefinierte Elementregistrierungen jetzt standardmäßig in Edge und Chrome 146 sowie in anderen Chromium-basierten Browsern verfügbar sind. Sie können jetzt benutzerdefinierte Elemente kapseln. Damit wird ein langjähriges Problem für Entwickler von Komponenten- und Micro-Frontend-Bibliotheken behoben.

Registrierungen für benutzerdefinierte Elemente mit Bereich ermöglichen wichtige Muster für Webentwickler. Sie können jetzt mehrere benutzerdefinierte Elementbibliotheken verwenden, die unabhängig voneinander von mehreren Teams entwickelt wurden, oder mehrere Versionen derselben Bibliothek nebeneinander.

Was ist eine benutzerdefinierte Elementregistrierung mit Bereich?

Heute befindet sich jede benutzerdefinierte Elementdefinition auf einer Webseite in einem einzelnen, gemeinsamen Register unter window.customElements. Wenn also zwei verschiedene Bibliotheken versuchen, ein benutzerdefiniertes Element mit demselben Tag-Namen zu definieren, z. B. <my-button>, wird ein Fehler ausgegeben und die Seite wird nicht mehr richtig dargestellt. Das ist ein erhebliches Problem in der realen Welt. Bei großen Anwendungen, deren Benutzeroberflächen aus mehreren Teams, Designsystemen oder Micro-Frontends bestehen, kann es leicht zu Namenskonflikten kommen. Mit benutzerdefinierten Elementregistrierungen mit Bereich wird dieses Problem behoben, da Sie unabhängige Registrierungen erstellen können. Jede Registrierung enthält eigene Definitionen für benutzerdefinierte Elemente, die vollständig von der globalen Registrierung und voneinander isoliert sind.

Neue Registry erstellen

Anstatt jedes benutzerdefinierte Element in der globalen window.customElements-Registrierung zu definieren:

1. Erstellen Sie eine neue Registry, indem Sie new CustomElementRegistry() aufrufen.
2. Weisen Sie der neuen Registry einen bestimmten Bereich zu (siehe Bereich der Registry festlegen).
3. Definieren Sie die Elemente, die in die neue Registrierung aufgenommen werden sollen.

Wenn dann ein benutzerdefiniertes Element verwendet wird, sucht der Browser die Definition des Elements in der zugehörigen Registry nach, die nicht unbedingt die globale ist. Das bedeutet, dass für verschiedene Teile Ihrer Seite völlig unterschiedliche benutzerdefinierte Elementdefinitionen verwendet werden können.

Registrierung eingrenzen

Eine benutzerdefinierte Elementregistrierung kann entweder auf ein Dokument, einen Shadow Root oder ein einzelnes Element beschränkt werden.

Auf einen Shadow-Root beschränken

Wenn Sie ein neues Registry auf einen Shadow-Root beschränken möchten, verwenden Sie die Option customElementRegistry beim Aufrufen der Methode attachShadow(). Alle benutzerdefinierten Elemente, die sich in diesem Shadow-Root befinden, verwenden jetzt die Definition in der entsprechenden registrierten Registrierung:

// Create your custom registry.
const registry = new CustomElementRegistry();
// Define a custom element in the new registry.
registry.define('my-card', class extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from scoped registry!';
  }
});

// Create shadow root, providing it with your new custom element registry.
const host = document.querySelector('#host');
const shadow = host.attachShadow({
  mode: 'open',
  customElementRegistry: registry,
});

shadow.innerHTML = '<my-card></my-card>';

Deklaratives Shadow-DOM

Verwenden Sie das Attribut shadowrootcustomelementregistry für ein <template>-Element, um dem Browser mitzuteilen, dass der resultierende Shadow-Root eine eingeschränkte Registrierung anstelle der globalen verwendet:

<my-host>
  <template shadowrootmode="open" shadowrootcustomelementregistry>
    <my-widget></my-widget>
  </template>
</my-host>

  const registry = new CustomElementRegistry();
  registry.define('my-widget', class extends HTMLElement {
    connectedCallback() { this.textContent = 'Scoped!'; }
  });

  const shadow = document.querySelector('my-host').shadowRoot;
  registry.initialize(shadow);

Wie im Beispiel gezeigt, reserviert das Attribut Speicherplatz für die benutzerdefinierte Elementregistrierung. Der Nutzer muss die Registrierung definieren und initialisieren, um den Schattenstammbereich auf ein getrenntes Dokument zu beschränken.

Sie können ein Register auch auf ein Dokument beschränken, z. B. auf ein Dokument, das von document.implementation.createHTMLDocument() erstellt wurde. So können Sie <template>-Elemente klonen und Dokumente außerhalb des Bildschirms bearbeiten. Jedes Element hat dabei eigene isolierte Sätze von Komponentendefinitionen. Verwenden Sie dazu die Methode CustomElementRegistry.initialize():

// Create a new registry.
const registry = new CustomElementRegistry();
registry.define('app-widget', AppWidget);

// Create a document, and use registry.initialize() to scope the registry to the document.
const doc = document.implementation.createHTMLDocument('');
registry.initialize(doc);

doc.body.innerHTML = '<app-widget></app-widget>';

Auf ein einzelnes Element beschränken

Sie können auch eine Registrierung direkt einem Element und seinem Unterbaum zuordnen, indem Sie die Option customElementRegistry an document.createElement() übergeben. Das Element und seine Nachfolger werden anhand dieser Registry aufgelöst, unabhängig davon, in welchen Teil des DOM sie später eingefügt werden:

// Create a registry and define a custom element in it.
const registry = new CustomElementRegistry();
registry.define('fancy-label', FancyLabel);

// Create a new DOM element and scope the new registry to it.
const el = document.createElement('fancy-input', {
  customElementRegistry: registry,
});

// Use a custom element in the new DOM element.
el.innerHTML = '<fancy-label>Name</fancy-label>';

Weitere Informationen

Weitere Informationen finden Sie in der Edge-Demo und ihrem Quellcode sowie im MDN-Referenzartikel zu CustomElementRegistry.

Dank unserer Zusammenarbeit im Rahmen des Chromium-Projekts sind bereichsbezogene benutzerdefinierte Elementregistrierungen jetzt standardmäßig sowohl in Microsoft Edge als auch in Chrome sowie in anderen Chromium-basierten Browsern aktiviert.

Sie müssen keine Einstellungen aktivieren oder sich für einen Origin Trial registrieren. Sie können die Funktion ab sofort in Chromium-basierten Browsern verwenden.

Wenn Sie diese Funktion in anderen Browsern benötigen, geben Sie dem Problem mit registrierten benutzerdefinierten Elementen mit Bereich eine Upvote-Reaktion und hinterlassen Sie einen Kommentar mit Ihren Anwendungsfällen und Workarounds.

Wenn Sie einen Fehler bei der Implementierung der Funktion in einem Chromium-basierten Browser finden, melden Sie ihn bitte unter crbug.com/new.

Wir hoffen, dass die Verwendung von Webkomponenten durch die Registrierung benutzerdefinierter Elemente mit Bereich einfacher wird.