Element: setHTML() Methode

Syntax

setHTML(input)
setHTML(input, options)

Parameter

input

Ein String, der 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 Eingangs erlaubt oder entfernt werden, oder der String "default" für die Standardkonfiguration. Die Methode entfernt alle XSS-unsicheren Elemente und Attribute, selbst wenn sie vom Sanitizer erlaubt werden.

Beachten Sie, dass im Allgemeinen ein Sanitizer effizienter als ein SanitizerConfig sein soll, 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 folgende Werte übergeben werden:

• Ein SanitizerConfig, das nicht gültig ist. Zum Beispiel eine Konfiguration, die sowohl "allowed" als auch "removed" Konfigurationseinstellungen enthält.
• ein String, der nicht den Wert "default" hat.
• ein Wert, der kein Sanitizer, SanitizerConfig oder String ist.

Beschreibung

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

setHTML() lässt alle Elemente im HTML-String fallen, die im Kontext des aktuellen Elements ungültig sind, wie ein <col> Element außerhalb einer <table>. Es entfernt dann alle HTML-Entitäten, die nicht durch die Sanitizer-Konfiguration erlaubt sind, und entfernt weiterhin jegliche 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 Standard Sanitizer Konfiguration verwendet. Diese Konfiguration erlaubt alle als XSS-sicher geltenden Elemente und Attribute und lehnt daher die als unsicher geltenden Entitäten ab; sehen Sie 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 auch wenn unsichere Optionen von der Sanitizer-Konfiguration erlaubt werden, sie bei Verwendung dieser Methode immer noch entfernt werden (was implizit Sanitizer.removeUnsafe() aufruft).

setHTML() sollte anstelle von Element.innerHTML verwendet werden, um unzuverlässige HTML-Strings 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 zuzulassen.

Da diese Methode immer Eingabestrings von XSS-unsicheren Entitäten bereinigt, ist sie nicht durch die Trusted Types API gesichert oder validiert.

Beispiele

Grundlegende Verwendung

Dieses Beispiel zeigt einige der Möglichkeiten, wie Sie setHTML() verwenden können, um einen HTML-String zu bereinigen und einzufügen.

// 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 bei Aufruf mit verschiedenen Sanitisern. Der Code definiert Schaltflächen, die Sie anklicken können, um einen HTML-String mit einem Standard- und einem benutzerdefinierten Sanitizer zu bereinigen und einzufügen. Der Originalstring und das bereinigte HTML werden protokolliert, sodass Sie die Ergebnisse in jedem Fall überprüfen können.

HTML

Das HTML definiert zwei <button> Elemente zur Anwendung verschiedener Sanitisers, einen weiteren Button, um das Beispiel zurückzusetzen, und ein <div> Element, um den String 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 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-unsicher gelten. Wir definieren auch den Handler für die Neuladen-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. Dieser sollte alle unsicheren Entitäten entfernen, bevor der HTML-String eingefügt wird. Beachten Sie, dass Sie genau sehen können, welche Elemente im Sanitizer() Konstruktorbeispiel 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 mittels eines benutzerdefinierten Sanitisers, das nur <div>, <p>, und <script> Elemente erlaubt. Beachten Sie, dass, weil wir die Methode setHTML verwenden, <script> auch 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 Buttons "Default" und "allowScript", um die Effekte des Standard- bzw. benutzerdefinierten Sanitisers 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 ausdrücklich von dem Sanitizer erlaubt wurden. Während das data- Attribut mit dem Standard-Sanitizer entfernt wird, wird es erlaubt, 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