Element: setHTML() Methode

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. Beachten Sie, dass im Allgemeinen ein Sanitizer effizienter erwartet wird als eine SanitizerConfig, wenn die Konfiguration wiederverwendet werden soll. Falls nicht angegeben, wird die Standard-Sanitizer-Konfiguration verwendet.

Keiner (undefined).

TypeError

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

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

Die setHTML() Methode bietet eine XSS-sichere Methode, um einen HTML-String zu parsen und zu säubern, in ein DocumentFragment umzuwandeln und dann als Teilbaum des Elements in das DOM einzufügen.

setHTML() entfernt alle Elemente im HTML-String, 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 von der Sanitizer-Konfiguration nicht erlaubt sind, und entfernt weitere XSS-unsichere Elemente oder Attribute — unabhängig davon, ob sie von der Sanitizer-Konfiguration erlaubt sind.

Wenn keine Sanitizer-Konfiguration im options.sanitizer Parameter angegeben wird, wird setHTML() mit der Standard-Sanitizer-Konfiguration verwendet. Diese Konfiguration erlaubt alle Elemente und Attribute, die als XSS-sicher gelten, und schließt somit Entitäten aus, die als unsicher gelten. Ein benutzerdefinierter Sanitizer oder eine benutzerdefinierte Sanitizer-Konfiguration kann spezifiziert werden, um zu wählen, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden. Beachten Sie, dass auch wenn unsichere Optionen von der Sanitizer-Konfiguration erlaubt werden, sie beim Verwenden dieser Methode trotzdem entfernt werden (die implizit Sanitizer.removeUnsafe() aufruft).

setHTML() sollte anstelle von Element.innerHTML verwendet werden, um nicht vertrauenswürdige HTML-Strings in ein Element einzufügen. Es sollte auch anstelle von Element.setHTMLUnsafe() verwendet werden, es sei denn, es besteht ein spezieller Bedarf, unsichere Elemente und Attribute zuzulassen.

Beachten Sie, dass diese Methode immer Eingabestrings von XSS-unsicheren Entitäten säubert, sie ist nicht durch die Trusted Types API gesichert oder validiert.

Dieses Beispiel zeigt einige der Möglichkeiten, wie Sie setHTML() verwenden können, um einen HTML-String zu säubern 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"] },
});

Dieses Beispiel bietet eine "Live"-Demonstration der Methode bei verschiedenen Sanitizern. Der Code definiert Schaltflächen, die Sie anklicken können, um einen HTML-String mit einem Standard- und einem benutzerdefinierten Sanitizer zu säubern und zu injizieren. Die ursprüngliche Zeichenkette und die bereinigte HTML werden protokolliert, damit Sie die Ergebnisse in jedem Fall überprüfen können.

HTML

Das HTML definiert zwei <button> Elemente zum Anwenden unterschiedlicher Sanitizer, eine weitere Schaltfläche zum Zurücksetzen des Beispiels und ein <div> Element zum Injizieren des Strings.

<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: 220px;
  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 säubernden String, der in allen Fällen gleich ist. Dieser enthält das <script> Element und den onclick Handler, die beide als XSS-unsafe gelten. Wir definieren auch den Handler für die Neuladenschaltfläche.

// Define unsafe string of HTML
const unsanitizedString = `
  <div>
    <p>This is a paragraph. <button onclick="alert('You clicked the button!')">Click me</button></p>
    <script src="path/to/a/module.js" type="module"><script>
  </div>
`;

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

Als nächstes definieren wir den Click-Handler für die Schaltfläche, die das HTML mit dem Standardsanitizer setzt. Dieser 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() Konstruktor-Beispielen 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 and onclick attribute\n\n";
  log(`\nunsanitized: ${unsanitizedString}`);
  log(`\nsanitized: ${target.innerHTML}`);
});

Der nächste Click-Handler setzt das Ziel-HTML unter Verwendung eines benutzerdefinierten Sanitizers, 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(`\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 des benutzerdefinierten Sanitizers zu sehen. Beachten Sie, dass in beiden Fällen das <script> Element und der onclick Handler entfernt werden, auch wenn sie ausdrücklich vom Sanitizer erlaubt sind.

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