Sanitizer: allowElement() 方法

可用性有限

此特性不是基线特性，因为它在一些最广泛使用的浏览器中不起作用。

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

Sanitizer 接口的 allowElement() 方法用于在 sanitizer 使用时，指定在输出中允许的元素。可以通过允许或禁止该类型元素上的属性列表来指定元素。

指定的元素会被添加到此 sanitizer 配置的 elements 列表中。如果该元素已存在于列表中，则会先移除现有条目，然后将新定义追加到列表末尾。请注意，如果您需要同时为每个元素添加属性和移除属性列表，它们必须在对该方法的一次调用中完成（因为如果分两次调用，第二次调用将替换第一次调用添加的元素定义）。

如果存在，指定的元素将从 sanitizer 配置的 removeElements 或 replaceWithChildrenElements 列表中移除。

语法

allowElement(element)

参数

element

一个字符串，表示允许的元素的名称，或者一个具有以下属性的对象

name

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

namespace 可选

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

attributes 可选

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

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

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

removeAttributes 可选

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

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

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

返回值

无 (undefined)。

示例

如何允许元素

此示例展示了如何使用 allowElement() 将元素添加到 sanitizer 的 elements 配置（允许的元素列表）中。

<pre id="log"></pre>

#log {
  height: 400px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.textContent = text;
}

JavaScript

代码首先创建一个新的 Sanitizer 对象，该对象最初允许 <div> 和 <script> 元素。然后调用 allowElement() 添加一个作为字符串参数指定的 <p> 元素，然后再调用一次添加一个作为对象指定的 <span> 元素。之后，我们获取并记录配置。

if ("Sanitizer" in window) {

// Create sanitizer using SanitizerConfig
const sanitizer = new Sanitizer({
  elements: ["div", "script"],
});

// Allow <p> specifying an string
sanitizer.allowElement("p");

// Allow <span> specifying an object
sanitizer.allowElement({ name: "span" });

let sanitizerConfig = sanitizer.get();
log(JSON.stringify(sanitizerConfig, null, 2));

} else {
  log("The HTML Sanitizer API is NOT supported in this browser.");
}

结果

最终配置如下所示。这包括原始元素（<div> 和 <script>）以及通过 allowElement() 添加的两个元素（<p> 和 <span>）。

允许已允许或已移除的元素

此示例展示了使用 allowElement() 添加已允许的元素或已配置为“待移除”的元素的时所产生的影响。

<pre id="log"></pre>

#log {
  height: 400px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.textContent = text;
}

JavaScript

代码首先创建一个新的 Sanitizer 对象，该对象最初允许 <div> 元素（移除除 id 之外的属性），并且还将 <span> 元素替换为其子元素。

然后调用 allowElement()，首先添加一个移除 style 属性的 <div> 元素。由于 <div> 元素已允许，因此它会从 elements 配置中移除，并将 <div> 元素定义追加到末尾。

然后将 <span> 元素添加到允许列表中，这将从 replaceWithChildrenElements 配置列表中移除它。

if ("Sanitizer" in window) {

// Create sanitizer using SanitizerConfig
const sanitizer = new Sanitizer({
  elements: [{ name: "div", attributes: [{ name: "id" }] }],
  replaceWithChildrenElements: ["span"],
});

// Allow <div> elements.
// Allow id elements but strip their style attributes
sanitizer.allowElement({
  name: "div",
  removeAttributes: ["style"],
});

// Allow <span> elements
sanitizer.allowElement("span");

let sanitizerConfig = sanitizer.get();
log(JSON.stringify(sanitizerConfig, null, 2));

} else {
  log("The HTML Sanitizer API is NOT supported in this browser.");
}

结果

最终配置会显示在日志中，如下所示。从日志中可以看到，原始的 <div> 元素过滤器已被移除，新的定义已追加到 elements 列表中。将 <span> 元素添加到 elements 列表已将其从 replaceWithChildrenElements 列表中移除。

规范

规范
HTML Sanitizer API # dom-sanitizer-allowelement

浏览器兼容性

帮助改进 MDN

了解如何贡献

此页面最后修改于 2025 年 6 月 26 日，由 MDN 贡献者修改。

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