ShadowRoot: `innerHTML`-Eigenschaft

Wert

Das Abrufen der Eigenschaft gibt eine Zeichenkette zurück, die die HTML-Serialisierung der Nachkommen des Shadow-Roots enthält.

Das Setzen der Eigenschaft akzeptiert entweder ein TrustedHTML-Objekt oder eine Zeichenkette. Es parst diesen Wert als HTML und ersetzt alle Nachkommen des Elements mit dem Ergebnis. Wenn er auf den Wert null gesetzt wird, wird dieser null-Wert in die leere Zeichenkette ("") umgewandelt, sodass shadowRoot.innerHTML = null gleichbedeutend mit shadowRoot.innerHTML = "" ist.

Ausnahmen

SyntaxError DOMException

Wird ausgelöst, wenn versucht wurde, den Wert von innerHTML mit einer Zeichenkette zu setzen, die nicht ordnungsgemäß formatiertes HTML ist.

TypeError

Wird ausgelöst, wenn die Eigenschaft auf eine Zeichenkette gesetzt wird, wenn Trusted Types durch eine CSP erzwungen werden und keine Standardrichtlinie definiert ist.

Beschreibung

innerHTML liest eine Serialisierung der verschachtelten Kind-DOM-Elemente innerhalb des Shadow-Roots oder setzt HTML oder XML, das geparst werden soll, um den DOM-Baum innerhalb des Shadow-Roots zu ersetzen.

Beachten Sie, dass einige Browser die Zeichen < und > als < und > serialisieren, 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 Sanitierungsfunktion umgehen und so einen Cross-Site-Scripting (XSS)-Angriff ermöglichen.

Sicherheitsüberlegungen

Die innerHTML-Eigenschaft ist ein potentieller Vektor für Cross-site-scripting (XSS)-Angriffe, bei denen potenziell unsichere vom Benutzer bereitgestellte Zeichenfolgen in den DOM injiziert werden, ohne vorher gesäubert zu werden. Während die Eigenschaft verhindert, dass <script>-Elemente ausgeführt werden, wenn sie injiziert werden, ist sie anfällig für viele andere Wege, wie Angreifer HTML erstellen können, um bösartigen JavaScript auszuführen. Zum Beispiel würde das folgende Beispiel den Code im error-Ereignishandler ausführen, weil der <img> src-Wert keine gültige Bild-URL ist:

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

Sie können diese Probleme mildern, indem Sie immer TrustedHTML-Objekte anstelle von Zeichenfolgen zuweisen und trusted types durchsetzen mit der require-trusted-types-for-CSP-Direktive. Dies stellt sicher, dass die Eingabe durch eine Transformationsfunktion geleitet wird, die die Gelegenheit hat, die Eingabe zu sanitizen, um potenziell gefährliches Markup zu entfernen, bevor es injiziert wird.

Beispiele

Lesen des HTML-Inhalts eines Elements

Das Lesen von innerHTML veranlasst den Benutzeragenten zur Serialisierung der Nachkommen des Shadow-Roots.

Angenommen, das folgende HTML:

<div class="host">
  <template shadowrootmode="open">
    <p>My name is Joe</p>
  </template>
</div>

Sie können das Markup des Shadow-Roots abrufen und protokollieren wie folgt:

const shadowHost = document.querySelector("#host");
const shadowRoot = shadowHost.shadowRoot;
const contents = shadowRoot.innerHTML;
console.log(contents); // "\n  <p>My name is Joe</p>\n"

Setzen von innerHTML eines Shadow-Roots

In diesem Beispiel werden wir den DOM eines Elements ersetzen, indem wir HTML in die innerHTML-Eigenschaft des Elements zuweisen. Um das Risiko von XSS zu mindern, erstellen wir zunächst ein TrustedHTML-Objekt aus der Zeichenkette, die das HTML enthält, und weisen dieses Objekt dann innerHTML zu.

Trusted Types 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()-Methode definiert, um eine Eingabezeichenkette in TrustedHTML-Instanzen zu transformieren. Häufig verwenden Implementierungen von createHTML() eine Bibliothek wie DOMPurify, um die Eingabe zu reinigen, 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 der potenziell unsicheren Eingabezeichenkette 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);

// Get the shadow root
const shadowHost = document.querySelector("#host");
const shadowRoot = shadowHost.shadowRoot;

// Inject the TrustedHTML (which contains a trusted string)
shadowRoot.innerHTML = trustedHTML;

Spezifikationen

Browser-Kompatibilität