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

Sanitizer

· 52CE 我爱测

The **`Sanitizer`** interface of the HTML Sanitizer API defines a configuration object that specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into an Element or ShadowRoot, or when parsing an HTML string into a Docume

HTML Sanitizer API

The Sanitizer interface of the HTML Sanitizer API defines a configuration object that specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into an Element or ShadowRoot, or when parsing an HTML string into a Document.

Constructors

  • Sanitizer.Sanitizer
    • : Creates and returns a Sanitizer object, optionally with custom sanitization behavior defined in a SanitizerConfig.

Instance methods

  • Sanitizer.allowElement()
    • : Sets an element as allowed by the sanitizer, optionally with an array of attributes that are allowed or disallowed.
  • Sanitizer.get()
    • : Returns the current Sanitizer configuration as a SanitizerConfig dictionary instance.
  • Sanitizer.removeElement()
    • : Sets an element to be removed by the sanitizer.
  • Sanitizer.removeUnsafe()
    • : Updates the sanitizer configuration so that it will remove any XSS-unsafe HTML.
  • Sanitizer.replaceElementWithChildren()
    • : Sets an element to be replaced by its child HTML elements.
  • Sanitizer.allowAttribute()
    • : Sets an attribute as allowed on any element.
  • Sanitizer.removeAttribute()
    • : Sets an attribute to be removed from any element.
  • Sanitizer.setComments()
    • : Sets whether comments will be allowed or removed by the sanitizer.
  • Sanitizer.setDataAttributes()
    • : Sets whether data attributes on elements will be allowed or removed by the sanitizer.

Description

A Sanitizer is a reusable configuration object that specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into an Element or ShadowRoot, or when parsing an HTML string into a Document. It can be used with the following sanitization methods:

A Sanitizer instance can be constructed from a SanitizerConfig, and is effectively a wrapper around that object. A Sanitizer and a SanitizerConfig can be used with the same methods, but 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. If no SanitizerConfig is passed to the constructor, the sanitizer is created with the default sanitizer configuration, which removes XSS-unsafe elements and attributes, along with other elements and attributes that can potentially be used in other attacks, such as clickjacking and spoofing.

Note that any Sanitizer can be made XSS-safe by calling Sanitizer.removeUnsafe(), but other potentially dangerous elements and attributes — which are removed by the default configuration — may still be present.

Using Sanitizer with the sanitization methods

The default Sanitizer configuration is automatically used if no Sanitizer is passed to Element.setHTML or the other safe sanitization methods. This is a reasonable default as it restricts the attack surface while still allowing the majority of use cases.

If a custom sanitizer is passed to these methods, any XSS-unsafe elements and attributes allowed by the sanitizer would also be removed. Note that although this removes the same elements as Sanitizer.removeUnsafe(), the passed Sanitizer is not actually changed by the operation: it would be "unsafe" if used in an unsafe method.

The unsafe sanitization methods perform no sanitization by default. However, as noted, you can call Sanitizer.removeUnsafe() to remove any XSS-unsafe elements (if you want to use the default configuration, you should use the safe methods).

Examples

For more examples see the HTML Sanitizer API and the individual methods. Below we show a few examples of how you might create different sanitizer configurations.

Creating a default sanitizer

The default sanitizer is constructed as shown below.

const sanitizer = new Sanitizer();

The XSS-safe sanitization methods create the same sanitizer automatically if no options are passed.

Creating an empty sanitizer

To create an empty sanitizer, pass an empty object to the constructor. The resulting sanitizer configuration is a remove configuration with empty arrays.

const sanitizer = new Sanitizer({});
console.log(sanitizer.get());
/*
{
  "comments": true,
  "removeAttributes": [],
  "removeElements": []
}
*/

Creating an "allow" sanitizer

This example shows how you might create an "allow sanitizer": a sanitizer that allows only a subset of attributes and elements.

The code first uses the Sanitizer.Sanitizer constructor to create a Sanitizer, specifying a SanitizerConfig that allows the element <div>, <p> and <script>.

The example then uses allowElement() to further allow <span> elements, allowAttribute() to allow the id attribute on any element, and replaceElementWithChildren() method to set that any <b> elements should be replaced by their inner content (this is a kind of "allow" in that you are explicitly specifying some entities to keep). Lastly we specify that comments should be retained.

const sanitizer = new Sanitizer({ elements: ["div", "p", "script"] });
sanitizer.allowElement("span");
sanitizer.allowAttribute("id");
sanitizer.replaceElementWithChildren("b");
sanitizer.setComments(true);

Creating a "remove" sanitizer

This example shows how you might create a "remove sanitizer", specifying items to remove from the input.

The code first uses the Sanitizer.Sanitizer constructor to create a Sanitizer, specifying a SanitizerConfig that removes the element <span> and <script>. We then use removeElement() to add <h6> to the array of elements to be removed, and removeAttribute() to remove lang from the attributes list. We also remove comments.

const sanitizer = new Sanitizer({ removeElements: ["span", "script"] });
sanitizer.removeElement("h6");
sanitizer.removeAttribute("lang");
sanitizer.setComments(false);

Specifications

Browser compatibility

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

资料来源与适用范围

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

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

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