Element.outerHTML — Eigenschaft · JavaScript-Referenz

Signatur

element.outerHTML

Beschreibung

Das Attribut outerHTML des Element-Interfaces liest oder setzt das HTML- oder XML-Markup des Elements und seiner Nachfahren, wobei in beiden Fällen etwaige shadow roots ausgelassen werden.

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

Warnung: Diese Eigenschaft parst ihre Eingabe als HTML und schreibt das Ergebnis in das DOM. APIs wie diese werden als injection sinks bezeichnet und sind ein potenzieller Angriffsvektor für Cross-Site-Scripting-(XSS-)Angriffe, wenn die Eingabe ursprünglich von einem Angreifer stammt. Sie können dieses Risiko mindern, indem Sie stets TrustedHTML-Objekte statt Strings zuweisen und Trusted Types erzwingen.

Wert

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

Beim Setzen der Eigenschaft wird entweder ein TrustedHTML-Objekt oder ein String akzeptiert. Die Eingabe wird als HTML geparst und ersetzt das Element und alle seine Nachfahren mit dem Ergebnis. Wird die Eigenschaft auf den Wert null gesetzt, wird dieser null-Wert in den leeren String ("") umgewandelt, sodass element.outerHTML = null äquivalent zu element.outerHTML = "" ist.

Ausnahmen

NoModificationAllowedError DOMException: Wird geworfen, wenn versucht wird, outerHTML auf einem Element zu setzen, das ein direktes Kind eines Document ist, wie z. B. Document.documentElement.
SyntaxError DOMException: Wird geworfen, wenn versucht wird, outerHTML mit einer XML-Eingabe zu setzen, die nicht wohlgeformt ist.
TypeError: Wird geworfen, wenn die Eigenschaft auf einen String gesetzt wird, während Trusted Types per CSP erzwungen werden und keine Default-Policy definiert ist.

Beschreibung

outerHTML liest eine Serialisierung des Elements oder setzt HTML bzw. XML, das geparst werden soll, um das Element innerhalb seines Elternknotens zu ersetzen.

Wenn das Element keinen Elternknoten hat, ändert das Setzen seiner outerHTML-Eigenschaft weder das Element noch seine Nachfahren. Beispiel:

Außerdem wird die Variable, deren outerHTML-Eigenschaft gesetzt wurde, weiterhin eine Referenz auf das ursprüngliche Element halten, obwohl das Element im Dokument ersetzt wird.

Escapete Attributwerte

Der zurückgegebene Wert escapet einige Werte in HTML-Attributen. Hier sehen wir, dass das Zeichen & escapet wird.

Einige Browser serialisieren zudem die Zeichen < und > als < und >, wenn sie in Attributwerten auftreten. Dies dient dazu, eine potenzielle Sicherheitslücke (mutation XSS) zu verhindern, bei der ein Angreifer eine Eingabe konstruieren kann, die eine Sanitization-Funktion umgeht und dadurch einen Cross-Site-Scripting-(XSS-)Angriff ermöglicht.

Shadow-DOM-Überlegungen

Die Serialisierung des aus der Eigenschaft gelesenen DOM-Baums enthält keine shadow roots. Wenn Sie eine HTML-Serialisierung eines Elements einschließlich der shadow roots erhalten möchten, müssen Sie stattdessen die Methode Element.getHTML() verwenden. Beachten Sie, dass diese den Inhalt des Elements liefert.

Entsprechend wird beim Setzen des Element-Inhalts über outerHTML die HTML-Eingabe in DOM-Elemente geparst, die keine shadow roots enthalten. So wird z. B. <template> als HTMLTemplateElement geparst, unabhängig davon, ob das shadowrootmode-Attribut angegeben ist. Wenn Sie den Inhalt eines Elements aus einer HTML-Eingabe setzen möchten, die deklarative shadow roots enthält, müssen Sie stattdessen Element.setHTMLUnsafe() oder ShadowRoot.setHTMLUnsafe() verwenden.

Sicherheitsüberlegungen

Die Eigenschaft outerHTML ist ein möglicher Vektor für Cross-Site-Scripting-(XSS-)Angriffe, da sie verwendet werden kann, um potenziell unsichere, vom Nutzer bereitgestellte Strings in das DOM zu injizieren. Zwar verhindert die Eigenschaft, dass <script>-Elemente bei ihrer Injektion ausgeführt werden, sie ist jedoch anfällig für viele andere Wege, auf denen Angreifer HTML konstruieren können, um bösartiges JavaScript auszuführen. Das folgende Beispiel würde etwa den Code im error-Event-Handler ausführen, weil der src-Wert des <img> keine gültige Bild-URL ist:

Sie können diese Probleme mindern, indem Sie stets TrustedHTML-Objekte statt Strings zuweisen und Trusted Types mithilfe der CSP-Direktive require-trusted-types-for erzwingen. Dadurch wird sichergestellt, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu sanitizen, um potenziell gefährliches Markup zu entfernen, bevor es injiziert wird.

Rückgabewert

Typ

string | TrustedHTML

Beschreibung

Beim Lesen ein String mit der HTML-Serialisierung des Elements und seiner Nachfahren. Beim Setzen wird ein TrustedHTML-Objekt oder String akzeptiert.

Beispiele

Element ohne Elternknoten

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

Variable behält Referenz auf Originalelement

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

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

XSS-Risiko beim Zuweisen von Strings

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

Serialisierung eines Elements abrufen (JS)

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

Trusted Types Tinyfill

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

TrustedTypePolicy erstellen

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

Element mit TrustedHTML ersetzen

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

// Wichtig · Fallstricke

Warnung: Auch wenn Sie einen String direkt outerHTML zuweisen können, ist dies ein Sicherheitsrisiko, wenn der einzufügende String potenziell bösartige Inhalte enthalten könnte. Sie sollten TrustedHTML verwenden, um sicherzustellen, dass der Inhalt vor dem Einfügen sanitized wird, und einen CSP-Header setzen, um Trusted Types zu erzwingen.

Siehe auch

XMLSerializer DOMParser HTMLElement.outerText Element.innerHTML Element.getHTML() Element.setHTMLUnsafe() TrustedHTML

← Vorheriger Eintrag Element.nextElementSibling Nächster Eintrag → Element.part