Document：parseHTMLUnsafe() 靜態方法

語法

Document.parseHTMLUnsafe(input)
Document.parseHTMLUnsafe(input, options)

引數

input

一個 TrustedHTML 或定義要解析的 HTML 的字串例項。

options 可選

一個包含以下可選引數的 options 物件

sanitizer 可選

一個 Sanitizer 或 SanitizerConfig 物件，它定義了輸入中允許或刪除的元素。這也可以是一個值為 "default" 的字串，它會應用一個帶有預設（XSS 安全）配置的 Sanitizer。如果未指定，則不使用 Sanitizer。

請注意，如果配置要重複使用，通常預期 Sanitizer 會比 SanitizerConfig 更高效。

返回值

一個 Document。

異常

TypeError

如果出現以下情況，將丟擲此錯誤

• 當 Trusted Types 由 CSP 強制執行 且未定義預設策略時，html 將作為字串傳遞。
• options.sanitizer 傳遞了一個
  • 不是 Sanitizer、SanitizerConfig 或字串的值。
  • 非規範化的 SanitizerConfig（包含“允許”和“移除”配置設定）。
  • 不具有值 "default" 的字串。

描述

parseHTMLUnsafe() 靜態方法可用於建立新的 Document 例項，可選地過濾掉不需要的元素和屬性。生成的 Document 將具有“text/html”的內容型別、“UTF-8”的字元集和“about:blank”的 URL。

輸入 HTML 可能包含宣告式 Shadow Root。如果 HTML 字串在特定 Shadow Host 中定義了多個宣告式 Shadow Root，則只建立第一個 ShadowRoot — 後續宣告將解析為該 Shadow Root 中的 <template> 元素。

parseHTMLUnsafe() 預設不執行任何清理。如果沒有將 Sanitizer 作為引數傳遞，輸入中的所有 HTML 實體都將被注入。

安全注意事項

方法名稱中的“Unsafe”字尾表示它不強制刪除所有不安全的 XSS HTML 實體（與 Document.parseHTML() 不同）。雖然如果與適當的 Sanitizer 一起使用，它也可以這樣做，但它不一定使用有效的 Sanitizer，甚至不使用任何 Sanitizer！因此，該方法是跨站指令碼 (XSS) 攻擊的可能載體，其中使用者提供的潛在不安全字串在未經清理的情況下被注入到 DOM 中。

您應該透過始終傳遞 TrustedHTML 物件而不是字串，並使用 require-trusted-types-for CSP 指令強制執行受信任型別來減輕這種風險。這確保輸入透過轉換函式，該函式有機會清理輸入以刪除潛在危險的標記（例如 <script> 元素和事件處理程式屬性），然後再注入。

使用 TrustedHTML 可以僅在少數地方審計和檢查清理程式碼是否有效，而不是分散在所有注入點中。使用 TrustedHTML 時，您不需要將 Sanitizer 傳遞給該方法。

如果由於任何原因您無法使用 TrustedHTML（或者更好的是 setHTML()），那麼下一個最安全的選擇是使用帶有 XSS 安全預設 Sanitizer 的 setHTMLUnsafe()。

規範

瀏覽器相容性

另見

• Document.parseHTML()
• Element.setHTML() 和 Element.setHTMLUnsafe()
• ShadowRoot.setHTML() 和 ShadowRoot.setHTMLUnsafe()
• DOMParser.parseFromString() 用於將 HTML 或 XML 解析為 DOM 樹
• HTML Sanitizer API