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