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 上檢視此頁面 • 報告此內容的問題