Web Components

Konzepte und Verwendung

Als Entwickler wissen wir, dass es sinnvoll ist, Code so oft wie möglich wiederzuverwenden. Bei benutzerdefinierten Markup-Strukturen war das traditionell nicht so einfach: Denken Sie an das komplexe HTML samt zugehörigen Styles und Skripten, das Sie möglicherweise schon schreiben mussten, um eigene UI-Steuerelemente darzustellen. Wenn Sie diese mehrfach verwenden, kann Ihre Seite schnell unübersichtlich werden.

Web Components sollen solche Probleme lösen. Sie bestehen aus drei zentralen Technologien, die sich kombinieren lassen, um vielseitige benutzerdefinierte Elemente mit gekapselter Funktionalität zu erstellen. Diese können mit geringerem Risiko von Namens- und Styling-Konflikten wiederverwendet werden:

Benutzerdefinierte Elemente (Custom Elements)

Eine Reihe von JavaScript-APIs, mit denen Sie benutzerdefinierte Elemente und deren Verhalten definieren können, um sie anschließend nach Bedarf in Ihrer Benutzeroberfläche zu verwenden.

Shadow DOM

Ein Mechanismus, mit dem Sie einem Element einen gekapselten „Shadow“-DOM-Baum zuordnen können – entweder imperativ über JavaScript-APIs oder deklarativ in HTML. Dadurch können Sie die Eigenschaften eines Elements kapseln, sodass seine Styles und IDs nicht mit anderen Teilen des Dokuments kollidieren.

HTML-Templates

Mit den Elementen <template> und <slot> können Sie Markup-Vorlagen schreiben, die auf der gerenderten Seite nicht angezeigt werden. Diese lassen sich dann mehrfach als Grundlage für die Struktur eines benutzerdefinierten Elements verwenden.

Die grundlegende Vorgehensweise bei der Implementierung einer Web Component sieht in der Regel ungefähr so aus:

1. Erstellen Sie mithilfe der Klassensyntax eine Klasse, in der Sie die Funktionalität Ihrer Web Component festlegen.
2. Registrieren Sie Ihr neues benutzerdefiniertes Element mit der Methode CustomElementRegistry.define(). Übergeben Sie dabei den zu definierenden Elementnamen, die Klasse oder Funktion, in der seine Funktionalität festgelegt ist, und optional das Element, von dem es erbt. Sie können es über Window.customElements in der globalen Registry registrieren oder mit dem Konstruktor CustomElementRegistry() eine Registry mit begrenztem Gültigkeitsbereich erstellen, um Namenskonflikte zwischen Komponenten zu vermeiden.
3. Ordnen Sie dem benutzerdefinierten Element bei Bedarf mit der Methode Element.attachShadow() ein Shadow DOM zu. Fügen Sie dem Shadow DOM mit den üblichen DOM-Methoden Kindelemente, Event-Listener und Ähnliches hinzu.
4. Definieren Sie bei Bedarf ein HTML-Template mit <template> und <slot>. Verwenden Sie wieder die üblichen DOM-Methoden, um das Template zu klonen und Ihrem Shadow DOM hinzuzufügen.
5. Verwenden Sie Ihr benutzerdefiniertes Element an beliebiger Stelle auf Ihrer Seite, genau wie jedes andere HTML-Element.

Referenz

Benutzerdefinierte Elemente

CustomElementRegistry

Enthält Funktionen für benutzerdefinierte Elemente, insbesondere die Methode CustomElementRegistry.define(). Mit ihr werden neue benutzerdefinierte Elemente registriert, damit sie anschließend im Dokument verwendet werden können. Mit dem Konstruktor CustomElementRegistry() können Sie Registries mit begrenztem Gültigkeitsbereich erstellen. Die Methode CustomElementRegistry.initialize() verknüpft eine solche Registry mit einem DOM-Teilbaum.

Window.customElements

Gibt eine Referenz auf das globale CustomElementRegistry-Objekt zurück.

Document.customElementRegistry

Die dem Dokument zugeordnete CustomElementRegistry.

Element.customElementRegistry

Die dem Element zugeordnete CustomElementRegistry.

Lebenszyklus-Callbacks

Spezielle Callback-Funktionen, die innerhalb der Klassendefinition eines benutzerdefinierten Elements definiert werden und dessen Verhalten beeinflussen:

connectedCallback()

Wird aufgerufen, wenn das benutzerdefinierte Element erstmals mit dem DOM des Dokuments verbunden wird.

disconnectedCallback()

Wird aufgerufen, wenn das benutzerdefinierte Element vom DOM des Dokuments getrennt wird.

adoptedCallback()

Wird aufgerufen, wenn das benutzerdefinierte Element in ein neues Dokument verschoben wird.

attributeChangedCallback()

Wird aufgerufen, wenn eines der Attribute des benutzerdefinierten Elements hinzugefügt, entfernt oder geändert wird.

Erweiterungen zum Erstellen angepasster integrierter Elemente

Die folgenden Erweiterungen sind definiert:

Das globale HTML-Attribut is

Damit können Sie festlegen, dass sich ein Standard-HTML-Element wie ein registriertes angepasstes integriertes Element verhalten soll.

Die Option „is“ der Methode Document.createElement()

Damit können Sie eine Instanz eines Standard-HTML-Elements erstellen, die sich wie ein bestimmtes registriertes angepasstes integriertes Element verhält.

CSS-Pseudoklassen

Pseudoklassen, die sich speziell auf benutzerdefinierte Elemente beziehen:

:defined

Trifft auf jedes definierte Element zu, einschließlich integrierter Elemente und mit CustomElementRegistry.define() definierter benutzerdefinierter Elemente.

:host

Wählt den Shadow-Host des Shadow DOM aus, in dem sich das verwendete CSS befindet.

:host()

Wählt den Shadow-Host des Shadow DOM aus, in dem sich das verwendete CSS befindet. So können Sie ein benutzerdefiniertes Element aus dessen Shadow DOM heraus auswählen – allerdings nur, wenn der als Funktionsparameter angegebene Selektor auf den Shadow-Host zutrifft.

:host-context()

Wählt den Shadow-Host des Shadow DOM aus, in dem sich das verwendete CSS befindet. So können Sie ein benutzerdefiniertes Element aus dessen Shadow DOM heraus auswählen – allerdings nur, wenn der als Funktionsparameter angegebene Selektor auf einen Vorfahren des Shadow-Hosts an dessen Position in der DOM-Hierarchie zutrifft.

:state()

Trifft auf benutzerdefinierte Elemente zu, die sich in einem angegebenen benutzerdefinierten Zustand befinden. Genauer gesagt trifft sie auf anonyme benutzerdefinierte Elemente zu, bei denen der angegebene Zustand im CustomStateSet des Elements vorhanden ist.

CSS-Pseudoelemente

Pseudoelemente, die sich speziell auf benutzerdefinierte Elemente beziehen:

::part

Repräsentiert jedes Element innerhalb eines Shadow-Baums, das ein passendes part-Attribut besitzt.

Shadow DOM

ShadowRoot

Repräsentiert den Wurzelknoten eines Shadow-DOM-Teilbaums.

ShadowRoot.customElementRegistry

Die der Shadow-Root zugeordnete CustomElementRegistry. Sie kann über die Option customElementRegistry von Element.attachShadow() oder später mit CustomElementRegistry.initialize() festgelegt werden.

Erweiterungen von Element

Erweiterungen des Element-Interfaces im Zusammenhang mit Shadow DOM:

• Die Methode Element.attachShadow() ordnet dem angegebenen Element einen Shadow-DOM-Baum zu.
• Die Eigenschaft Element.shadowRoot gibt die dem angegebenen Element zugeordnete Shadow-Root zurück oder null, wenn keine Shadow-Root zugeordnet ist.

Relevante Ergänzungen zu Node

Ergänzungen des Node-Interfaces, die für Shadow DOM relevant sind:

• Die Methode Node.getRootNode() gibt die Wurzel des Kontextobjekts zurück und schließt dabei optional die Shadow-Root ein, falls eine vorhanden ist.
• Die Eigenschaft Node.isConnected gibt einen booleschen Wert zurück, der angibt, ob der Node direkt oder indirekt mit dem Kontextobjekt verbunden ist – beispielsweise mit dem Document-Objekt im normalen DOM oder mit der ShadowRoot in einem Shadow DOM.

Erweiterungen von Event

Erweiterungen des Event-Interfaces im Zusammenhang mit Shadow DOM:

Event.composed

Gibt true zurück, wenn sich das Event über die Grenze des Shadow DOM hinweg in das normale DOM ausbreitet, andernfalls false.

Event.composedPath

Gibt den Pfad des Events zurück, also die Objekte, auf denen Listener aufgerufen werden. Knoten in Shadow-Bäumen sind nicht enthalten, wenn die Shadow-Root mit dem Modus ShadowRoot.mode „closed“ erstellt wurde.

HTML-Templates

<template>

Enthält ein HTML-Fragment, das beim erstmaligen Laden des umgebenden Dokuments nicht gerendert wird, aber zur Laufzeit mit JavaScript angezeigt werden kann. Es wird hauptsächlich als Grundlage für die Struktur benutzerdefinierter Elemente verwendet. Das zugehörige DOM-Interface ist HTMLTemplateElement.

<slot>

Ein Platzhalter innerhalb einer Web Component, den Sie mit eigenem Markup füllen können. Dadurch lassen sich getrennte DOM-Bäume erstellen und gemeinsam darstellen. Das zugehörige DOM-Interface ist HTMLSlotElement.

Das globale HTML-Attribut slot

Weist einem Element einen Slot in einem Shadow-DOM-Baum zu.

Element.assignedSlot

Ein schreibgeschütztes Attribut, das eine Referenz auf das <slot> zurückgibt, in das dieses Element eingefügt ist.

Text.assignedSlot

Ein schreibgeschütztes Attribut, das eine Referenz auf das <slot> zurückgibt, in das dieser Textknoten eingefügt ist.

Erweiterungen von Element

Erweiterungen des Element-Interfaces im Zusammenhang mit Slots:

Element.slot

Gibt den Namen des Shadow-DOM-Slots zurück, der dem Element zugewiesen ist.

CSS-Pseudoelemente

Pseudoelemente, die sich speziell auf Slots beziehen:

::slotted

Trifft auf Inhalte zu, die in einen Slot eingefügt sind.

Das Event slotchange

Wird auf einer HTMLSlotElement-Instanz (einem <slot>-Element) ausgelöst, wenn sich die in diesem Slot enthaltenen Knoten ändern.

Leitfäden

Benutzerdefinierte Elemente verwenden

Ein Leitfaden, der zeigt, wie Sie mit den Funktionen benutzerdefinierter Elemente einfache Web Components erstellen. Er behandelt außerdem Lebenszyklus-Callbacks und einige weitere fortgeschrittene Funktionen.

Shadow DOM verwenden

Ein Leitfaden zu den Grundlagen von Shadow DOM. Er zeigt unter anderem, wie Sie einem Element ein Shadow DOM zuordnen, dem Shadow-DOM-Baum Inhalte hinzufügen und ihn gestalten.

Templates und Slots verwenden

Ein Leitfaden, der zeigt, wie Sie mit den Elementen <template> und <slot> eine wiederverwendbare HTML-Struktur definieren und diese anschließend in Ihren Web Components verwenden.

Beispiele

In unserem GitHub-Repository web-components-examples sammeln wir Beispiele. Im Laufe der Zeit werden weitere hinzukommen.

Spezifikationen

Browser-Kompatibilität

html.elements.template

api.ShadowRoot