Sanitizer: allowElement() Methode

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die allowElement() Methode der Sanitizer Schnittstelle legt fest, dass das angegebene Element im Ergebnis erlaubt ist, wenn der Sanitizer verwendet wird. Das Element kann mit Listen von Attributen spezifiziert werden, die bei Elementen dieses Typs erlaubt oder nicht erlaubt sind.

Das angegebene Element wird zur elements Liste in der Konfiguration dieses Sanitizers hinzugefügt. Wenn das Element bereits in der Liste vorhanden ist, wird der vorhandene Eintrag zuerst entfernt und die neue Definition am Ende der Liste angehängt. Beachten Sie, dass, wenn Sie sowohl für das Hinzufügen als auch das Entfernen von Attributen pro Element arbeiten möchten, diese in einem einzigen Aufruf dieser Methode hinzugefügt werden müssen (da bei zwei separaten Aufrufen der zweite Aufruf die im ersten hinzugefügte Elementdefinition ersetzen würde).

Das angegebene Element wird aus der Sanitizer-Konfiguration von den removeElements oder replaceWithChildrenElements Listen entfernt, falls vorhanden.

Syntax

allowElement(element)

Parameter

element

Ein String, der den Namen des erlaubten Elements angibt, oder ein Objekt mit den folgenden Eigenschaften:

name

Ein String, der den Namen des Elements enthält.

namespace Optional

Ein String, der den Namespace des Elements enthält. Der Standard-Namespace ist "http://www.w3.org/1999/xhtml".

attributes Optional

Ein Array, das die Attribute angibt, die bei diesem (erlaubten) Element beim Bereinigen von HTML erlaubt sind.

Jedes Attribut kann durch einen Namen (einen String) angegeben werden, oder als ein Objekt mit den folgenden Eigenschaften:

name: Ein String, der den Namen des Attributs enthält.
namespace Optional: Ein String, der den Namespace des Attributs enthält, welcher standardmäßig null ist.

removeAttributes Optional

Ein Array, das die Attribute angibt, die bei diesem (erlaubten) Element beim Bereinigen von HTML entfernt werden.

Jedes Attribut kann durch einen Namen (einen String) angegeben werden, oder als ein Objekt mit den folgenden Eigenschaften:

name: Ein String, der den Namen des Attributs enthält.
namespace Optional: Ein String, der den Namespace des Attributs enthält, welcher standardmäßig null ist.

Rückgabewert

Keiner (undefined).

Beispiele

Anleitung zum Erlauben von Elementen

Dieses Beispiel zeigt, wie allowElement() verwendet wird, um ein Element zur elements Konfiguration des Sanitizers (die Liste der erlaubten Elemente) hinzuzufügen.

<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

Der Code erstellt zunächst ein neues Sanitizer Objekt, das anfangs <div> und <script> Elemente erlaubt. Dann wird allowElement() aufgerufen, um ein <p> Element hinzuzufügen, das als String-Parameter angegeben ist, und nochmals, um ein <span> Element hinzuzufügen, das als Objekt angegeben ist. Wir erhalten dann die Konfiguration und protokollieren sie.

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.");
}

Ergebnisse

Die endgültige Konfiguration wird unten protokolliert. Dies umfasst die ursprünglichen Elemente (<div> und <script>) und die beiden mit allowElement() hinzugefügten (<p> und <span>).

Erlauben von bereits erlaubten oder entfernten Elementen

Dieses Beispiel zeigt die Wirkung von allowElement(), wenn Elemente hinzugefügt werden, die bereits erlaubt sind, oder die in der Konfiguration als "zu entfernen" festgelegt sind.

<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

Der Code erstellt zunächst ein neues Sanitizer Objekt, das anfänglich <div> Elemente erlaubt (außer id Attributen andere Attribute entfernend) und auch <span> Elemente mit allen Kinderelementen ersetzt.

Dann wird allowElement() aufgerufen, um zuerst ein <div> Element mit Entfernung von style Attributen hinzuzufügen. Da das <div> Element bereits erlaubt ist, wird es aus der elements Konfiguration entfernt und die <div> Elementdefinition wird angehängt.

Ein <span> Element wird dann zur Erlauben-Liste hinzugefügt, was es aus der replaceWithChildrenElements Konfigurationsliste entfernt.

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.");
}

Ergebnisse

Die endgültige Konfiguration wird protokolliert und unten angezeigt. Aus dem Log können wir sehen, dass der ursprüngliche Filter für das <div> Element entfernt wurde und die neue Definition der elements-Liste hinzugefügt wurde. Das Hinzufügen des <span> Elements zur elements-Liste hat es von der replaceWithChildrenElements-Liste entfernt.

Spezifikationen

Specification
HTML Sanitizer API # dom-sanitizer-allowelement