Element: outerHTML-Eigenschaft

Wert

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

Das Setzen der Eigenschaft akzeptiert entweder ein TrustedHTML-Objekt oder einen String. Die Eingabe wird als HTML analysiert und ersetzt das Element und all seine Nachfahren mit dem Ergebnis. Wenn es auf den Wert 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 an einem Element zu setzen, das 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 erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

outerHTML holt eine Serialisierung des Elements oder setzt HTML oder XML, das analysiert werden soll, um es innerhalb des übergeordneten Elements zu ersetzen.

Wenn das Element keinen Elternelement-Knoten hat, wird das Setzen seiner outerHTML-Eigenschaft es oder seine Nachfahren nicht ändern. Zum Beispiel:

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

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

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

Entkommene Attributwerte

Der zurückgegebene Wert entkommt einigen Werten in HTML-Attributen. Hier sehen wir, dass das &-Zeichen entkommen 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 Sicherheitsanfälligkeit (Mutation XSS) zu verhindern, in der ein Angreifer Eingaben erstellen kann, die eine Sanierungsfunktion umgehen, wodurch ein Cross-Site-Scripting (XSS)-Angriff ermöglicht wird.

Überlegungen zum Shadow DOM

Die Serialisierung des aus der Eigenschaft gelesenen DOM-Baums umfasst keine Shadow Roots. Wenn Sie eine HTML-Serialisierung eines Elements erhalten möchten, das Shadow Roots umfasst, müssen Sie stattdessen die Methode Element.getHTML() verwenden. Beachten Sie, dass dies die Inhalte des Elements holt.

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

Sicherheitsüberlegungen

Die outerHTML-Eigenschaft ist ein möglicher Vektor für Cross-Site-Scripting (XSS)-Angriffe, da sie verwendet werden kann, um potenziell unsichere von einem Benutzer bereitgestellte Strings in den DOM einzuschleusen. Obwohl die Eigenschaft verhindert, dass <script>-Elemente beim Einfügen ausgeführt werden, ist sie anfällig für viele andere Möglichkeiten, wie Angreifer HTML erstellen können, um bösartiges JavaScript auszuführen. Zum Beispiel würde der folgende Code in diesem Beispiel den Code im error-Event-Handler ausführen, da 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 mindern, indem Sie immer TrustedHTML-Objekte anstelle von Strings zuweisen und Trusted Types durchsetzen mithilfe der require-trusted-types-for-CSP-Richtlinie. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Möglichkeit hat, die Eingabe zu sanitieren, um potenziell gefährliche Markups zu entfernen, bevor es eingefügt wird.

Beispiele

Holen der Serialisierung eines Elements

Das Lesen von outerHTML verursacht, dass der User-Agent das Element serialisiert.

Bei folgendem HTML:

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

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

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

Ersetzen des Elements

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 dann dieses Objekt outerHTML zu.

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

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

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