Dokument: parseHTML() statische Methode

Eingeschränkt verfügbar

Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die parseHTML()-statische Methode des Document-Objekts bietet eine XSS-sichere Methode zum Parsen und Sanitisieren eines HTML-Strings, um eine neue Document-Instanz zu erstellen.

In diesem Artikel

Syntax

js
Document.parseHTML(input)
Document.parseHTML(input, options)

Parameter

input

Ein String, der HTML definiert, das sanisiert und in den Shadow-Root eingefügt werden soll.

options Optional

Ein Optionsobjekt mit den folgenden optionalen Parametern:

sanitizer

Ein Sanitizer oder SanitizerConfig Objekt, das definiert, welche Elemente des Eingabe-Strings erlaubt oder entfernt werden, oder der String "default" für die Standard-Sanitizer-Konfiguration. Die Methode entfernt alle XSS-unsicheren Elemente und Attribute, selbst wenn sie vom Sanitizer erlaubt sind. Wenn nicht angegeben, wird die Standard-Sanitizer-Konfiguration verwendet.

Beachten Sie, dass es effizienter sein kann, bei mehrfacher Verwendung derselben Konfiguration einen Sanitizer zu verwenden und diesen bei Bedarf zu modifizieren.

Rückgabewert

Ein Document.

Ausnahmen

TypeError

Dies wird ausgelöst, wenn options.sanitizer einen Wert erhält:

SanitizerConfig, die nicht gültig ist. Zum Beispiel eine Konfiguration, die sowohl "allowed" als auch "removed" Einstellungsparameter umfasst.
Ein String, der nicht den Wert "default" hat.
Ein Wert, der kein Sanitizer, SanitizerConfig oder String ist.

Beschreibung

Die parseHTML()-Methode parst und sanitized einen HTML-String, um eine neue Document-Instanz zu erstellen, die XSS-sicher ist. Das resultierende Document hat einen Content-Type von "text/html", einen Zeichensatz von UTF-8 und eine URL von "about:blank".

Wenn im Parameter options.sanitizer kein Sanitizer angegeben ist, wird parseHTML() mit der Standard-Sanitizer-Konfiguration verwendet. Diese Konfiguration ist für die meisten 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. Beachten Sie, dass selbst wenn unsichere Optionen vom Sanitizer erlaubt sind, sie bei Verwendung dieser Methode weiterhin entfernt werden (sie entfernt dieselben Elemente wie ein Sanitizer, auf dem Sanitizer.removeUnsafe() aufgerufen wurde).

Das Eingabe-HTML kann declarative shadow roots enthalten. Wenn der HTML-String mehr als einen declarative shadow root in einem bestimmten Shadow-Host definiert, wird nur das erste ShadowRoot erstellt — nachfolgende Deklarationen werden als <template>-Elemente innerhalb dieses Shadow-Roots geparst.

parseHTML() sollte anstelle von Document.parseHTMLUnsafe() verwendet werden, es sei denn, es besteht ein spezifisches Bedürfnis, unsichere Elemente und Attribute zuzulassen. Wenn das zu parsende HTML keine unsicheren HTML-Entitäten enthalten muss, sollten Sie Document.parseHTML() verwenden.

Beachten Sie, dass diese Methode immer Eingabestrings von XSS-unsicheren Entitäten sanisiert und nicht durch die Trusted Types API gesichert oder validiert wird.