大网数据广告活动
Web 标准与前端开发

Document: parseHTMLUnsafe() static method

· 52CE 我爱测

[!WARNING] > This method parses its input as HTML, writing the result into the DOM. > APIs like this are known as injection sinks, and are potentially a vector for cross-site scripting (XSS) attacks, if the input originally came from an attacker. > > You can mitigate this risk by

DOM

[!WARNING] This method parses its input as HTML, writing the result into the DOM. APIs like this are known as injection sinks, and are potentially a vector for cross-site scripting (XSS) attacks, if the input originally came from an attacker.

You can mitigate this risk by always passing TrustedHTML objects instead of strings and enforcing trusted types. See Security considerations for more information.

[!NOTE] Document/parseHTML_static should almost always be used instead of this method — on browsers where it is supported — as it always removes XSS-unsafe HTML entities.

The parseHTMLUnsafe() static method of the Document object is used to parse HTML input, optionally filtering unwanted HTML elements and attributes, in order to create a new Document instance.

Syntax

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

Parameters

  • input
    • : A TrustedHTML instance or a string defining HTML to be parsed.
  • options
    • : An options object with the following optional parameters:
      • sanitizer
        • : A Sanitizer or SanitizerConfig object which defines what elements of the input will be allowed or removed. This can also be a string with the value "default", which applies a Sanitizer with the (XSS-safe) default sanitizer configuration. If not specified, no sanitizer is used.

          Note that if you're using the same configuration multiple times, it's expected to be more efficient to use a Sanitizer and modify it when you need to.

Return value

A Document.

Exceptions

  • TypeError
    • : This is thrown if:
      • html is passed a string when Trusted Types are enforced by a CSP and no default policy is defined.
      • options.sanitizer is passed a:
        • SanitizerConfig that isn't valid. For example, a configuration that includes both "allowed" and "removed" configuration settings.
        • string that does not have the value "default".
        • value that is not a Sanitizer, SanitizerConfig, or string.

Description

The parseHTMLUnsafe() static method can be used to create a new Document instance, optionally filter out unwanted elements and attributes. The resulting Document will have a content type of "text/html", a character set of UTF-8, and a URL of "about:blank".

The input HTML may include declarative shadow roots. If the string of HTML defines more than one declarative shadow root in a particular shadow host then only the first ShadowRoot is created — subsequent declarations are parsed as template elements within that shadow root.

parseHTMLUnsafe() doesn't perform any sanitization by default. If no sanitizer is passed as a parameter, all HTML entities in the input will be injected.

Security considerations

The suffix "Unsafe" in the method name indicates that it does not enforce removal of all XSS-unsafe HTML entities (unlike Document/parseHTML_static). While it can do so if used with an appropriate sanitizer, it doesn't have to use an effective sanitizer, or any sanitizer at all! The method is therefore a possible vector for cross-site scripting (XSS) attacks, where potentially unsafe strings provided by a user are injected into the DOM without first being sanitized.

You should mitigate this risk by always passing TrustedHTML objects instead of strings, and enforcing trusted types using the require-trusted-types-for CSP directive. This ensures that the input is passed through a transformation function, which has the chance to sanitize the input to remove potentially dangerous markup (such as script elements and event handler attributes), before it is injected.

Using TrustedHTML makes it possible to audit and check that sanitization code is effective in just a few places, rather than scattered across all your injection sinks. You should not need to pass a sanitizer to the method when using TrustedHTML.

If for any reason you can't use TrustedHTML (or even better, setHTML()) then the next safest option is to use setHTMLUnsafe() with the XSS-safe default sanitizer configuration.

Specifications

Browser compatibility

See also

  • Document.parseHTML_static
  • Element.setHTML() and Element.setHTMLUnsafe()
  • ShadowRoot.setHTML() and ShadowRoot.setHTMLUnsafe()
  • DOMParser.parseFromString() for parsing HTML or XML into a DOM tree
  • HTML Sanitizer API

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。