ShadowRoot: setHTML() Methode

Syntax

setHTML(input)
setHTML(input, options)

Parameter

input

Ein String, der das zu bereinigende und in den Shadow Root einzufgende HTML definiert.

options Optional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizer

Ein Sanitizer oder SanitizerConfig Objekt, das definiert, welche Elemente des Eingabewerts erlaubt oder entfernt werden, oder der String "default" fr die Standard-Sanitizer-Konfiguration. Die Methode entfernt alle XSS-gefhrlichen Elemente und Attribute, auch wenn sie durch den Sanitizer erlaubt sind. Wenn nicht angegeben, wird die Standardkonfiguration von Sanitizer verwendet.

Beachten Sie, dass es effizienter ist, einen Sanitizer zu verwenden und diesen bei Bedarf zu modifizieren, wenn Sie die gleiche Konfiguration mehrfach verwenden.

Rckgabewert

Keiner (undefined).

Ausnahmen

TypeError

Wird ausgelst, wenn options.sanitizer bergeben wird mit:

• einer SanitizerConfig, die nicht gltig ist. Zum Beispiel eine Konfiguration, die sowohl "erlaubte" als auch "entfernte" Konfigurationseinstellungen enthlt.
• einem String, der nicht den Wert "default" hat.
• einem Wert, der kein Sanitizer, SanitizerConfig oder String ist.

Beschreibung

Die setHTML() Methode bietet eine XSS-sichere Methode, um einen HTML-String zu parsen und zu bereinigen und diesen zu verwenden, um den bestehenden Baum im Shadow DOM zu ersetzen.

setHTML() entfernt alle HTML-Entitten, die nicht durch die Sanitizer-Konfiguration erlaubt sind, und entfernt weiterhin alle XSS-gefhrlichen Elemente oder Attribute unabhngig davon, ob sie durch die Sanitizer-Konfiguration erlaubt sind oder nicht.

Wenn kein Sanitizer im Parameter options.sanitizer angegeben ist, wird setHTML() mit der Standard-Sanitizer-Konfiguration verwendet. Diese Konfiguration ist fr die meisten Anwendungsflle geeignet, da sie XSS-Angriffe sowie andere Angriffe wie Clickjacking oder Spoofing verhindert.

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

setHTML() sollte anstelle von ShadowRoot.innerHTML verwendet werden, um nicht vertrauenswrdige HTML-Strings in das Shadow DOM einzufgen. Es sollte auch anstelle von ShadowRoot.setHTMLUnsafe() verwendet werden, es sei denn, es besteht ein spezifisches Bedrfnis, unsichere Elemente und Attribute zuzulassen.

Beachten Sie, dass diese Methode Eingabestrings von XSS-gefhrlichen Entitten immer bereinigt, sie ist nicht gesichert oder validiert durch die Trusted Types API.

Beispiele

Grundlegende Verwendung

Dieses Beispiel zeigt einige der Mglichkeiten, wie Sie setHTML() verwenden knnen, um einen HTML-String zu bereinigen und einzufgen.

Zuerst erstellen wir den ShadowRoot, den wir anvisieren wollen. Dieser knnte programmatisch mit Element.attachShadow() erstellt werden, aber fr dieses Beispiel erstellen wir den Root deklarativ.

<div id="host">
  <template shadowrootmode="open">
    <span>A span element in the shadow DOM</span>
  </template>
</div>

Wir knnen einen Zugriff auf den Shadow Root vom #host Element so erhalten:

const shadow = document.querySelector("#host").shadowRoot;

Der untenstehende Code zeigt, wie wir setHTML() mit einem String und verschiedenen Sanitizern aufrufen knnen, um das HTML zu filtern und in den Shadow Root einzufgen.

// Define unsanitized string of HTML
const unsanitizedString = "abc <script>alert(1)<" + "/script> def";

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

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

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

setHTML() Live-Beispiel

Dieses Beispiel bietet eine "Live"-Demonstration der Methode, wenn sie mit verschiedenen Sanitizern aufgerufen wird. Der Code definiert Schaltflchen, die Sie anklicken knnen, um einen HTML-String mit einem Standard- und einem benutzerdefinierten Sanitizer zu bereinigen und einzufgen. Der Originalstring und das bereinigte HTML werden protokolliert, sodass Sie die Ergebnisse in jedem Fall inspizieren knnen.

HTML

Das HTML definiert zwei <button> Elemente fr die Anwendung verschiedener Sanitizer, einen weiteren Button, um das Beispiel zurckzusetzen, und ein <div>, das den deklarativen Shadow Root enthlt.

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

<div id="host">
  <template shadowrootmode="open">
    <span>I am in the shadow DOM </span>
  </template>
</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 Handler fr den Reload-Button.

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

Dann definieren wir den zu bereinigenden String, der fr alle Flle derselbe ist. Dieser enthlt das <script> Element und den onclick Handler, die beide als XSS-gefhrlich gelten. Wir erhalten auch die Variable shadow, die unser Zugriff auf den Shadow Root ist.

// Define unsafe string of HTML
const unsanitizedString = `
  <div>
    <p>Paragraph to inject into shadow DOM.
      <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 shadow = document.querySelector("#host").shadowRoot;

Als nchstes definieren wir den Click-Handler fr den Button, der den Shadow Root mit dem Standard-Sanitizer setzt. Dies sollte alle unsicheren Entitten entfernen, bevor der HTML-String eingefgt wird. Beachten Sie, dass Sie genau sehen knnen, 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
  shadow.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: ${shadow.innerHTML}`);
});

Der nchste 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> trotzdem 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"],
  });
  shadow.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: ${shadow.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 Buttons, um die Effekte des Standard- und des benutzerdefinierten Sanitizers zu sehen.

Beachten Sie, dass weil wir eine sichere Bereinigungsmethode verwenden, in beiden Fllen das <script> Element und der onclick Handler entfernt werden, selbst wenn sie explizit durch den Sanitizer erlaubt sind. Whrend das data- Attribut mit dem Standard-Sanitizer entfernt wird, ist es erlaubt, wenn wir einen Sanitizer bergeben.

Spezifikationen

Browser-Kompatibilitt

Siehe auch

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