Web & Entwicklung

Web Components: Erstellen Sie wiederverwendbare UI-Komponenten mit Vanilla JavaScript

Web Components: Build Reusable UI Components with Vanilla JavaScript

Lernen Sie Web Components Schritt für Schritt, indem Sie eine wiederverwendbare UI-Karte mit Custom Elements, Shadow DOM, HTML Templates, Slots und JavaScript-Modulen erstellen. Kein Framework oder Build-Tools erforderlich.

Web Components: Wiederverwendbare UI-Komponenten mit Vanilla JavaScript erstellen

Stellen Sie sich vor, Sie erstellen eine Karte für Ihre Website und verwenden sie dann in einem WordPress-Thema, einer Joomla-Erweiterung oder einer eigenständigen Anwendung, ohne sie für jede Umgebung neu schreiben zu müssen.

Das versprechen Web Components: browsernative Tools zum Erstellen wiederverwendbarer HTML-Elemente. Für das Beispiel, das wir bauen werden, sind kein React, Vue, npm-Pakete oder Bundler erforderlich.

Am Ende dieses Tutorials haben Sie eine funktionierende <ui-card>-Komponente mit anpassbarem Content, isolierten Styles, einer Featured-Variante, einem Schließen-Button und einem öffentlichen Event. Wir bauen sie in kleinen Schritten, damit Sie sehen können, welche Technologie jeweils beiträgt.

Was Sie bauen werden

Unsere fertige Komponente unterstützt dieses HTML:

<ui-card variant="featured">
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

Visuelles Vorschau — Standard- und Featured-Karten

<div style="padding:16px;border:1px solid #dce3ec;border-radius:14px;background:#f8fafc;margin:16px 0"> <div style="padding:20px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin-bottom:12px"> <strong style="display:block;margin-bottom:6px">Standard-Karte</strong> <span>Diese Karte verwendet das Standard-Design.</span> </div> <div style="padding:20px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Featured-Karte</strong> <span>Diese Karte hat ein hervorgehobenes Design.</span> </div> </div>

Diese Vorschau ist das Design-Ziel, kein Screenshot einer无关 Bibliothek. Wir reproduzieren es mit dem unten stehenden Code.

1. Verstehen der vier Bausteine

Custom Elements ermöglichen es uns, ein neues HTML-Tag und sein JavaScript-Verhalten zu registrieren. Shadow DOM gibt dem Element seinen eigenen internen DOM und gestaltete Styles. HTML-Templates und Slots ermöglichen es uns, die Struktur wiederverzuverwenden, während wir unterschiedlichen Content in jede Instanz einfügen. ES Modules ermöglichen es uns, die Komponente aus einer normalen JavaScript-Datei zu laden.

Das sind separate Funktionen. Ein Custom Element muss nicht Shadow DOM verwenden, und ein Framework ist für keine der Funktionen erforderlich.

2. Erstellen der Projektdateien

Erstellen Sie diese Struktur in Ihrem Editor:

web-components-demo/
├── index.html
├── components/
│   └── ui-card.js
└── css/
    └── main.css

Legen Sie dies in index.html:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Web Components Demo</title>
  <link rel="stylesheet" href="./css/main.css">
  <script type="module" src="./components/ui-card.js"></script>
</head>
<body>
  <main class="container">
    <h1>Reusable UI Components</h1>
    <p>Let's build a reusable card without a framework.</p>
    <ui-card></ui-card>
  </main>
</body>
</html>

Fügen Sie die Styles auf Page-Ebene zu css/main.css:

body {
  margin: 0;
  background: #f4f6f9;
  color: #1f2937;
  font-family: system-ui, sans-serif;
}
.container {
  max-width: 900px;
  margin: 60px auto;
  padding: 0 20px;
}
ui-card {
  display: block;
  margin-top: 24px;
}

Starten Sie einen lokalen HTTP-Server im Projektverzeichnis, z. B.:

python -m http.server 8000

Besuchen Sie http://localhost:8000. Die Überschrift erscheint, aber die Karte hat noch keinen sichtbaren Inhalt. Verwenden Sie einen HTTP-Server, anstatt index.html mit file:// zu öffnen: Die Regeln für das Laden von Modulen im Browser können Datei-Importe auf lokaler Ebene blockieren.

3. Registrieren Ihres ersten Custom Elements

Erstellen Sie components/ui-card.js:

class UiCard extends HTMLElement {
  connectedCallback() {
    this.textContent = 'Hello from a Web Component!';
  }
}

customElements.define('ui-card', UiCard);

Aktualisieren Sie die Seite. Sie sollten jetzt sehen:

Erwartetes Ergebnis — Schritt 3

Hallo von einem Web Component!

HTMLElement liefert normales DOM-Verhalten. connectedCallback() läuft, wenn das Element an das Dokument angehängt wird. customElements.define() verbindet die Klasse mit dem HTML-Tag.

Der Bindestrich in ui-card ist für autonome Custom-Element-Names erforderlich. Der Callback kann erneut ausgeführt werden, wenn das Element entfernt und wieder eingefügt wird, was wichtig ist, wenn wir Initialisierungslogik hinzufügen.

4. Der Karte ein eigenes Design mit Shadow DOM geben

Ersetzen Sie ui-card.js mit:

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });

    shadow.innerHTML = `
      <style>
        article {
          padding: 24px;
          background: white;
          border: 1px solid #dce3ec;
          border-radius: 12px;
        }
        h2 {
          margin: 0 0 12px;
          color: #2563eb;
        }
      </style>
      <article>
        <h2>My reusable card</h2>
        <p>This content lives inside Shadow DOM.</p>
      </article>
    `;
  }
}

customElements.define('ui-card', UiCard);

Erwartetes Ergebnis — Schritt 4

<div style="padding:22px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin:16px 0"> <strong style="display:block;color:#2563eb;font-size:20px;margin-bottom:10px">Meine wiederverwendbare Karte</strong> Dieser Inhalt lebt im Shadow DOM. </div>

Öffnen Sie DevTools, inspizieren Sie <ui-card>, und erweitern Sie #shadow-root (open). Sie werden den internen Article und Stylesheet sehen.

Im Gegensatz zu normalen Dokument-Selektoren erreichen globale CSS-Regeln wie article { border: none } diesen Shadow-Baum normalerweise nicht. Vererbte Eigenschaften und CSS-Custom Properties können immer noch die Grenze überschreiten. Shadow DOM encapsulates presentation; es ist kein Sicherheits-Sandbox.

Die if (this.shadowRoot)-Prüfung verhindert das Anhängen einer zweiten Shadow-Root, wenn das Element erneut verbunden wird.

Illustration of the article's main concept

5. Trennung des Layouts mit einem HTML-Template

Das Einbetten alles in connectedCallback() wird unhandlich, sobald die Komponente wächst. Definieren wir die Markierung einmal und klonen sie für jede Karte.

Ersetzen Sie die Datei mit:

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 {
      margin: 0 0 12px;
      color: #2563eb;
    }
  </style>
  <article>
    <h2>My reusable card</h2>
    <p>Created from an HTML template.</p>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('ui-card', UiCard);

template.content ist ein Dokument-Fragment. cloneNode(true) kopiert die gesamte Struktur in jeden Schattenbaum der Karte. Das Template selbst wird nicht gerendert, bis wir es klonen und einfügen.

Diese Version sieht fast identisch aus. Die Verbesserung ist architektonisch: Ein Template kann viele Instanzen bedienen.

6. Einführen unterschiedlicher Inhalte mit Slots

Eine wiederverwendbare Karte ist nützlich, wenn jede Instanz dieselbe Überschrift hat. Ersetzen Sie nur die Template-Deklaration am Anfang von ui-card.js mit dem Folgenden; behalten Sie die Klasse und Registrierung aus Schritt 5 bei.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    article {
      padding: 24px;
      background: white;
      border: 1px solid #dce3ec;
      border-radius: 12px;
    }
    h2 { margin: 0 0 12px; color: #2563eb; }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
  </style>
  <article>
    <h2><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

Ersetzen Sie nun <ui-card></ui-card> in index.html:

<ui-card>
  <span slot="title">Learn Web Components</span>
  <p>Build reusable interfaces with native JavaScript.</p>
  <a slot="action" href="/tutorial">Read the tutorial</a>
</ui-card>

Erwartetes Ergebnis — Schritt 6

<div style="padding:22px;border:1px solid #dce3ec;border-radius:12px;background:#fff;margin:16px 0"> <strong style="display:block;color:#2563eb;font-size:20px;margin-bottom:10px">Web Components lernen</strong> <p style="margin:0 0 12px">Wiederverwendbare Oberflächen mit native JavaScript erstellen.</p> <span style="color:#2563eb;font-weight:600">Das Tutorial lesen</span> </div>

Der benannte Slot erhält das Element mit slot="title". Der unbenannte Slot erhält den Absatz. Der Action-Slot erhält den Link. Ein Slot's Fallback-Text erscheint, wenn nichts zugewiesen wird.

Das Layout lebt in der Komponente; die tatsächlichen Worte und Links bleiben im HTML der Seite. Dies ist besonders nützlich für CMS-Inhalte. Ersetzen Sie /tutorial mit einer echten Ziel-Adresse in Ihrem Projekt.

7. Erstellen einer Featured-Variante mit CSS

Fügen Sie Innerhalb des <style>-Blocks der Vorlage Folgendes hinzu:

:host {
  display: block;
}
:host([variant="featured"]) article {
  background: #eff6ff;
  border-color: #93c5fd;
}

Ersetzen Sie dann die einzelne Karte in index.html durch zwei Karten:

<ui-card>
  <span slot="title">Standard card</span>
  <p>This card uses the default appearance.</p>
</ui-card>

<ui-card variant="featured">
  <span slot="title">Featured card</span>
  <p>This card has a highlighted appearance.</p>
</ui-card>

Erwartetes Ergebnis — Schritt 7

<div style="padding:12px;border:1px solid #e2e8f0;border-radius:14px;background:#fafafa;margin:16px 0"> <div style="padding:18px;border:1px solid #dce3ec;border-radius:12px;background:white;margin-bottom:12px"> <strong style="display:block;margin-bottom:6px">Standard-Karte</strong> Diese Karte verwendet das Standard-Design. </div> <div style="padding:18px;border:1px solid #93c5fd;border-radius:12px;background:#eff6ff"> <strong style="display:block;color:#1d4ed8;margin-bottom:6px">Featured-Karte</strong> Diese Karte hat ein hervorgehobenes Design. </div> </div>

Dies ist eine besonders nützliche Funktion von :host(): Es stylt die Komponente basierend auf Attributen des Custom-Elements. Wenn JavaScript variant später ändert, aktualisiert CSS automatisch. Kein attributeChangedCallback() wird für eine rein CSS-getriebene Änderung benötigt.

8. Hinzufügen eines Schließen-Buttons und eines öffentlichen Events

Lassen Sie die Karte interaktiv werden. Innerhalb des Template's <article> fügen Sie diesen Button vor der Überschrift hinzu:

<button class="dismiss" type="button" aria-label="Dismiss card">
  ×
</button>

Fügen Sie diese Regeln zum CSS des Templates hinzu:

article { position: relative; }
.dismiss {
  position: absolute;
  top: 12px;
  right: 12px;
  width: 32px;
  height: 32px;
  border: 0;
  border-radius: 6px;
  background: transparent;
  color: #475569;
  font-size: 24px;
  cursor: pointer;
}
.dismiss:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

Ersetzen Sie connectedCallback() in der Klasse mit:

connectedCallback() {
  if (this.shadowRoot) return;

  const shadow = this.attachShadow({ mode: 'open' });
  shadow.appendChild(template.content.cloneNode(true));

  shadow.querySelector('.dismiss').addEventListener('click', () => {
    this.dispatchEvent(new CustomEvent('card-dismissed', {
      bubbles: true,
      composed: true
    }));
    this.remove();
  });
}

In index.html fügen Sie dieses Script vor </body> hinzu:

<script type="module">
  document.addEventListener('card-dismissed', () => {
    console.log('A card was dismissed.');
  });
</script>

Öffnen Sie die Browser-Konsole und klicken Sie ×. Die Karte verschwindet und die Konsole zeigt die Nachricht.

Das Event bietet einen öffentlichen Integrationspunkt: Die umgebende Anwendung braucht nichts über den internen Button der Karte zu wissen. bubbles lässt das Event bubblen; composed erlaubt das Überschreiten einer Shadow-Grenze, wo applicable. Hier stammt das Event auf dem Host-Element selbst.

9. Komplettversion: Kopieren und verwenden

Technical workflow illustration

Sie können jetzt den gesamten Inhalt von components/ui-card.js mit dieser konsolidierten Version ersetzen. Sie fügt CSS-Anpassungen und exportierte Parts hinzu, während sie das Verhalten der vorherigen Schritte beibehält.

const template = document.createElement('template');

template.innerHTML = `
  <style>
    :host {
      display: block;
      color: #1f2937;
      font-family: system-ui, sans-serif;
    }
    article {
      position: relative;
      box-sizing: border-box;
      padding: 24px;
      background: var(--card-background, #fff);
      border: 1px solid var(--card-border, #dce3ec);
      border-radius: 12px;
    }
    :host([variant="featured"]) article {
      background: var(--card-featured-background, #eff6ff);
      border-color: var(--card-featured-border, #93c5fd);
    }
    h2 {
      margin: 0 36px 12px 0;
      color: var(--card-title-color, #2563eb);
      font-size: 1.25rem;
    }
    .content { line-height: 1.6; }
    .action { margin-top: 16px; }
    .dismiss {
      position: absolute;
      top: 12px;
      right: 12px;
      width: 32px;
      height: 32px;
      border: 0;
      border-radius: 6px;
      background: transparent;
      color: #475569;
      font-size: 24px;
      cursor: pointer;
    }
    .dismiss:hover { background: rgba(0, 0, 0, 0.06); }
    .dismiss:focus-visible {
      outline: 2px solid #2563eb;
      outline-offset: 2px;
    }
  </style>
  <article part="container">
    <button class="dismiss" type="button"
            aria-label="Dismiss card">×</button>
    <h2 part="title"><slot name="title">Untitled card</slot></h2>
    <div class="content"><slot></slot></div>
    <div class="action"><slot name="action"></slot></div>
  </article>
`;

class UiCard extends HTMLElement {
  connectedCallback() {
    if (this.shadowRoot) return;

    const shadow = this.attachShadow({ mode: 'open' });
    shadow.appendChild(template.content.cloneNode(true));

    shadow.querySelector('.dismiss').addEventListener('click', () => {
      this.dispatchEvent(new CustomEvent('card-dismissed', {
        bubbles: true,
        composed: true,
        detail: {
          variant: this.getAttribute('variant') || 'default'
        }
      }));
      this.remove();
    });
  }
}

if (!customElements.get('ui-card')) {
  customElements.define('ui-card', UiCard);
}

Im Gegensatz zu einem schnellen Demo versucht diese Version nicht, den Shadow Root zweimal anzuhängen, fügt keinen unvertrauenswürdigen Inhalt mit innerHTML ein und basiert nicht auf einem Framework. Der Template-String ist developer-kontrolliert; interpolieren Sie niemals unvertrauenswürdige Benutzer-Eingaben in ihn.

10. Stil von der hostenden Website

Shadow DOM ist nicht dafür gedacht, Anpassungen unmöglich zu machen. Es ermutigt Sie, eine bewusste Styling-Schnittstelle zu definieren.

In css/main.css fügen Sie Folgendes hinzu:

ui-card {
  --card-border: #cbd5e1;
  --card-title-color: #0f766e;
}
ui-card::part(container) {
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
}

Die Custom Properties werden von dem Shadow-Baum geerbt und kontrollieren die Werte, die wir exponiert haben. Das part="container"-Attribut lässt externes CSS ein ausgewähltes internes Element mit ::part(container) ansprechen.

Wenn Sie ein anderes Featured-Hintergrund brauchen, verwenden Sie --card-featured-background. Dies ist vorzuziehen, da es Verbrauchern erlaubt, von der genauen internen DOM-Struktur abhängig zu sein.

11. Wiederverwendung der Karte in WordPress, Joomla oder plain HTML

Kopieren Sie ui-card.js in die Zielwebsite und laden Sie sie als JavaScript-Modul:

<script type="module" src="/assets/js/ui-card.js"></script>

Verwenden Sie dann <ui-card> in der Page-Markup. In WordPress registrieren Sie Assets über die vom Theme oder Plugin Unterstützung提供的 script-loading APIs, using module support angemessene für Ihre WordPress-Version. In Joomla verwenden Sie den Web Asset Manager, um das Modul zu registrieren und zu laden. Streuen Sie keine hart codierten Script-Tags durch Produkt-Templates.

Für eine CMS-generierte Karte rendern Sie Titel, Absatz und Link als slotted HTML. Escapeen Sie Inhalte und Attribute gemäß den CMS-Ausgaberegeln.

Praktischer Nutzt: Ein Joomla-Modul und ein WordPress-Block können beide dasselbe Custom-Tag ausgeben, während sie eine Komponenten-Implementation teilen. Jedes CMS bleibt für das Abrufen und Escapen seiner eigenen Inhalte verantwortlich.

12. Barrierefreiheit, SEO und progressive Enhancement

Verwenden Sie native HTML-Controls innerhalb von Komponenten immer dann, wenn möglich. Unsere Schließen-Aktion verwendet ein echtes button, das Tastatur-Aktivierungsemantik liefert, und ein aria-label, da × allein nicht deskriptiv ist.

Wenn ein Benutzer eine Karte mit Tastatur-Fokus schließt, überlegen Sie, wo der Fokus als Nächstes in einer komplexeren Oberfläche hingehen sollte. Dialoge, Menüs und Comboboxes benötigen viel mehr Barrierefreiheits-Verhalten als dieses Beispiel.

Halten Sie wichtige Inhalte in bedeutendem Light-DOM-Markup, wo practical. Wenn JavaScript ausfällt, wird der Browser <ui-card> nicht upgraden; der slotted Überschrift und Absatz bleiben im Dokument, obwohl die gestylte Shell und der Schließen-Button nicht existieren.

Für Suchmaschinen: Nehmen Sie nicht an, dass JavaScript-only-Inhalte in jedem Crawler identisch indiziert werden. Kritische Inhalte sollten im initialen HTML verfügbar sein oder durch eine angemessene Rendering-Strategie.

Shadow DOM hat auch Grenzen: Normale Dokument-CSS-Selektoren stylen keine internen Knoten, und einige ARIA-ID-Beziehungen können Shadow-Grenzen nicht überschreiten. Entwerfen Sie Komponenten-Schnittstellen mit diesen Einschränkungen im Hinterkopf.

13. Sind Web Components immer schneller?

Nicht unbedingt. Web Components erfordern keinen bestimmten Framework-Laufzeit, aber die Leistung hängt von der Menge an JavaScript, DOM-Komplexität, Render-Häufigkeit und Applikations-Architektur ab.

Eine kleine Karte ist ein guter Kandidat. Hunderte komplexer Elemente mit unnötigem DOM-Rebuilding können immer noch langsam sein. Wiederverwenden Sie Templates, vermeiden Sie wiederholtes Full-Rendering, und messen Sie die echte Leistung.

Für eine große Applikation, die bereits um einen Framework's State-Management und Routing herum gebaut ist, kann die Verwendung der eigenen Komponenten des Frameworks einfacher sein. Web Components glänzen, wenn ein stabiles UI-Element Grenzen zwischen Frameworks oder CMS-Systemen überschreiten muss.

14. Fehlerbehebung

Symptom Wahrscheinliche Ursache Was zu prüfen
Karte ist leer Modul wurde nicht geladen DevTools-Konsole, URL, Server-MIME-Type
customElements.define wirft Fehler Ungültiger oder doppelter Name Hyphen-Anforderung und Registrierungs-Schutz
CSS wird nicht in der Karte angewendet Shadow-DOM-Grenze Verwenden Sie Custom Properties, :host, oder ::part
Inhalt erscheint am falschen Platz Slot-Namen-Mismatch Vergleichen Sie slot="title" mit <slot name="title">
Klick auf Schließen tut nichts Template-Button fehlt Inspektieren Sie Shadow-Baum und Konsole
Komponente versagt, wenn bewegt Initialisierung läuft zweimal Schutz für Shadow-Root-Erstellung
Link führt zu 404 Beispiel-URL wurde nicht ersetzt Verwenden Sie ein existierendes Ziel

Denken Sie daran, dass connectedCallback() mehr als einmal ausgeführt werden kann. Der Schutz in unserer finalen Version hält die Initialisierung ein-malig; komplexere Komponenten müssen möglicherweise externe Observer oder globale Event-Listener während ihres Verbindungs-Lebenszyklus anhängen und entfernen.

15. wann sollten Sie Web Components verwenden?

Wählen Sie sie, wenn eine Komponente eine wiederverwendbare, dokumentierte HTML-Schnittstelle über mehrere Websites, Frameworks oder CMS-Umgebungen hinweg benötigt. Karten, Benachrichtigungen, Produkt-Widgets und kleine interaktive Tools sind gute Kandidaten.

Überspringen Sie die Abstraktion, wenn einige Zeilen ordinary HTML und CSS das Problem bereits lösen. Und erfinden Sie native Controls nicht ohne starken Grund.

Ein nütztes Test: würde eine andere Anwendung davon profitieren, dieses Element zu verwenden, ohne zu wissen, wie es implementiert wurde? Wenn ja, ist ein Web Component erwägenswert.

Schluss

Sie haben eine echte wiederverwendbare Komponente gebaut, nicht nur eine Browser-API gelesen. Sie hat ein Custom-Tag, gestaltete Styles, konfigurierbaren Content, eine Featured-Variante und ein Event, auf das andere Code zuhören kann.

Beginnen Sie mit einer Komponente, die in Ihren Projekten immer wieder vorkommt. Geben Sie ihr eine kleine öffentliche API, testen Sie sie in mehr als einem Layout, und halten Sie die Abhängigkeiten minimal.

Der langfristige Wert von Web Components liegt nicht darin, dass sie jedes Framework ersetzen. Sie ermöglichen es, dass nützliche UI-Elemente das Framework oder CMS überleben, das sie zuerst hostete.

Offizielle Referenzen