ShadowRoot.serializable — Eigenschaft · JavaScript-Referenz

Signatur

ShadowRoot.serializable

Beschreibung

Die Eigenschaft serializable zeigt an, ob ein ShadowRoot serialisierbar ist. Ist sie true, kann Element.getHTML() bzw. ShadowRoot.getHTML() mit der Option { serializableShadowRoots: true } den Inhalt des Shadow-Roots mit ausgeben. Er erscheint dann als deklaratives <template shadowrootmode="…">-Element im erzeugten HTML-String.

Der Wert wird nur beim Anlegen des Shadow-Roots festgelegt und lässt sich danach nicht mehr ändern:

per JavaScript mit element.attachShadow({ mode: "open", serializable: true }),
deklarativ mit dem Attribut shadowrootserializable an einem <template shadowrootmode="open">-Element.

Das braucht man vor allem beim serverseitigen Rendern (SSR), bei Snapshots für Tests oder Vorabrendering und beim Kopieren oder Speichern von DOM-Bäumen, die Web Components enthalten. Ohne dieses Kennzeichen lässt getHTML() Shadow-Inhalte weg, genau wie innerHTML. So bleibt die Kapselung einer Komponente standardmäßig erhalten.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Shadow-Root serialisierbar ist, sonst false (Standardwert).

Beispiele

Serialisierbaren Shadow-Root anlegen und prüfen

const host = document.createElement("div");
const root = host.attachShadow({ mode: "open", serializable: true });
root.innerHTML = "<p>Hallo aus dem Shadow DOM</p>";

console.log(root.serializable);

// Ohne Option ist der Standardwert false
const other = document.createElement("div").attachShadow({ mode: "open" });
console.log(other.serializable);

true false

Shadow-Inhalt mit getHTML() serialisieren

const host = document.createElement("my-card");
const root = host.attachShadow({ mode: "open", serializable: true });
root.innerHTML = "<p>Karte</p>";

// innerHTML ignoriert Shadow-Roots grundsätzlich
console.log(host.innerHTML);

// getHTML berücksichtigt serialisierbare Shadow-Roots
console.log(host.getHTML({ serializableShadowRoots: true }));

<template shadowrootmode="open" shadowrootserializable=""><p>Karte</p></template>

Deklarativer Shadow-Root mit shadowrootserializable

const container = document.createElement("div");

// setHTMLUnsafe wertet deklaratives Shadow DOM aus (innerHTML nicht)
container.setHTMLUnsafe(`
  <user-badge>
    <template shadowrootmode="open" shadowrootserializable>
      <span>Admin</span>
    </template>
  </user-badge>`);

const badge = container.querySelector("user-badge");
console.log(badge.shadowRoot.serializable);

true

Nur serialisierbare Komponenten für einen Snapshot sammeln

const snapshotHosts = [...document.querySelectorAll("*")]
  .filter((el) => el.shadowRoot?.serializable)
  .map((el) => el.localName);

console.log("Serialisierbare Hosts:", snapshotHosts);

Serialisierbare Hosts: ["my-card", "user-badge"] (je nach Seite)

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie root.serializable = true hat keine Wirkung und wirft im Strict Mode einen TypeError. Der Wert lässt sich nur über attachShadow() oder das Attribut shadowrootserializable festlegen.
Die Option muss mitgegeben werden: Auch bei serializable === true gibt getHTML() den Shadow-Inhalt nur aus, wenn serializableShadowRoots: true gesetzt ist. Einzelne Roots lassen sich unabhängig von serializable über die Option shadowRoots: [root] einbeziehen.
Geschlossene Roots: Auch Roots mit mode: "closed" können serialisierbar sein. Ihr Inhalt landet dann im HTML-String. Überlege genau, ob gekapselte Interna nach außen gelangen dürfen.
Sicherheit: Serialisiertes HTML aus fremden Quellen nicht ungeprüft mit setHTMLUnsafe() oder Document.parseHTMLUnsafe() wieder einlesen, sonst droht XSS.
Nicht dasselbe wie clonable: serializable steuert die HTML-Ausgabe, clonable das Kopieren mit cloneNode().
Kompatibilität: Erst in neueren Browsern verfügbar (Chrome/Edge 125, Firefox 128, Safari 18). In älteren Browsern ist die Eigenschaft undefined. Prüfen lässt sich die Unterstützung mit "serializable" in ShadowRoot.prototype.

Siehe auch

Element.attachShadow() Element.getHTML() ShadowRoot.getHTML() ShadowRoot.clonable ShadowRoot.mode Element.setHTMLUnsafe() ShadowRoot