SanitizerConfig

实验性： 这是一项实验性技术
在生产中使用此技术之前，请仔细检查浏览器兼容性表格。

HTML Sanitizer API 中的 SanitizerConfig 字典表示一个 sanitizer 配置对象。此配置指定了在将 HTML 字符串插入 Element 或 ShadowRoot 时，或在将 HTML 字符串解析为 Document 时，允许或应移除哪些元素、属性和注释。

此类型的一个实例可以传递给 Sanitizer() 构造函数来配置一个 Sanitizer，并且是 Sanitizer.get() 返回的结果。当调用 sanitization methods 时，它也可以作为 option.sanitizer 参数传递。

在 Element 上调用 setHTML() 或 setHTMLUnsafe()。
在 ShadowRoot 上调用 setHTML() 或 setHTMLUnsafe()。
静态方法 Document.parseHTML() 或 Document.parseHTMLUnsafe()。

请注意，在上述方法中，通常会传递一个 Sanitizer 实例作为选项，而不是 SanitizerConfig，特别是因为 sanitizer 实例更易于共享和修改，效率更高。

实例属性

elements

一个数组，指示在清理 HTML 时允许的元素，还可以选择性地指定其允许或移除的属性。

每个元素可以按名称（字符串）指定，或者作为一个具有以下属性的对象指定：

name

一个包含元素名称的字符串。

namespace 可选

一个包含元素命名空间的字符串。默认命名空间为 "http://www.w3.org/1999/xhtml"。

attributes 可选

一个数组，指示在清理 HTML 时允许在此（已允许的）元素上使用的属性。

每个属性可以按名称（字符串）指定，或者作为一个具有以下属性的对象指定：

name: 包含属性名称的字符串。
namespace 可选: 一个包含属性命名空间的字符串，默认为 null。

removeAttributes 可选

一个数组，指示在清理 HTML 时要从此（已允许的）元素上移除的属性。

每个属性可以按名称（字符串）指定，或者作为一个具有以下属性的对象指定：

name: 包含属性名称的字符串。
namespace 可选: 一个包含属性命名空间的字符串，默认为 null。

removeElements

一个数组，指示在清理 HTML 时要移除的元素。

每个元素可以按名称（字符串）指定，或者作为一个具有以下属性的对象指定：

name: 一个包含元素名称的字符串。
namespace 可选: 一个包含元素命名空间的字符串。默认命名空间为 "http://www.w3.org/1999/xhtml"。

replaceWithChildrenElements

一个数组，指示在清理 HTML 时要用其子元素替换的元素。这主要用于去除文本中的样式（例如，您可以使用此方法将 <b>some text</b> 更改为 some text）。

每个元素可以按名称（字符串）指定，或者作为一个具有以下属性的对象指定：

name: 一个包含元素名称的字符串。
namespace 可选: 一个包含元素命名空间的字符串。默认命名空间为 "http://www.w3.org/1999/xhtml"。

attributes

一个数组，指示在清理 HTML 时允许的属性。

每个属性可以按名称（字符串）指定，或者作为一个具有以下属性的对象指定：

name: 包含属性名称的字符串。
namespace 可选: 一个包含属性命名空间的字符串，默认为 null。

removeAttributes

一个数组，指示在清理 HTML 时要从元素中移除的属性。

每个属性可以按名称（字符串）指定，或者作为一个具有以下属性的对象指定：

name: 包含属性名称的字符串。
namespace 可选: 一个包含属性命名空间的字符串，默认为 null。

comments

如果允许注释，则为 true；如果应移除注释，则为 false。

dataAttributes

如果允许 data 属性，则为 true；如果应移除 data 属性，则为 false。

示例

创建一个“允许”配置

本示例展示了如何创建一个“允许” sanitizer 配置，并将其传递给 Sanitizer() 构造函数。

const sanitizer = new Sanitizer({
  elements: ["div", "p", "script"],
  attributes: ["id"],
  replaceWithChildrenElements: ["b"],
  comments: true,
  dataAttributes: false,
});

请注意，您不能在同一个配置中同时指定允许列表和移除列表，否则在将配置传递给构造函数或 sanitization 方法时会引发异常。

创建一个“移除”配置

本示例展示了如何创建一个“移除” sanitizer 配置，并将其传递给 Sanitizer() 构造函数。

const sanitizer = new Sanitizer({
  removeElements: ["span", "script"],
  removeAttributes: ["lang", "id"],
  comments: false,
});

请注意，您不能在同一个配置中同时指定允许列表和移除列表，否则在将配置传递给构造函数或 sanitization 方法时会引发异常。

规范

规范
HTML Sanitizer API # dom-sanitizer-get
HTML Sanitizer API # dom-sanitizer-sanitizer

浏览器兼容性

api.Sanitizer.get

api.Sanitizer.Sanitizer

帮助改进 MDN

了解如何贡献

此页面最后修改于 2025年7月21日，作者是 MDN 贡献者。

在 GitHub 上查看此页面 • 报告此内容的问题