<template>: Das Inhalts-Template-Element

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since November 2015.

* Some parts of this feature may have varying levels of support.

Das <template> HTML-Element dient als Mechanismus zur Speicherung von HTML-Fragmenten, die entweder später über JavaScript verwendet oder sofort in einen Shadow DOM generiert werden können.

Attribute

Dieses Element umfasst die globalen Attribute.

shadowrootmode

Erstellt ein shadow root für das übergeordnete Element. Es ist eine deklarative Version der Methode Element.attachShadow() und akzeptiert die gleichen enumerierten Werte.

open: Macht das interne Shadow Root DOM für JavaScript sichtbar (empfohlen für die meisten Anwendungsfälle).
closed: Verbirgt das interne Shadow Root DOM vor JavaScript.

Hinweis: Der HTML-Parser erstellt ein ShadowRoot-Objekt im DOM für das erste <template> in einem Knoten mit diesem Attribut, das auf einen erlaubten Wert gesetzt ist. Wenn das Attribut nicht gesetzt ist, nicht auf einen erlaubten Wert gesetzt ist oder bereits ein ShadowRoot im gleichen übergeordneten Element deklarativ erstellt wurde, wird ein HTMLTemplateElement konstruiert. Ein HTMLTemplateElement kann nach dem Parsen nicht nachträglich in ein Shadow Root umgewandelt werden, zum Beispiel durch das Setzen von HTMLTemplateElement.shadowRootMode.

Hinweis: Sie könnten das nicht standardmäßige Attribut shadowroot in älteren Tutorials und Beispielen finden, das früher in Chrome 90-110 unterstützt wurde. Dieses Attribut wurde seitdem entfernt und durch das standardmäßige Attribut shadowrootmode ersetzt.

shadowrootclonable

Legt den Wert der clonable-Eigenschaft eines mit diesem Element erstellten ShadowRoot auf true fest. Wenn gesetzt, wird ein Klon des Shadow-Hosts (das übergeordnete Element dieses <template>) erstellt mit Node.cloneNode() oder Document.importNode(), der ein Shadow Root in der Kopie enthält.

shadowrootcustomelementregistry

Legt die customElementRegistry-Eigenschaft eines mit diesem Element erstellten ShadowRoot auf null fest, anstatt des Custom-Element-Registers des Dokuments. Dadurch kann später ein sogenanntes CustomElementRegistry mithilfe von CustomElementRegistry.initialize() angeschlossen werden.

shadowrootdelegatesfocus

Legt den Wert der delegatesFocus-Eigenschaft eines mit diesem Element erstellten ShadowRoot auf true fest. Wenn dies gesetzt ist und ein nicht-fokussierbares Element im Shadow-Baum ausgewählt wird, wird der Fokus auf das erste fokussierbare Element im Baum delegiert. Der Wert ist standardmäßig false.

shadowrootreferencetarget Experimentell Nicht standardisiert

Setzt den Wert der referenceTarget-Eigenschaft eines mit diesem Element erstellten ShadowRoot. Der Wert sollte die ID eines Elements innerhalb des Shadow DOMs sein. Wenn gesetzt, verursachen Zielreferenzen zum Host-Element von außerhalb des Shadow DOMs, dass das referenzierte Ziel-Element zum effektiven Ziel der Referenz zum Host-Element wird.

shadowrootserializable

Setzt den Wert der serializable-Eigenschaft eines mit diesem Element erstellten ShadowRoot auf true. Wenn gesetzt, kann das Shadow Root durch Aufrufen der Methoden Element.getHTML() oder ShadowRoot.getHTML() mit dem Parameter options.serializableShadowRoots auf true serialisiert werden. Der Wert ist standardmäßig false.

Hinweise zur Nutzung

Dieses Element hat keinen erlaubten Inhalt, da alles, was im HTML-Quelltext darin verschachtelt ist, nicht tatsächlich die Kinder des <template>-Elements wird. Die Node.childNodes-Eigenschaft des <template>-Elements ist immer leer, und Sie können den genannten verschachtelten Inhalt nur über die spezielle content-Eigenschaft zugreifen. Wenn jedoch Methoden wie Node.appendChild() auf das <template>-Element angewendet werden, würden Sie Kinder in das <template>-Element selbst einfügen, was eine Verletzung seines Inhaltsmodells darstellt und das von der content-Eigenschaft zurückgegebene DocumentFragment nicht tatsächlich aktualisiert.

Aufgrund der Art und Weise, wie das <template>-Element geparst wird, sind alle öffnenden und schließenden <html>, <head> und <body>-Tags innerhalb des Templates Syntaxfehler und werden vom Parser ignoriert, sodass <template><head><title>Test</title></head></template> gleich <template><title>Test</title></template> ist.

Es gibt zwei Hauptanwendungen für das <template>-Element.

Dokumentfragment für Templates

Standardmäßig wird der Inhalt des Elements nicht gerendert. Das entsprechende HTMLTemplateElement-Interface beinhaltet eine standardmäßige content-Eigenschaft (ohne entsprechendes Inhalt-/Markup-Attribut). Diese content-Eigenschaft ist schreibgeschützt und enthält ein DocumentFragment, das den durch das Template dargestellten DOM-Teilbaum enthält.

Die Methoden Node.cloneNode() und Document.importNode() erstellen beide eine Kopie eines Knotens. Der Unterschied besteht darin, dass importNode() den Knoten im Kontext des aufrufenden Dokuments klont, während cloneNode() das Dokument des zu klonenden Knotens verwendet. Der Dokumentkontext bestimmt das CustomElementRegistry für den Aufbau beliebiger benutzerdefinierter Elemente. Aus diesem Grund sollten Sie document.importNode() verwenden, um das content Fragment zu klonen, damit benutzerdefinierte Elemente mithilfe der Definitionen im aktuellen Dokument und nicht im separaten Dokument, das den Template-Inhalt besitzt, konstruiert werden. Siehe die Beispiele auf der Seite zu Node.cloneNode() für weitere Details.

Beachten Sie, dass der DocumentFragment-Container selbst keine Daten enthalten sollte. Siehe das Beispiel Daten auf dem DocumentFragment werden nicht geklont für weitere Details.

Deklarativer Shadow DOM

Wenn das <template>-Element das Attribut shadowrootmode mit dem Wert entweder open oder closed enthält, wird der HTML-Parser sofort einen Shadow DOM generieren. Das Element wird im DOM durch seinen Inhalt ersetzt, der in einem ShadowRoot eingebunden ist, das dem übergeordneten Element angefügt wird. Dies ist das deklarative Äquivalent des Aufrufs von Element.attachShadow(), um einem Element ein Shadow Root anzufügen.

Wenn das Element einen anderen Wert für shadowrootmode hat oder das Attribut shadowrootmode nicht besitzt, erzeugt der Parser ein HTMLTemplateElement. Ebenso, wenn es mehrere deklarative Shadow Roots gibt, wird nur das erste von einem ShadowRoot ersetzt — nachfolgende Instanzen werden als HTMLTemplateElement-Objekte geparst.

Beispiele

Erzeugen von Tabellenzeilen

Zuerst beginnen wir mit dem HTML-Teil des Beispiels.

html

<table id="producttable">
  <thead>
    <tr>
      <td>UPC_Code</td>
      <td>Product_Name</td>
    </tr>
  </thead>
  <tbody>
    <!-- existing data could optionally be included here -->
  </tbody>
</table>

<template id="productrow">
  <tr>
    <td class="record"></td>
    <td></td>
  </tr>
</template>

Zuerst haben wir eine Tabelle, in die wir später Inhalte mithilfe von JavaScript-Code einfügen werden. Dann kommt das Template, das die Struktur eines HTML-Fragments beschreibt, das eine einzelne Tabellenzeile darstellt.

Nachdem die Tabelle erstellt und das Template definiert wurde, verwenden wir JavaScript, um Zeilen in die Tabelle einzufügen, wobei jede Zeile basierend auf dem Template konstruiert wird.

// Test to see if the browser supports the HTML template element by checking
// for the presence of the template element's content attribute.
if ("content" in document.createElement("template")) {
  // Instantiate the table with the existing HTML tbody
  // and the row with the template
  const tbody = document.querySelector("tbody");
  const template = document.querySelector("#productrow");

  // Clone the new row and insert it into the table
  const clone = document.importNode(template.content, true);
  let td = clone.querySelectorAll("td");
  td[0].textContent = "1235646565";
  td[1].textContent = "Stuff";

  tbody.appendChild(clone);

  // Clone the new row and insert it into the table
  const clone2 = document.importNode(template.content, true);
  td = clone2.querySelectorAll("td");
  td[0].textContent = "0384928528";
  td[1].textContent = "Acme Kidney Beans 2";

  tbody.appendChild(clone2);
} else {
  // Find another way to add the rows to the table because
  // the HTML template element is not supported.
}

Das Ergebnis ist die ursprüngliche HTML-Tabelle, der zwei neue Zeilen per JavaScript hinzugefügt wurden:

table {
  background: black;
}
table td {
  background: white;
}

Implementierung eines deklarativen Shadow DOM

In diesem Beispiel wird zu Beginn des Markups eine versteckte Warnung eingefügt. Diese Warnung wird später über JavaScript angezeigt, wenn der Browser das Attribut shadowrootmode nicht unterstützt. Anschließend gibt es zwei <article>-Elemente, die jeweils verschachtelte <style>-Elemente mit unterschiedlichem Verhalten enthalten. Das erste <style>-Element ist global für das gesamte Dokument. Das zweite ist auf das Shadow Root beschränkt, das an Stelle des <template>-Elements aufgrund der Anwesenheit des Attributs shadowrootmode generiert wird.

html

<p hidden>
  ⛔ Your browser doesn't support <code>shadowrootmode</code> attribute yet.
</p>
<article>
  <style>
    p {
      padding: 8px;
      background-color: wheat;
    }
  </style>
  <p>I'm in the DOM.</p>
</article>
<article>
  <template shadowrootmode="open">
    <style>
      p {
        padding: 8px;
        background-color: plum;
      }
    </style>
    <p>I'm in the shadow DOM.</p>
  </template>
</article>

const isShadowRootModeSupported = Object.hasOwn(
  HTMLTemplateElement.prototype,
  "shadowRootMode",
);

document
  .querySelector("p[hidden]")
  .toggleAttribute("hidden", isShadowRootModeSupported);

Deklarativer Shadow DOM mit delegiertem Fokus

Dieses Beispiel zeigt, wie shadowrootdelegatesfocus auf ein Shadow Root angewendet wird, das deklarativ erstellt wurde, und welchen Effekt dies auf den Fokus hat.

Der Code deklariert zunächst ein Shadow Root innerhalb eines <div>-Elements, indem das <template>-Element mit dem Attribut shadowrootmode verwendet wird. Dies zeigt sowohl ein nicht-fokussierbares <div>-Element mit Text als auch ein fokussierbares <input>-Element. Es wird auch CSS verwendet, um Elemente mit :focus blau zu gestalten und das normale Styling des Host-Elements festzulegen.

html

<div>
  <template shadowrootmode="open">
    <style>
      :host {
        display: block;
        border: 1px dotted black;
        padding: 10px;
        margin: 10px;
      }
      :focus {
        outline: 2px solid blue;
      }
    </style>
    <div>Clickable Shadow DOM text</div>
    <input type="text" placeholder="Input inside Shadow DOM" />
  </template>
</div>

Der zweite Codeblock ist identisch, außer dass er das Attribut shadowrootdelegatesfocus setzt, das den Fokus auf das erste fokussierbare Element im Baum delegiert, wenn ein nicht-fokussierbares Element im Baum ausgewählt wird.

html

<div>
  <template shadowrootmode="open" shadowrootdelegatesfocus>
    <style>
      :host {
        display: block;
        border: 1px dotted black;
        padding: 10px;
        margin: 10px;
      }
      :focus {
        outline: 2px solid blue;
      }
    </style>
    <div>Clickable Shadow DOM text</div>
    <input type="text" placeholder="Input inside Shadow DOM" />
  </template>
</div>

Zuletzt verwenden wir das folgende CSS, um einen roten Rand auf das übergeordnete <div>-Element anzuwenden, wenn es fokussiert ist.

css

div:focus {
  border: 2px solid red;
}

Die Ergebnisse werden unten gezeigt. Wenn das HTML zuerst gerendert wird, haben die Elemente kein Styling, wie auf dem ersten Bild zu sehen. Für das Shadow Root ohne gesetztes shadowrootdelegatesfocus können Sie überall außer dem <input> klicken, und der Fokus ändert sich nicht (wenn Sie das <input>-Element auswählen, sieht es wie das zweite Bild aus).

Screenshot des Codes ohne Fokus-Einstellung

Für das Shadow Root mit gesetztem shadowrootdelegatesfocus führt ein Klick auf den Text (der nicht fokussierbar ist) dazu, dass das <input>-Element ausgewählt wird, da dies das erste fokussierbare Element im Baum ist. Dies fokussiert auch das Elternelement, wie unten gezeigt.

Screenshot des Codes, bei dem das Element fokussiert ist

Daten auf dem DocumentFragment werden nicht geklont

Wenn ein DocumentFragment-Wert übergeben wird, verschieben Node.appendChild und ähnliche Methoden nur die Kindknoten dieses Wertes in den Zielknoten. Daher ist es in der Regel vorzuziehen, Ereignishandler an die Kinder eines DocumentFragment zu binden, anstatt an das DocumentFragment selbst.

Betrachten Sie das folgende HTML und JavaScript:

HTML

html

<div id="container"></div>

<template id="template">
  <div>Click me</div>
</template>

JavaScript

const container = document.getElementById("container");
const template = document.getElementById("template");

function clickHandler(event) {
  event.target.append(" — Clicked this div");
}

const firstClone = document.importNode(template.content, true);
firstClone.addEventListener("click", clickHandler);
container.appendChild(firstClone);

const secondClone = document.importNode(template.content, true);
secondClone.children[0].addEventListener("click", clickHandler);
container.appendChild(secondClone);

Ergebnis

Da firstClone ein DocumentFragment ist, werden bei appendChild nur seine Kinder zu container hinzugefügt; die Ereignishandler von firstClone werden nicht kopiert. Im Gegensatz dazu wird, weil ein Ereignishandler für den ersten Kindknoten von secondClone hinzugefügt wird, der Ereignishandler kopiert, wenn appendChild aufgerufen wird, und ein Klick darauf funktioniert wie erwartet.

Technische Zusammenfassung

Inhaltskategorien	Metadatenelemente, Fließelemente, Phraseelemente, skriptunterstützende Elemente
Erlaubter Inhalt	Nichts (siehe Hinweise zur Nutzung)
Tag-Auslassung	Keine, sowohl das Anfags- als auch das End-Tag sind obligatorisch.
Erlaubte Eltern	Jedes Element, das Metadatenelemente, Phraseelemente oder skriptunterstützende Elemente akzeptiert. Auch als Kind eines `<colgroup>`-Elements erlaubt, das kein `span`-Attribut besitzt.
Implizite ARIA-Rolle	Keine entsprechende Rolle
Erlaubte ARIA-Rollen	Keine `role` erlaubt
DOM-Schnittstelle	[`HTMLTemplateElement`](/de/docs/Web/API/HTMLTemplateElement)

Spezifikationen

Specification
HTML # the-template-element

Browser-Kompatibilität

Siehe auch

part und exportparts HTML-Attribute
<slot> HTML-Element
:has-slotted, :host, :host() und :host-context() CSS-Pseudoklassen
::part und ::slotted CSS-Pseudoelemente
ShadowRoot Schnittstelle
Verwendung von Templates und Slots
CSS Scoping-Modul
Deklarativer Shadow DOM (mit html) in Verwendung von Shadow DOM
Deklarativer Shadow DOM auf web.dev (2023)

Help improve MDN

Learn how to contribute Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden