Document : méthode statique parseHTML()

Syntaxe

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

Paramètres

input

Une chaîne de caractères définissant le HTML à analyser et à injecter dans la racine d'ombre.

options Facultatif

Un objet d'options avec les paramètres optionnels suivants :

sanitizer

Un objet Sanitizer ou SanitizerConfig qui définit quels éléments de l'entrée sont autorisés ou supprimés, ou la chaîne de caractères "default" pour la configuration par défaut de l'assainisseur. La méthode supprime tous les éléments et attributs non sécurisés pour les XSS, même s'ils sont autorisés par l'assainisseur. Si aucun objet n'est défini, la configuration par défaut du Sanitizer est utilisée.

Notez que si vous utilisez la même configuration plusieurs fois, il est prévu qu'il soit plus efficace d'utiliser un Sanitizer et de le modifier lorsque vous en avez besoin.

Valeur de retour

Un objet Document.

Exceptions

TypeError

Est levée si options.sanitizer reçoit :

• SanitizerConfig qui n'est pas valide. Par exemple, une configuration qui inclut à la fois les paramètres "allowed" et "removed".
• une chaîne de caractères qui n'a pas la valeur "default".
• une valeur qui n'est pas un Sanitizer, SanitizerConfig, ou une chaîne de caractères.

Description

La méthode parseHTML() analyse et assainit une chaîne de caractères HTML afin de créer une nouvelle instance de Document sécurisée contre les XSS. Le Document résultant a un type de contenu de "text/html", un encodage de caractères UTF-8 et une URL « about:blank ».

Si aucun assainisseur n'est défini dans le paramètre options.sanitizer, parseHTML() utilise la configuration par défaut de l'assainisseur. Cette configuration est adaptée à la majorité des cas d'utilisation, car elle empêche les attaques XSS, ainsi que d'autres attaques comme l'usurpation de clics ou l'usurpation d'identité.

Un assainisseur personnalisé ou une configuration d'assainissement peut être défini pour choisir quels éléments, attributs et commentaires sont autorisés ou supprimés. Notez que même si des options non sécurisées sont autorisées par l'assainisseur, elles sont néanmoins supprimées lors de l'utilisation de cette méthode (qui appelle implicitement Sanitizer.removeUnsafe()).

Le HTML d'entrée peut inclure des racines d'ombre déclaratives. Si la chaîne HTML définit plus d'une racine d'ombre déclarative dans un hôte d'ombre donné, seule la première ShadowRoot est créée — les déclarations suivantes sont analysées comme des éléments <template> à l'intérieur de cette racine d'ombre.

parseHTML() doit être utilisé plutôt que Document.parseHTMLUnsafe(), sauf s'il existe un besoin spécifique d'autoriser des éléments et attributs non sécurisés. Si le HTML à analyser n'a pas besoin de contenir des entités HTML non sécurisées, vous devriez utiliser Document.parseHTML().

Notez que, comme cette méthode assainit toujours les chaînes d'entrée contenant des entités non sécurisées au regard des XSS, elle n'est pas sécurisée ni validée à l'aide de l'API Trusted Types.

Spécifications

Compatibilité des navigateurs

Voir aussi

• La méthode statique Document.parseHTMLUnsafe()
• Les méthodes Element.setHTML() et Element.setHTMLUnsafe()
• Les méthodes ShadowRoot.setHTML() et ShadowRoot.setHTMLUnsafe()
• La méthode DOMParser.parseFromString() pour analyser du HTML ou XML en un arbre DOM
• L'API HTML Sanitizer