Element: Eigenschaft outerHTML

Wert

Beim Lesen der Eigenschaft wird eine Zeichenfolge zurückgegeben, die eine HTML-Serialisierung des element und seiner Nachfahren enthält.

Beim Festlegen der Eigenschaft wird entweder ein TrustedHTML-Objekt oder eine Zeichenfolge akzeptiert. Die Eingabe wird als HTML interpretiert; das Ergebnis ersetzt das Element und alle seine Nachfahren. Wird die Eigenschaft auf den Wert null gesetzt, wird null in eine leere Zeichenfolge ("") umgewandelt. Somit ist element.outerHTML = null gleichbedeutend mit element.outerHTML = "".

Ausnahmen

NoModificationAllowedError DOMException

Wird ausgelöst, wenn versucht wird, outerHTML für ein Element festzulegen, das ein direktes Kind eines Document ist, beispielsweise Document.documentElement.

SyntaxError DOMException

Wird ausgelöst, wenn versucht wird, outerHTML mit einer nicht wohlgeformten XML-Eingabe festzulegen.

TypeError

Wird ausgelöst, wenn der Eigenschaft eine Zeichenfolge zugewiesen wird, während Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

outerHTML gibt eine Serialisierung des Elements zurück oder legt HTML oder XML fest, das interpretiert werden soll, um das Element innerhalb seines Elternelements zu ersetzen.

Hat das Element keinen Elternknoten, ändert das Festlegen seiner Eigenschaft outerHTML weder das Element noch seine Nachfahren. Beispiel:

const div = document.createElement("div");
div.outerHTML = '<div class="test">test</div>';
console.log(div.outerHTML); // output: "<div></div>"

Das Element wird zwar im Dokument ersetzt, die Variable, deren Eigenschaft outerHTML festgelegt wurde, enthält jedoch weiterhin eine Referenz auf das ursprüngliche Element:

const p = document.querySelector("p");
console.log(p.nodeName); // shows: "P"
p.outerHTML = "<div>This div replaced a paragraph.</div>";
console.log(p.nodeName); // still "P";

Escapte Attributwerte

Im zurückgegebenen Wert werden einige Werte in HTML-Attributen escaped. Hier ist zu sehen, dass das Zeichen & escaped wird:

const anchor = document.createElement("a");
anchor.href = "https://developer.mozilla.org?a=b&c=d";
console.log(anchor.outerHTML); // output: "<a href='https://developer.mozilla.org?a=b&amp;c=d'></a>"

Einige Browser serialisieren auch die Zeichen < und > als < und >, wenn sie in Attributwerten vorkommen (siehe Browser-Kompatibilität). Dadurch soll eine potenzielle Sicherheitslücke (Mutation XSS) verhindert werden: Ein Angreifer könnte eine Eingabe erstellen, die eine Bereinigungsfunktion umgeht und so einen Cross-Site-Scripting-(XSS-)Angriff ermöglicht.

Aspekte des Shadow DOM

Die Serialisierung des DOM-Baums, die aus der Eigenschaft gelesen wird, enthält keine Shadow Roots. Wenn Sie eine HTML-Serialisierung eines Elements einschließlich seiner Shadow Roots erhalten möchten, müssen Sie stattdessen die Methode Element.getHTML() verwenden. Beachten Sie, dass diese den Inhalt des Elements zurückgibt.

Auch beim Festlegen von Elementinhalten mit outerHTML wird die HTML-Eingabe in DOM-Elemente interpretiert, die keine Shadow Roots enthalten. So wird beispielsweise <template> als HTMLTemplateElement interpretiert, unabhängig davon, ob das Attribut shadowrootmode angegeben ist. Wenn Sie den Inhalt eines Elements anhand einer HTML-Eingabe festlegen möchten, die deklarative Shadow Roots enthält, müssen Sie stattdessen Element.setHTMLUnsafe() oder ShadowRoot.setHTMLUnsafe() verwenden.

Sicherheitsaspekte

Die Eigenschaft outerHTML kann ein Angriffsvektor für Cross-Site-Scripting-(XSS-)Angriffe sein, da sich mit ihr potenziell unsichere, von Benutzern bereitgestellte Zeichenfolgen in das DOM einfügen lassen. Die Eigenschaft verhindert zwar, dass eingefügte <script>-Elemente ausgeführt werden. Angreifer können jedoch auf viele andere Arten HTML erstellen, das bösartiges JavaScript ausführt. Im folgenden Beispiel würde etwa der Code im error-Event-Handler ausgeführt, da der src-Wert des <img>-Elements keine gültige Bild-URL ist:

const name = "<img src='x' onerror='alert(1)'>";
element.outerHTML = name; // shows the alert

Sie können diese Risiken verringern, indem Sie stets TrustedHTML-Objekte statt Zeichenfolgen zuweisen und mithilfe der CSP-Direktive require-trusted-types-for die Verwendung von Trusted Types erzwingen. So wird sichergestellt, dass die Eingabe eine Transformationsfunktion durchläuft, die sie bereinigen und potenziell gefährliches Markup entfernen kann, bevor sie eingefügt wird.

Beispiele

Serialisierung eines Elements abrufen

Beim Lesen von outerHTML serialisiert der User Agent das Element.

Gegeben sei das folgende HTML:

<div id="example">
  <p>Content</p>
  <p>Further Elaborated</p>
</div>

Sie können das Markup des <div>-Elements wie folgt abrufen und protokollieren:

const myElement = document.querySelector("#example");
const contents = myElement.outerHTML;
console.log(contents);
// '<div id="example">\n  <p>Content</p>\n  <p>Further Elaborated</p>\n</div>'

Das Element ersetzen

In diesem Beispiel ersetzen wir ein Element im DOM, indem wir der Eigenschaft outerHTML des Elements HTML zuweisen. Um das XSS-Risiko zu verringern, erstellen wir zunächst aus der Zeichenfolge mit dem HTML ein TrustedHTML-Objekt und weisen dieses anschließend outerHTML zu.

Trusted Types werden noch nicht von allen Browsern unterstützt. Daher definieren wir zuerst das Trusted-Types-Tinyfill. Es dient als transparenter Ersatz für die Trusted Types JavaScript API:

if (typeof trustedTypes === "undefined")
  trustedTypes = { createPolicy: (n, rules) => rules };

Als Nächstes erstellen wir eine TrustedTypePolicy, die createHTML() definiert, um eine eingegebene Zeichenfolge in TrustedHTML-Instanzen umzuwandeln. Implementierungen von createHTML() verwenden üblicherweise eine Bibliothek wie DOMPurify, um die Eingabe wie unten gezeigt zu bereinigen:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});

Anschließend verwenden wir dieses policy-Objekt, um aus der potenziell unsicheren Eingabezeichenfolge ein TrustedHTML-Objekt zu erstellen, und weisen das Ergebnis dem Element zu:

// The potentially malicious string
const untrustedString = "<p>I might be XSS</p><img src='x' onerror='alert(1)'>";

// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);

// Inject the TrustedHTML (which contains a trusted string)
const element = document.querySelector("#container");
element.outerHTML = trustedHTML; // Replaces the element with id "container"

// Note that the  #container div is no longer part of the document tree,

Spezifikationen

Browser-Kompatibilität

Siehe auch

• DOM-Bäume in XML-Zeichenfolgen serialisieren: XMLSerializer
• XML oder HTML in DOM-Bäume interpretieren: DOMParser
• HTMLElement.outerText