DasouterHTML Attribut desElement Interface liest oder setzt das HTML- oder XML-Markup des Elements und seiner Nachkommen, ignoriert jedoch jeglicheShadow Roots in beiden Fällen.

Um den Inhalt eines Elements zu lesen oder zu setzen, verwenden Sie stattdessen dieinnerHTML Eigenschaft.

Wert

Das Lesen der Eigenschaft gibt einen String zurück, der eine HTML-Serialisierung desElements und seiner Nachkommen enthält.

Das Setzen der Eigenschaft akzeptiert entweder einTrustedHTML Objekt oder einen String.Die Eingabe wird als HTML analysiert und ersetzt das Element sowie alle seine Nachkommen mit dem Ergebnis.Wenn der Wert aufnull gesetzt wird, wird diesernull-Wert in den leeren String ("") umgewandelt, sodasselement.outerHTML = null gleichbedeutend mitelement.outerHTML = "" ist.

Ausnahmen

NoModificationAllowedErrorDOMException

Wird ausgelöst, wenn versucht wurde,outerHTML auf einem Element zu setzen, welches ein direktes Kind einesDocument ist, wie z.B.Document.documentElement.

SyntaxErrorDOMException

Wird ausgelöst, wenn versucht wurde,outerHTML mit einer XML-Eingabe zu setzen, die nicht wohlgeformt ist.

TypeError

Wird ausgelöst, wenn die Eigenschaft auf einen String gesetzt wird, währendTrusted Typesdurch eine CSP durchgesetzt werden und keine Standardrichtlinie definiert ist.

Beschreibung

outerHTML erhält eine Serialisierung des Elements oder setzt HTML oder XML, das analysiert werden soll, um es innerhalb des Elternelements zu ersetzen.

Wenn das Element keinen Elterknoten hat, ändert das Setzen seinerouterHTML-Eigenschaft weder dieses Element noch seine Nachkommen.Zum Beispiel:

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

Auch wenn das Element im Dokument ersetzt wird, hält die Variable, derenouterHTML-Eigenschaft gesetzt wurde, 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";

Escapete Attributwerte

Der zurückgegebene Wert wird einige Werte in HTML-Attributen escapen.Hier sehen wir, dass das&-Zeichen escapt 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<- und>-Zeichen als< und>, wenn sie in Attributwerten erscheinen (sieheBrowser-Kompatibilität).Dies dient dazu, eine potenzielle Sicherheitslücke (Mutation XSS) zu verhindern, bei der ein Angreifer Eingaben erstellen kann, die eineSanitisierungsfunktion umgehen, was eine Cross-Site Scripting (XSS)-Attacke ermöglicht.

Überlegungen zum Shadow DOM

Die Serialisierung des DOM-Baums, die von der Eigenschaft gelesen wird, schließt keineShadow Roots ein.Wenn Sie eine HTML-Serialisierung eines Elements benötigen, die Shadow Roots einschließt, müssen Sie stattdessen dieElement.getHTML() Methode verwenden.Beachten Sie, dass dies dieInhalte des Elements erhält.

Ähnlich wird beim Festlegen von Elementinhalten mitouterHTML die HTML-Eingabe in DOM-Elemente analysiert, die keine Shadow Roots enthalten.Beispielsweise wird<template> alsHTMLTemplateElement analysiert, unabhängig davon, ob dasshadowrootmode-Attribut angegeben ist oder nicht.Wenn Sie dieInhalte eines Elements aus einer HTML-Eingabe, die deklarative Shadow Roots enthält, setzen möchten, müssen Sie stattdessenElement.setHTMLUnsafe() oderShadowRoot.setHTMLUnsafe() verwenden.

Sicherheitsüberlegungen

DieouterHTML-Eigenschaft kann ein Vektor fürCross-Site Scripting (XSS)-Angriffe sein, da sie verwendet werden kann, um potenziell unsichere von einem Benutzer bereitgestellte Strings in das DOM zu injizieren.Während die Eigenschaft verhindert, dass<script>-Elemente beim Einfügen ausgeführt werden, ist sie anfällig für viele andere Arten, mit denen Angreifer HTML so gestalten können, dass bösartiges JavaScript ausgeführt wird.Zum Beispiel würde der folgende Code imerror-Event-Handler ausgeführt, weil der<img>src Wert keine gültige Bild-URL ist:

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

Sie können diese Probleme vermindern, indem Sie stetsTrustedHTML-Objekte statt Strings zuweisen undvertraute Typen durchsetzen mit demrequire-trusted-types-for CSP-Direktive.Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Chance hat, die Eingabe zusanitisieren, um potenziell gefährliches Markup zu entfernen, bevor es injiziert wird.

Beispiele

Die Serialisierung eines Elements erhalten

Das Lesen vonouterHTML führt dazu, dass der User-Agent das Element serialisiert.

Angenommen, folgendes HTML ist gegeben:

<div>  <p>Content</p>  <p>Further Elaborated</p></div>

Sie können das Markup für das<div> wie folgt abrufen und protokollieren:

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

Das Element ersetzen

In diesem Beispiel werden wir ein Element im DOM ersetzen, indem wir HTML derouterHTML-Eigenschaft des Elements zuweisen.Um das Risiko von XSS zu mindern, erstellen wir zuerst einTrustedHTML-Objekt aus dem String, der das HTML enthält, und weisen dieses Objekt dannouterHTML zu.

Vertrauenswürdige Typen werden noch nicht von allen Browsern unterstützt, daher definieren wir zuerst dasTrusted Types Tinyfill.Dies fungiert als transparenter Ersatz für die Trusted Types JavaScript-API:

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

Als Nächstes erstellen wir eineTrustedTypePolicy, die einecreateHTML() für die Umwandlung eines Eingabestrings inTrustedHTML-Instanzen definiert.In der Regel verwenden Implementierungen voncreateHTML() eine Bibliothek wieDOMPurify, um die Eingabe wie unten gezeigt zu sanitisieren:

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

Dann verwenden wir diesespolicy-Objekt, um einTrustedHTML-Objekt aus dem potenziell unsicheren Eingabestring zu erstellen und das Ergebnis dem Element zuzuweisen:

// The potentially malicious stringconst untrustedString = "<p>I might be XSS</p><img src='x' onerror='alert(1)'>";// Create a TrustedHTML instance using the policyconst 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

• Serialisieren von DOM-Bäumen in XML-Strings:XMLSerializer
• Parsen von XML oder HTML in DOM-Bäume:DOMParser
• HTMLElement.outerText