Element.getHTML() — Methode · JavaScript-Referenz

Signatur

Element.prototype.getHTML(options)

Beschreibung

getHTML() gibt die Kindknoten eines Elements als HTML-String zurück. Ohne Argumente ist das Ergebnis fast immer dasselbe wie beim Lesen von element.innerHTML. Neu ist, dass die Methode auch Shadow Roots ausgeben kann. Diese erscheinen im String als deklaratives Shadow DOM, also als <template shadowrootmode="open|closed">…</template>.

Das braucht man vor allem, wenn man Web Components mit ihrem Shadow DOM vollständig als HTML speichern will. Typische Anwendungen sind serverseitiges Rendern (SSR), Snapshots für Tests, das Speichern von Editor-Inhalten oder das Kopieren von Komponenten in ein anderes Dokument. Um den String wieder einzulesen, nutzt man Element.setHTMLUnsafe() oder Document.parseHTMLUnsafe(). Nur diese beiden Methoden erzeugen aus deklarativem Shadow DOM wieder echte Shadow Roots.

Ein Shadow Root landet nur dann im Ergebnis, wenn eine dieser Bedingungen erfüllt ist:

serializableShadowRoots: true ist gesetzt und der Shadow Root ist serialisierbar. Das ist er, wenn er mit attachShadow({ mode, serializable: true }) oder über das Attribut shadowrootserializable angelegt wurde.
Der Shadow Root steht ausdrücklich im Array shadowRoots. Das funktioniert auch bei geschlossenen (closed) und nicht serialisierbaren Shadow Roots.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Objekt, das festlegt, wie Shadow Roots ausgegeben werden.
$options.serializableShadowRoots	boolean	false	Bei `true` werden alle als serialisierbar markierten Shadow Roots im Teilbaum ausgegeben.
$options.shadowRoots	ShadowRoot[]	[]	Shadow Roots, die in jedem Fall ausgegeben werden, auch wenn sie geschlossen oder nicht serialisierbar sind.

Rückgabewert

Typ

string

Beschreibung

Der HTML-String mit dem Inhalt des Elements. Das Element selbst ist nicht enthalten, es geht also um den Inhalt wie bei innerHTML. Ausgewählte Shadow Roots erscheinen als <template shadowrootmode>.

Beispiele

Einfache Umwandlung wie mit innerHTML

const box = document.createElement('div');
box.innerHTML = '<p>Hallo <strong>Welt</strong></p>';

console.log(box.getHTML());
console.log(box.getHTML() === box.innerHTML);

<p>Hallo <strong>Welt</strong></p> true

Serialisierbaren Shadow Root mit ausgeben

const host = document.createElement('user-card');
const shadow = host.attachShadow({ mode: 'open', serializable: true });
shadow.innerHTML = '<span>Max Mustermann</span>';

// Ohne Option wird das Shadow DOM ignoriert
console.log(JSON.stringify(host.getHTML()));

// Mit Option wird es als deklaratives Shadow DOM ausgegeben
console.log(host.getHTML({ serializableShadowRoots: true }));

"" <template shadowrootmode="open" shadowrootserializable=""><span>Max Mustermann</span></template>

Geschlossenen Shadow Root ausgeben und wieder einlesen

const host = document.createElement('div');
const closedRoot = host.attachShadow({ mode: 'closed' });
closedRoot.innerHTML = '<b>Intern</b>';

// Den Shadow Root ausdrücklich angeben
const html = host.getHTML({ shadowRoots: [closedRoot] });
console.log(html);

// Wieder einlesen: nur setHTMLUnsafe erzeugt echte Shadow Roots
const wrapper = document.createElement('section');
wrapper.setHTMLUnsafe(`<div>${html}</div>`);
console.log(wrapper.firstElementChild.shadowRoot); // closed, deshalb null
console.log(wrapper.firstElementChild.childNodes.length); // kein <template> im Light DOM

<template shadowrootmode="closed"><b>Intern</b></template> null 0

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Methode ist erst seit 2024 in allen großen Browsern verfügbar (Chrome 125, Firefox 128, Safari 18). Für ältere Browser prüft man mit 'getHTML' in Element.prototype und nutzt sonst innerHTML, allerdings ohne Shadow DOM.
Nur der Inhalt: Wie bei innerHTML fehlt das Element selbst im Ergebnis. Anders als outerHTML gibt es keine Variante mit dem Element selbst.
Einlesen: innerHTML und insertAdjacentHTML machen aus deklarativem Shadow DOM keine Shadow Roots. Die <template>-Elemente bleiben dann einfach als Templates stehen. Nur setHTMLUnsafe() und Document.parseHTMLUnsafe() werten sie aus.
Sicherheit: Mit der Option shadowRoots lassen sich auch geschlossene Shadow Roots auslesen. Gibt man solche Strings an Dritte weiter, kann das Implementierungsdetails oder Daten preisgeben. Ein ausgegebener String ist außerdem nicht bereinigt. Wird er aus fremden Quellen wieder eingelesen, droht XSS. Unsicheres HTML sollte man vorher bereinigen, zum Beispiel mit DOMPurify oder der Sanitizer-API.
Formularzustände wie der aktuelle Wert eines <input>, Event-Listener und JavaScript-Eigenschaften werden nicht mit ausgegeben. Übernommen werden nur Attribute und Knoten.

Siehe auch

Element.innerHTML Element.outerHTML Element.setHTMLUnsafe() Element.attachShadow() ShadowRoot.getHTML() Document.parseHTMLUnsafe() FileSystemEntry.getParent()