Dokument: parseHTML() statische Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

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 Bereinigen eines HTML-Strings, um eine neue Document-Instanz zu erstellen.

Syntax

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

Parameter

input

Ein String, der HTML definiert, das bereinigt 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 Inputs erlaubt oder entfernt werden, oder der String "default" für die Standard-Konfiguration des Sanitizers. Beachten Sie, dass im Allgemeinen ein "Sanitizer" effizienter als ein SanitizerConfig erwartet wird, wenn die Konfiguration wiederverwendet werden soll. Wird nichts angegeben, wird die XSS-sichere Standardkonfiguration des Sanitizers verwendet.

Ausnahmen

TypeError

Diese Ausnahme wird geworfen, wenn options.sanitizer eines der folgenden erhält:

eine nicht normalisierte SanitizerConfig (eine, die sowohl "allowed" als auch "removed" Konfigurationseinstellungen enthält).
einen String, der nicht den Wert "default" hat.
einen Wert, der weder ein Sanitizer, noch ein SanitizerConfig oder String ist.

Die parseHTML()-Methode parst und bereinigt einen HTML-String, um eine neue Document-Instanz zu erstellen, die XSS-sicher ist. Das resultierende Document wird einen content type von "text/html", einen character set von UTF-8 und eine URL von "about:blank" haben.

Falls keine Konfiguration des Sanitizers im options.sanitizer-Parameter angegeben ist, wird parseHTML() mit der Standardkonfiguration des Sanitizer verwendet. Diese Konfiguration erlaubt alle Elemente und Attribute, die als XSS-sicher gelten, und verbietet somit Entitäten, die als unsicher gelten. Ein benutzerdefinierter Sanitizer oder eine benutzerdefinierte Sanitizer-Konfiguration kann angegeben werden, um auszuwählen, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden. Beachten Sie, dass selbst wenn unsichere Optionen durch die Sanitizer-Konfiguration erlaubt sind, sie dennoch entfernt werden, wenn diese Methode verwendet wird (was implizit den Aufruf von Sanitizer.removeUnsafe() beinhaltet).

Der eingegebene HTML-String kann deklarative Shadow-Roots enthalten. Wenn der HTML-String mehr als einen deklarativen Shadow-Root in einem bestimmten Shadow-Host definiert, wird nur der erste ShadowRoot erstellt — nachfolgende Deklarationen werden als <template>-Elemente innerhalb dieses Shadow-Roots geparst.

parseHTML() sollte statt 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, sollte Document.parseHTML() verwendet werden.

Da diese Methode eingehende Strings von XSS-unsicheren Entitäten immer bereinigt, wird dies nicht durch die Trusted Types API gesichert oder validiert.