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 seront autorisés ou supprimés, ou la chaîne de caractères "default" pour la configuration par défaut du nettoyeur. Notez que de manière générale, un Sanitizer est censé être plus efficace qu'un SanitizerConfig si la configuration doit être réutilisée. Si rien n'est défini, la configuration par défaut d'assainissement XSS est utilisée.

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 aura un type de contenu de "text/html", un encodage de caractères UTF-8 et une URL « about:blank ».

Si aucune configuration du nettoyeur n'est précisée dans le paramètre options.sanitizer, parseHTML() utilise la configuration par défaut de Sanitizer. Cette configuration autorise tous les éléments et attributs considérés comme sûrs vis‑à‑vis des XSS, et refuse donc les entités considérées comme dangereuses. 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 la configuration d'assainissement, elles seront 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