Element: setHTML() Methode

Syntax

setHTML(input)
setHTML(input, options)

Parameter

input

Ein String, der HTML definiert, das bereinigt und in das Element injiziert 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 der String "default" für die Standardkonfiguration. Die Methode entfernt alle XSS-gefährlichen Elemente und Attribute, selbst wenn dies durch den Sanitizer erlaubt ist. Wenn nicht angegeben, wird die Standard-Sanitizer-Konfiguration verwendet.

Beachten Sie, dass es effizienter sein kann, einen Sanitizer zu verwenden und diesen bei Bedarf zu ändern, wenn dieselbe Konfiguration mehrmals verwendet wird.

Rückgabewert

Keinen (undefined).

Ausnahmen

TypeError

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

• SanitizerConfig, die nicht gültig ist. Zum Beispiel eine Konfiguration, die sowohl "erlaubte" als auch "entfernte" Konfigurationseinstellungen enthält.
• ein String, der nicht den Wert "default" hat.
• ein Wert, der weder ein Sanitizer, SanitizerConfig noch ein String ist.

Beschreibung

Die setHTML()-Methode bietet eine XSS-sichere Methode, um einen HTML-String in ein DocumentFragment zu parsen und zu bereinigen und ihn dann als Unterbaum des Elements ins DOM einzufügen.

setHTML() lässt alle Elemente im HTML-Input-String fallen, die im Kontext des aktuellen Elements ungültig sind, wie zum Beispiel ein <col>-Element außerhalb einer <table>. Anschließend entfernt es alle HTML-Entitäten, die durch die Sanitizer-Konfiguration nicht erlaubt sind, und entfernt weiter alle XSS-gefährlichen Elemente oder Attribute — unabhängig davon, ob diese durch den Sanitizer erlaubt sind oder nicht.

Wird kein Sanitizer im options.sanitizer-Parameter angegeben, wird setHTML() mit der Standard-Sanitizer-Konfiguration verwendet. Diese Konfiguration ist für die Mehrheit der Anwendungsfälle geeignet, da sie XSS-Angriffe sowie andere Angriffe wie Clickjacking oder Spoofing verhindert.

Ein benutzerdefinierter Sanitizer oder SanitizerConfig kann angegeben werden, um auszuwählen, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden sollen. Beachten Sie, dass selbst wenn unsichere Optionen durch den Sanitizer erlaubt sind, sie bei Verwendung dieser Methode dennoch entfernt werden (sie entfernt die gleichen Elemente wie ein Sanitizer, bei dem Sanitizer.removeUnsafe() aufgerufen wurde).

setHTML() sollte anstelle von Element.innerHTML verwendet werden, um unzuverlässige Strings von HTML in ein Element einzufügen. Es sollte auch anstelle von Element.setHTMLUnsafe() verwendet werden, es sei denn, es gibt einen spezifischen Bedarf, unsichere Elemente und Attribute zuzulassen.

Beachten Sie, dass diese Methode Eingabestrings von XSS-gefährlichen Entitäten immer bereinigt und daher nicht gesichert oder validiert wird unter Verwendung der Trusted Types API.

Beispiele

Grundlegende Verwendung

Dieses Beispiel zeigt einige der Möglichkeiten, wie Sie setHTML() verwenden können, um einen HTML-String 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 Sanitizern aufgerufen wird. Der Code definiert Schaltflächen, die Sie anklicken können, um einen HTML-String unter Verwendung eines Standard- und eines benutzerdefinierten Sanitizers zu bereinigen und zu injizieren. Der ursprüngliche String und das bereinigte HTML werden protokolliert, sodass Sie die Ergebnisse in jedem Fall inspizieren können.

HTML

Das HTML definiert zwei <button>-Elemente zum Anwenden verschiedener Sanitizer, eine weitere Schaltfläche, um das Beispiel zurückzusetzen, und ein <div>-Element, um den String zu injizieren.

<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 den zu bereinigenden String, der für alle Fälle gleich sein wird. Dieser enthält das <script>-Element und den onclick-Handler, die beide als XSS-gefährlich gelten. Wir definieren auch den Handler für die Reload-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 der HTML-String 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 unter Verwendung eines benutzerdefinierten Sanitizers, der nur die <div>, <p> und <script>-Elemente zulässt. Beachten Sie, dass <script> entfernt wird, weil wir die setHTML-Methode verwenden!

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 Schaltflächen "Default" und "allowScript", um die Auswirkungen des Standard- und des benutzerdefinierten Sanitizers 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 Sanitizer ausdrücklich erlaubt sind. Während jedoch das data- Attribut beim Standardsanitizer entfernt wird, wird es zugelassen, wenn wir einen Sanitizer übergeben.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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