Element: outerHTML-Eigenschaft

Wert

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

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

Ausnahmen

NoModificationAllowedError DOMException

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

SyntaxError DOMException

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ährend Trusted Types durch 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 seiner outerHTML-Eigenschaft weder dieses Element noch seine Nachkommen. Zum Beispiel:

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

Auch wenn das Element im Dokument ersetzt wird, hält die Variable, deren outerHTML-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 (siehe Browser-Kompatibilität). Dies dient dazu, eine potenzielle Sicherheitslücke (Mutation XSS) zu verhindern, bei der ein Angreifer Eingaben erstellen kann, die eine Sanitisierungsfunktion 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 keine Shadow Roots ein. Wenn Sie eine HTML-Serialisierung eines Elements benötigen, die Shadow Roots einschließt, müssen Sie stattdessen die Element.getHTML() Methode verwenden. Beachten Sie, dass dies die Inhalte des Elements erhält.

Ähnlich wird beim Festlegen von Elementinhalten mit outerHTML die HTML-Eingabe in DOM-Elemente analysiert, die keine Shadow Roots enthalten. Beispielsweise wird <template> als HTMLTemplateElement analysiert, unabhängig davon, ob das shadowrootmode-Attribut angegeben ist oder nicht. Wenn Sie die Inhalte eines Elements aus einer HTML-Eingabe, die deklarative Shadow Roots enthält, setzen möchten, müssen Sie stattdessen Element.setHTMLUnsafe() oder ShadowRoot.setHTMLUnsafe() verwenden.

Sicherheitsüberlegungen

Die outerHTML-Eigenschaft kann ein Vektor für Cross-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 im error-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 stets TrustedHTML-Objekte statt Strings zuweisen und vertraute Typen durchsetzen mit dem require-trusted-types-for CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Chance hat, die Eingabe zu sanitisieren, um potenziell gefährliches Markup zu entfernen, bevor es injiziert wird.

Beispiele

Die Serialisierung eines Elements erhalten

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

Angenommen, folgendes HTML ist gegeben:

<div id="example">
  <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 id="example">\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 der outerHTML-Eigenschaft des Elements zuweisen. Um das Risiko von XSS zu mindern, erstellen wir zuerst ein TrustedHTML-Objekt aus dem String, der das HTML enthält, und weisen dieses Objekt dann outerHTML zu.

Vertrauenswürdige Typen werden noch nicht von allen Browsern unterstützt, daher definieren wir zuerst das Trusted 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 eine TrustedTypePolicy, die eine createHTML() für die Umwandlung eines Eingabestrings in TrustedHTML-Instanzen definiert. In der Regel verwenden Implementierungen von createHTML() eine Bibliothek wie DOMPurify, um die Eingabe wie unten gezeigt zu sanitisieren:

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

Dann verwenden wir dieses policy-Objekt, um ein TrustedHTML-Objekt aus dem potenziell unsicheren Eingabestring zu erstellen und das Ergebnis dem Element zuzuweisen:

// 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

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