ShadowRoot.getHTML() — Methode · JavaScript-Referenz

Signatur

ShadowRoot.prototype.getHTML(options)

Beschreibung

getHTML() wandelt die Kindknoten eines ShadowRoot in einen HTML-String um. Das Ergebnis entspricht zunächst dem Lesen von shadowRoot.innerHTML. Der Unterschied: getHTML() kann auch verschachtelte Shadow Roots in den String aufnehmen. Diese erscheinen dann als deklaratives Shadow DOM, also als <template shadowrootmode="open">…</template>.

Nützlich ist das vor allem für Server-Side Rendering (SSR), Snapshots, Tests und das Kopieren von Web-Components-Bäumen. Das erzeugte HTML lässt sich mit Element.setHTMLUnsafe(), Document.parseHTMLUnsafe() oder direkt vom HTML-Parser wieder einlesen. Dabei entstehen die Shadow Roots neu.

Welche Shadow Roots im Ergebnis landen, bestimmen die Optionen:

Mit serializableShadowRoots: true werden alle verschachtelten Shadow Roots aufgenommen, die als serialisierbar markiert sind. Das sind Roots, die mit attachShadow({ mode, serializable: true }) oder mit dem Attribut shadowrootserializable erzeugt wurden.
Mit shadowRoots: [...] gibst du gezielt einzelne Shadow Roots an, die aufgenommen werden sollen. Das gilt auch für nicht serialisierbare und für closed-Roots, sofern du eine Referenz darauf hast.

Der Shadow Root, auf dem du die Methode aufrufst, wird selbst nicht als <template> ausgegeben. Serialisiert werden nur seine Kindknoten.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Objekt, das steuert, wie verschachtelte Shadow Roots serialisiert werden.
$options.serializableShadowRoots	boolean	false	Bei `true` werden alle verschachtelten Shadow Roots aufgenommen, deren Eigenschaft `serializable` auf `true` steht.
$options.shadowRoots	ShadowRoot[]	[]	Liste von Shadow Roots, die in jedem Fall aufgenommen werden, unabhängig von `serializable` und auch im Modus `closed`.

Rückgabewert

Typ

string

Beschreibung

HTML-String mit den Kindknoten des Shadow Root. Aufgenommene verschachtelte Shadow Roots erscheinen darin als <template shadowrootmode="…">.

Beispiele

Inhalt eines Shadow Root auslesen

const host = document.createElement('div');
const shadow = host.attachShadow({ mode: 'open' });
shadow.innerHTML = '<style>p { color: red; }</style><p>Hallo</p>';

// Ohne Optionen: entspricht shadow.innerHTML
console.log(shadow.getHTML());

Verschachtelte, serialisierbare Shadow Roots mit ausgeben

const outer = document.createElement('div');
const outerShadow = outer.attachShadow({ mode: 'open' });

const inner = document.createElement('span');
// serializable: true erlaubt die Serialisierung dieses Roots
const innerShadow = inner.attachShadow({ mode: 'open', serializable: true });
innerShadow.innerHTML = '<b>Innen</b>';

outerShadow.append(inner);

console.log(outerShadow.getHTML());
console.log(outerShadow.getHTML({ serializableShadowRoots: true }));

<span></span> <span><template shadowrootmode="open" shadowrootserializable=""><b>Innen</b></template></span>

Gezielt einen geschlossenen Shadow Root einbeziehen

const wrapper = document.createElement('div');
const wrapperShadow = wrapper.attachShadow({ mode: 'open' });

const widget = document.createElement('my-widget');
// Closed-Root: nur über die gespeicherte Referenz erreichbar
const closedRoot = widget.attachShadow({ mode: 'closed' });
closedRoot.innerHTML = '<slot></slot><i>geheim</i>';
wrapperShadow.append(widget);

const html = wrapperShadow.getHTML({ shadowRoots: [closedRoot] });
console.log(html);

// Wiederherstellen, z. B. in einem anderen Container
const copy = document.createElement('div');
copy.setHTMLUnsafe(html);

<my-widget><template shadowrootmode="closed"><slot></slot><i>geheim</i></template></my-widget>

// Wichtig · Fallstricke

Browser-Unterstützung: Die Methode ist erst seit 2024 in allen großen Browsern verfügbar. Prüfe sie bei Bedarf mit 'getHTML' in ShadowRoot.prototype und greife sonst auf innerHTML zurück.
Ohne Optionen keine verschachtelten Roots: Wenn serializableShadowRoots nicht aktiv ist und shadowRoots leer bleibt, werden verschachtelte Shadow Roots stillschweigend weggelassen. Es gibt keinen Fehler.
serializable lässt sich nur beim Erzeugen festlegen, also über attachShadow() oder shadowrootserializable. Nachträglich ändern kannst du den Wert nicht.
Sicherheit: Mit shadowRoots legst du auch Inhalte von closed-Roots offen. Gib solche Strings nicht ungeprüft an Dritte weiter. Beim Einlesen mit setHTMLUnsafe() wird nicht bereinigt (Sanitizing). Fremdes HTML kann so zu XSS führen.
Formularzustände und Event-Listener gehen verloren, genauso wie per JavaScript gesetzte Eigenschaften (z. B. input.value, wenn das Attribut value nicht gesetzt ist). Serialisiert werden nur Markup und Attribute.
Adoptierte Stylesheets (adoptedStyleSheets) sind nicht im Ergebnis enthalten.

Siehe auch

Element.getHTML() ShadowRoot.setHTMLUnsafe() ShadowRoot.innerHTML ShadowRoot.serializable Element.attachShadow() Document.parseHTMLUnsafe() ShadowRoot.getAnimations()