Element: setHTML() Methode

Syntax

setHTML(input)
setHTML(input, options)

Parameter

input

Eine Zeichenkette, die HTML definiert, das bereinigt und in das Element eingefügt werden soll.

options Optional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizer

Ein Sanitizer oder SanitizerConfig Objekt, das definiert, welche Elemente des Inputs erlaubt oder entfernt werden, oder die Zeichenkette "default" für die Standardkonfiguration. Die Methode entfernt alle XSS-unsicheren Elemente und Attribute, selbst wenn sie vom Sanitizer erlaubt sind.

Beachten Sie, dass ein Sanitizer im Allgemeinen effizienter ist als eine SanitizerConfig, wenn die Konfiguration wiederverwendet werden soll. Wenn nicht angegeben, wird die Standard-Sanitizer-Konfiguration verwendet.

Rückgabewert

Keiner (undefined).

Ausnahmen

TypeError

Dies wird ausgelöst, wenn options.sanitizer übergeben wird:

• eine nicht normalisierte SanitizerConfig (eine, die sowohl "allowed"- als auch "removed"-Konfigurationseinstellungen enthält).
• eine Zeichenkette, die nicht den Wert "default" hat.
• ein Wert, der kein Sanitizer, SanitizerConfig oder eine Zeichenkette ist.

Beschreibung

Die setHTML() Methode bietet eine XSS-sichere Methode, um eine Zeichenkette von HTML in ein DocumentFragment zu parsen und zu bereinigen und sie dann als Unterbaum des Elements in das DOM einzufügen.

setHTML() verwirft alle Elemente in der HTML-Input-Zeichenkette, die im Kontext des aktuellen Elements ungültig sind, wie etwa ein <col> Element außerhalb eines <table>. Es entfernt dann alle HTML-Entitäten, die von der Sanitizer-Konfiguration nicht erlaubt sind, und entfernt weiter alle XSS-unsicheren Elemente oder Attribute – unabhängig davon, ob sie von der Sanitizer-Konfiguration erlaubt sind oder nicht.

Wenn keine Sanitizer-Konfiguration im Parameter options.sanitizer angegeben ist, wird setHTML() mit der Standardkonfiguration von Sanitizer verwendet. Diese Konfiguration erlaubt alle Elemente und Attribute, die als XSS-sicher gelten, wodurch Entitäten, die als unsicher gelten, nicht erlaubt werden; siehe den Sanitizer() Konstruktor für weitere Informationen. Ein benutzerdefinierter Sanitizer oder eine Sanitizer-Konfiguration kann angegeben werden, um auszuwählen, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden. Beachten Sie, dass unsichere Optionen, selbst wenn sie von der Sanitizer-Konfiguration erlaubt sind, bei Verwendung dieser Methode immer noch entfernt werden (die implizit Sanitizer.removeUnsafe() aufruft).

setHTML() sollte anstelle von Element.innerHTML verwendet werden, um unzuverlässige Zeichenketten von HTML in ein Element einzufügen. Es sollte auch anstelle von Element.setHTMLUnsafe() verwendet werden, es sei denn, es besteht ein spezifisches Bedürfnis, unsichere Elemente und Attribute zu erlauben.

Beachten Sie, dass diese Methode immer Eingabezeichenketten von XSS-unsicheren Entitäten bereinigt, es wird nicht mithilfe der Trusted Types API gesichert oder validiert.

Beispiele

Grundlegende Verwendung

Dieses Beispiel zeigt einige der Möglichkeiten, wie Sie setHTML() verwenden können, um eine Zeichenkette von HTML zu bereinigen und zu injizieren.

// Define unsanitized string of HTML
const unsanitizedString = "abc <script>alert(1)<" + "/script> def";
// Get the target Element with id "target"
const target = document.getElementById("target");

// setHTML() with default sanitizer
target.setHTML(unsanitizedString);

// Define custom Sanitizer and use in setHTML()
// This allows only elements: div, p, button (script is unsafe and will be removed)
const sanitizer1 = new Sanitizer({
  elements: ["div", "p", "button", "script"],
});
target.setHTML(unsanitizedString, { sanitizer: sanitizer1 });

// Define custom SanitizerConfig within setHTML()
// This removes elements div, p, button, script, and any other unsafe elements/attributes
target.setHTML(unsanitizedString, {
  sanitizer: { removeElements: ["div", "p", "button", "script"] },
});

setHTML() Live-Beispiel

Dieses Beispiel bietet eine "Live"-Demonstration der Methode, wenn sie mit verschiedenen Sanitisierern aufgerufen wird. Der Code definiert Schaltflächen, die Sie klicken können, um eine Zeichenkette von HTML mit einem Standard- und einem benutzerdefinierten Sanitizer zu bereinigen und zu injizieren. Die ursprüngliche Zeichenkette und das bereinigte HTML werden protokolliert, damit Sie die Ergebnisse in jedem Fall inspizieren können.

HTML

Das HTML definiert zwei <button> Elemente zum Anwenden verschiedener Sanitisierverfahren, eine weitere Schaltfläche zum Zurücksetzen des Beispiels und ein <div> Element, um die Zeichenkette einzufügen.

<button id="buttonDefault" type="button">Default</button>
<button id="buttonAllowScript" type="button">allowScript</button>

<button id="reload" type="button">Reload</button>
<div id="target">Original content of target element</div>

<pre id="log"></pre>

#log {
  height: 320px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
  margin: 5px;
}

JavaScript

const logElement = document.querySelector("#log");
function log(text) {
  logElement.textContent += text;
}

if ("Sanitizer" in window) {

Zuerst definieren wir die zu bereinigende Zeichenkette, die für alle Fälle dieselbe sein wird. Diese enthält das <script> Element und den onclick Handler, die beide als XSS-unsicher gelten. Wir definieren auch den Handler für die Neulade-Schaltfläche.

// Define unsafe string of HTML
const unsanitizedString = `
  <div>
    <p>Paragraph to inject into shadow DOM.
      <button onclick="alert('You clicked the button!')">Click me</button>
    </p>
    <script src="path/to/a/module.js" type="module"><\/script>
    <p data-id="123">Para with <code>data-</code> attribute</p>
  </div>
`;

const reload = document.querySelector("#reload");
reload.addEventListener("click", () => document.location.reload());

Als nächstes definieren wir den Klick-Handler für die Schaltfläche, die das HTML mit dem Standardsanitizer setzt. Dies sollte alle unsicheren Entitäten entfernen, bevor die Zeichenkette von HTML eingefügt wird. Beachten Sie, dass Sie genau sehen können, welche Elemente in den Sanitizer() Konstruktorbeispielen entfernt werden.

const defaultSanitizerButton = document.querySelector("#buttonDefault");
defaultSanitizerButton.addEventListener("click", () => {
  // Set the content of the element using the default sanitizer
  target.setHTML(unsanitizedString);

  // Log HTML before sanitization and after being injected
  logElement.textContent =
    "Default sanitizer: remove script element, onclick attribute, data- attribute\n\n";
  log(`\nunsanitized: ${unsanitizedString}`);
  log(`\n\nsanitized: ${target.innerHTML}`);
});

Der nächste Klick-Handler setzt das Ziel-HTML mit einem benutzerdefinierten Sanitizer, der nur <div>, <p> und <script> Elemente erlaubt. Beachten Sie, dass, weil wir die setHTML Methode verwenden, <script> ebenfalls entfernt wird!

const allowScriptButton = document.querySelector("#buttonAllowScript");
allowScriptButton.addEventListener("click", () => {
  // Set the content of the element using a custom sanitizer
  const sanitizer1 = new Sanitizer({
    elements: ["div", "p", "script"],
  });
  target.setHTML(unsanitizedString, { sanitizer: sanitizer1 });

  // Log HTML before sanitization and after being injected
  logElement.textContent =
    "Sanitizer: {elements: ['div', 'p', 'script']}\n Script removed even though allowed\n";
  log(`\nunsanitized: ${unsanitizedString}`);
  log(`\n\nsanitized: ${target.innerHTML}`);
});

} else {
  log("The HTML Sanitizer API is NOT supported in this browser.");
  // Provide fallback or alternative behavior
}

Ergebnisse

Klicken Sie auf die "Default" und "allowScript" Schaltflächen, um die Effekte des Standard- und benutzerdefinierten Sanitisierers zu sehen.

Beachten Sie, dass weil wir eine sichere Bereinigungsmethode verwenden, in beiden Fällen das <script> Element und der onclick Handler entfernt werden, selbst wenn sie durch den Sanitisierer explizit erlaubt sind. Während das data- Attribut mit dem Standardsanitizer entfernt wird, bleibt es erhalten, wenn wir einen Sanitisierer verwenden.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Element.setHTMLUnsafe()
• ShadowRoot.setHTML() und ShadowRoot.setHTMLUnsafe()
• Document.parseHTML() und Document.parseHTMLUnsafe()
• HTML Sanitizer API