Document: parseHTML() 静的メソッド

構文

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

引数

input

無害化され、シャドウルートに挿入される HTML を定義する文字列です。

options 省略可

以下のオプション引数を持つオプションオブジェクトです。

sanitizer

Sanitizer または SanitizerConfig オブジェクトで、入力のどの要素を許可または削除するかを定義します。または、文字列 "default" を指定してデフォルトのサニタイザー設定を使用できます。 サニタイザーで許可されていても、XSS に対して安全でない要素と属性はこのメソッドによって削除されます。 指定しなかった場合は、デフォルトの Sanitizer 設定が使用されます。 同じ設定を複数回使う場合は、必要に応じて変更できる Sanitizer を使う方が効率的です。

返値

Document です。

例外

TypeError

options.sanitizer に次のようなものが渡された場合に例外が発生します。

• 有効でない SanitizerConfig。例えば、"allowed" と "removed" の両方の設定を含むもの。
• 値が "default" ではない文字列
• Sanitizer、SanitizerConfig、文字列のどれでもない値。

解説

parseHTML() メソッドは、HTML 文字列を構文解析して無害化し、XSS に対して安全な新しい Document インスタンスを生成します。 生成される Document のコンテンツタイプは "text/html"、文字コードは UTF-8、URL は "about:blank" です。

options.sanitizer 引数にサニタイザーが指定されていない場合、parseHTML() はデフォルトのサニタイザー設定を使用します。 この設定は、XSS 攻撃だけでなく、クリックジャッキングやなりすましなどの攻撃も防ぐため、ほとんどの用途に適しています。

独自の Sanitizer または SanitizerConfig を指定して、許可または削除する要素、属性、コメントを選択できます。 サニタイザーで安全でないオプションが許可されていても、このメソッドでは削除されます（Sanitizer.removeUnsafe() を呼び出したサニタイザーと同じ要素が削除されます）。

入力される HTML には、宣言型シャドウルート が含まれることがあります。 特定のシャドウホスト内に複数の宣言型シャドウルートが定義されている場合、最初の ShadowRoot だけが生成され、それ以降の宣言はそのシャドウルート内の <template> 要素として構文解析されます。

安全でない要素や属性を許可する必要が特にない限り、parseHTML() は Document.parseHTMLUnsafe() の代わりに使用すべきです。 解析対象の HTML に安全でない HTML エンティティが含まれる必要がない場合は、Document.parseHTML() を使用してください。

このメソッドは入力文字列から XSS に対して安全でないエンティティを常に無害化するため、信頼型 API による保護や検証は行われません。

仕様書

ブラウザーの互換性

関連情報

• Document.parseHTMLUnsafe()
• Element.setHTML() および Element.setHTMLUnsafe()
• ShadowRoot.setHTML() および ShadowRoot.setHTMLUnsafe()
• DOMParser.parseFromString(): HTML や XML を DOM ツリーに構文解析する
• HTML サニタイザー API