Element: setHTML() Methode

input

Ein String, der HTML definiert, welches bereinigt und in das Element eingefügt wird.

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 in der Regel ein Sanitizer effizienter als eine SanitizerConfig ist, wenn die Konfiguration wiederverwendet werden soll. Wenn nicht angegeben, wird die Standard-Sanitizerkonfiguration verwendet.

Kein Wert (undefined).

TypeError

Dies wird geworfen, 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 String von HTML zu analysieren und zu bereinigen, und dann in ein DocumentFragment umzuwandeln und als Teilbaum des Elements in den DOM einzufügen.

setHTML() verwirft alle Elemente im HTML-Input-String, die im Kontext des aktuellen Elements ungültig sind, wie z.B. ein <col> Element außerhalb einer <table>. Anschließend entfernt es alle HTML-Entitäten, die durch die Sanitizerkonfiguration nicht erlaubt sind, sowie weitere XSS-unsichere Elemente oder Attribute — unabhängig davon, ob sie durch die Sanitizerkonfiguration erlaubt sind oder nicht.

Wenn keine Sanitizerkonfiguration im Parameter options.sanitizer angegeben wird, wird setHTML() mit der Standard- Sanitizer Konfiguration verwendet. Diese Konfiguration erlaubt alle Elemente und Attribute, die als XSS-sicher gelten, und damit werden Entitäten, die als unsicher gelten, nicht zugelassen. Ein benutzerdefinierter Sanitizer oder eine benutzerdefinierte Sanitizerkonfiguration kann angegeben werden, um auszuwählen, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden. Beachten Sie, dass selbst wenn unsichere Optionen durch die Sanitizerkonfiguration erlaubt werden, diese beim Verwenden dieser Methode dennoch entfernt werden (welche implizit Sanitizer.removeUnsafe() aufruft).

setHTML() sollte anstelle von Element.innerHTML für das Einfügen von nicht vertrauenswürdigen HTML-Strings in ein Element verwendet werden. 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 immer XSS-unsichere Eingabestrings bereinigt und dass dieser Prozess nicht durch die Trusted Types API gesichert oder validiert wird.

Dieses Beispiel zeigt einige der Möglichkeiten, setHTML() zu verwenden, 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"] },
});

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

HTML

Das HTML definiert zwei <button> Elemente, um unterschiedliche Sanitizer anzuwenden, eine weitere Schaltfläche zum Zurücksetzen des Beispiels und ein <div> Element, in das der String injiziert wird.

<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 String, der bereinigt werden soll, der in allen Fällen gleich sein wird. Dieser enthält das <script> Element und den onclick Handler, die beide als XSS-unsafe angesehen werden. Wir definieren auch den Handler für die Neuladen-Schaltflä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 Klick-Handler für die Schaltfläche, die das HTML mit dem Standard-Sanitizer 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 and onclick attribute\n\n";
  log(`\nunsanitized: ${unsanitizedString}`);
  log(`\nsanitized: ${target.innerHTML}`);
});

Der nächste Klick-Handler setzt das Ziel-HTML mithilfe eines benutzerdefinierten Sanitizers, der nur <div>, <p> und <script> Elemente erlaubt. Beachten Sie, dass, da 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 Schaltflächen "Default" und "allowScript", um die Auswirkungen des Standard- und benutzerdefinierten Sanitizers zu sehen. Beachten Sie, dass in beiden Fällen das <script> Element und der onclick Handler entfernt werden, auch wenn sie explizit vom Sanitizer erlaubt sind.

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