HTMLTemplateElement.shadowRootSerializable — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTemplateElement.shadowRootSerializable

Beschreibung

Die Eigenschaft shadowRootSerializable spiegelt das boolesche HTML-Attribut shadowrootserializable eines <template>-Elements wider. Sie gehört zum deklarativen Shadow DOM. Ein <template shadowrootmode="open"> legt beim Parsen des HTML-Codes direkt einen Shadow Root am Elternelement an, ganz ohne JavaScript.

Ist das Attribut gesetzt, bekommt der erzeugte ShadowRoot die Eigenschaft serializable === true. Solche Shadow Roots werden von Element.getHTML({ serializableShadowRoots: true }) bzw. ShadowRoot.getHTML() mit ausgegeben. Das nutzt man z. B. beim serverseitigen Rendern (SSR), bei Snapshots oder beim Kopieren von Web-Komponenten samt ihrem Shadow-Inhalt.

Im Skript liefert die Eigenschaft true, wenn das Attribut vorhanden ist, sonst false. Setzt man den Wert, wird das Attribut hinzugefügt bzw. entfernt. Das Gegenstück im Skript ist die Option serializable von Element.attachShadow().

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Attribut shadowrootserializable gesetzt ist, sonst false. Beim Schreiben wird das Attribut hinzugefügt (true) oder entfernt (false).

Beispiele

Eigenschaft lesen und setzen (Spiegelung des Attributs)

const tpl = document.createElement('template');
console.log(tpl.shadowRootSerializable); // false

tpl.shadowRootSerializable = true;
console.log(tpl.hasAttribute('shadowrootserializable')); // true
console.log(tpl.outerHTML);

false true <template shadowrootserializable=""></template>

Deklarativen, serialisierbaren Shadow Root per setHTMLUnsafe() erzeugen

const host = document.createElement('div');
host.setHTMLUnsafe(`
  <my-card>
    <template shadowrootmode="open" shadowrootserializable>
      <p>Hallo aus dem Shadow DOM</p>
    </template>
  </my-card>`);

const card = host.querySelector('my-card');
console.log(card.shadowRoot.serializable); // true
console.log(card.shadowRoot.innerHTML.trim());

true <p>Hallo aus dem Shadow DOM</p>

Shadow-Inhalt mit getHTML() serialisieren (z. B. für SSR/Snapshots)

const host = document.createElement('div');
host.setHTMLUnsafe(
  '<x-badge><template shadowrootmode="open" shadowrootserializable><b>Neu</b></template></x-badge>'
);

// Ohne Option: Shadow Root fehlt in der Ausgabe
console.log(host.getHTML());
// Mit Option: serialisierbare Shadow Roots werden als <template> ausgegeben
console.log(host.getHTML({ serializableShadowRoots: true }));

<x-badge></x-badge> <x-badge><template shadowrootmode="open" shadowrootserializable=""><b>Neu</b></template></x-badge>

Unterstützung prüfen

const supportsSerializable =
  'shadowRootSerializable' in HTMLTemplateElement.prototype;

console.log(supportsSerializable ? 'Unterstützt' : 'Nicht unterstützt – Fallback nötig');

Unterstützt

// Wichtig · Fallstricke

Wirkt nur beim Parsen: Das Attribut hat nur Einfluss, wenn der HTML-Parser das Template zusammen mit shadowrootmode verarbeitet. Das passiert beim ersten Laden des Dokuments sowie bei setHTMLUnsafe() und Document.parseHTMLUnsafe(). Wenn man shadowRootSerializable an einem bereits bestehenden oder per createElement erzeugten Template setzt und das Template dann einfügt, entsteht kein Shadow Root. innerHTML verarbeitet deklaratives Shadow DOM ebenfalls nicht.
Template verschwindet: Nach dem Parsen wird das deklarative Template in den Shadow Root umgewandelt und ist nicht mehr im DOM. Den Zustand prüft man danach über element.shadowRoot.serializable.
Ohne shadowrootmode bleibt das Attribut wirkungslos.
Ein closed-Shadow-Root kann zwar serialisierbar sein, wird von getHTML() aber nur ausgegeben, wenn man ihn ausdrücklich über die Option shadowRoots übergibt.
Sicherheit: setHTMLUnsafe() bereinigt keine Eingaben. Verarbeitet man damit nicht vertrauenswürdiges HTML, drohen XSS-Lücken.
Kompatibilität: Die Eigenschaft ist relativ neu (Chromium 125, Firefox 128, Safari 18). In älteren Browsern ist sie undefined, deshalb vorher die Unterstützung prüfen.

Siehe auch

HTMLTemplateElement.shadowRootMode HTMLTemplateElement.shadowRootClonable HTMLTemplateElement.shadowRootDelegatesFocus ShadowRoot.serializable Element.getHTML() Element.setHTMLUnsafe() Element.attachShadow()