SanitizerConfig

Das SanitizerConfig Dictionary der HTML Sanitizer API legt fest, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden sollen, wenn HTML-Strings in ein Element oder ShadowRoot eingefügt werden, oder beim Parsen eines HTML-Strings in ein Document.

Beachten Sie, dass normalerweise Sanitizer Instanzen anstatt von SanitizerConfig Objekten verwendet werden, da sie effizienter zu teilen und zu modifizieren sind.

Instanz-Eigenschaften

elements

Ein Array, das die Elemente angibt, die beim Bereinigen von HTML erlaubt sind, und optional auch deren erlaubte oder entfernte Attribute.

Jedes Element kann entweder durch seinen Namen (ein String) oder als Objekt mit den folgenden Eigenschaften angegeben werden:

name

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

namespace Optional

Ein String, der den Namensraum des Elements enthält. Der Standard-Namensraum 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 entweder durch seinen Namen (ein String) oder als Objekt mit den folgenden Eigenschaften angegeben werden:

name

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

namespace Optional

Ein String, der den Namensraum 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 sollen.

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

name

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

namespace Optional

Ein String, der den Namensraum des Attributs enthält, welcher standardmäßig null ist.

removeElements

Ein Array, das die Elemente angibt, die beim Bereinigen von HTML entfernt werden sollen.

Jedes Element kann entweder durch seinen Namen (ein String) oder als Objekt mit den folgenden Eigenschaften angegeben werden:

name

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

namespace Optional

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

replaceWithChildrenElements

Ein Array, das die Elemente angibt, die durch ihren Inhalt ersetzt werden sollen, wenn HTML bereinigt wird. Dies wird hauptsächlich verwendet, um Stile von Text zu entfernen (zum Beispiel, um <b>ein Text</b> in ein Text zu ändern).

Jedes Element kann entweder durch seinen Namen (ein String) oder als Objekt mit den folgenden Eigenschaften angegeben werden:

name

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

namespace Optional

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

attributes

Ein Array, das die Attribute angibt, die beim Bereinigen von HTML erlaubt sind.

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

name

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

namespace Optional

Ein String, der den Namensraum des Attributs enthält, welcher standardmäßig null ist.

removeAttributes

Ein Array, das die Attribute angibt, die beim Bereinigen von HTML von Elementen entfernt werden sollen.

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

name

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

namespace Optional

Ein String, der den Namensraum des Attributs enthält, welcher standardmäßig null ist.

comments

true, wenn Kommentare erlaubt sind, und false, wenn sie entfernt werden sollen.

dataAttributes

true, wenn alle data-* Attribute erlaubt sind (in diesem Fall dürfen data-* Attribute nicht im attributes Array aufgeführt sein). Wenn false, müssen alle zu erlaubenden data-* Attribute im attributes Array aufgeführt werden.

Beschreibung

Ein SanitizerConfig gibt an, welche Elemente, Attribute und Kommentare erlaubt oder entfernt werden sollen, wenn HTML-Strings in ein Element oder ShadowRoot eingefügt werden oder wenn ein HTML-String in ein Document geparst wird.

Eine Instanz dieses Typs kann dem Sanitizer() Konstruktor übergeben werden, um einen Sanitizer zu konfigurieren, und wird von Sanitizer.get() zurückgegeben. Es kann auch als option.sanitizer Parameter beim Aufrufen der Sanitization-Methoden übergeben werden:

• setHTML() oder setHTMLUnsafe() auf Element.
• setHTML() oder setHTMLUnsafe() auf ShadowRoot.
• Document.parseHTML() oder Document.parseHTMLUnsafe() statische Methoden.

Gültige Konfiguration

Die Struktur des Konfigurationsobjekts erlaubt die Deklaration von Filteroptionen, die widersprüchlich oder redundant sind, wie zum Beispiel das Angeben eines Elements sowohl in der Erlauben- als auch in der Entfernen-Liste oder das mehrfache Auflisten eines Attributs in einer Liste. Um jegliche Mehrdeutigkeit zu vermeiden, erfordern Methoden, die eine SanitizerConfig Instanz verwenden, dass ein gültiges Konfigurationsobjekt übergeben wird und werfen einen TypeError, wenn eine ungültige Konfiguration verwendet wird.

In einer gültigen Sanitizer-Konfiguration:

• Es darf entweder das elements oder das removeElements Array definiert sein, aber nicht beide.

  Hinweis: Es ist unmöglich, pro Element-Attribute zu definieren, wenn das removeElements Array definiert ist, da diese zu Elementen im elements Array hinzugefügt werden.

• Es darf entweder das globale attributes oder removeAttributes Array definiert sein, aber nicht beide.

• Das replaceWithChildrenElements Array, falls definiert, darf keine Elemente gemeinsam mit elements oder removeElements haben.

• Kein Array darf doppelte Elemente oder Attribute enthalten.

• Wenn das globale attributes Array definiert ist:

  • Ein Element kann beliebige oder keine der attributes und removeAttributes definieren.
  • Die attributes eines Elements dürfen keine gemeinsamen Werte mit dem globalen attributes Array haben.
  • Das removeAttributes Array eines Elements darf nur Werte enthalten, die auch im globalen attributes Array vorhanden sind.
  • Wenn dataAttributes true ist, dürfen die globalen und elementbasierte Attribut-Arrays keine data-* Attribute enthalten (da diese automatisch erlaubt werden).

• Wenn das globale removeAttributes Array definiert ist:

  • Ein Element kann entweder attributes oder removeAttributes angeben, aber nicht beide.
  • Das attributes oder removeAttributes Array eines Elements, je nach dem, welches (falls überhaupt) definiert ist, darf keine gemeinsamen Werte mit dem globalen removeAttributes Array haben.
  • Der dataAttributes Boolean darf nicht definiert sein.

Das leere Objekt {} ist eine gültige Konfiguration.

Erlauben- und Entfernen-Konfigurationen

Eine der Hauptimplikationen des vorherigen Abschnitts ist, dass eine gültige Konfiguration entweder elements oder removeElements Arrays (aber nicht beide) und entweder attributes oder removeAttributes Arrays (aber nicht beide) festlegen kann.

Eine Konfiguration, die die Arrays elements und/oder attributes hat, wird als Erlauben-Konfiguration bezeichnet, da sie das Bereinigungsverhalten in Bezug auf die Werte definiert, die im Ausgang enthalten sein dürfen. Eine Entfernen-Konfiguration ist eine, die entweder removeElements und/oder removeAttributes hat und das Verhalten in Bezug auf die Werte definiert, die aus dem Ausgang entfernt werden.

Beispiele

Erstellung einer "Erlauben"-Konfiguration

Dieses Beispiel zeigt, wie Sie eine "Erlauben" Sanitizer-Konfiguration erstellen können, die bestimmte Elemente und Attribute erlaubt, <b> Elemente durch deren Kinder ersetzt, es erlaubt, Kommentare im Ausgang einzuschließen, und erfordert, dass data-* Attribute explizit im attributes Array aufgelistet werden, um einbezogen zu werden. Das Konfigurationsobjekt wird dem Sanitizer() Konstruktor übergeben.

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

Erstellung einer "Entfernen"-Konfiguration

Dieses Beispiel zeigt, wie Sie eine "Entfernen" Sanitizer-Konfiguration erstellen können, die sowohl Elemente als auch Attribute entfernt.

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

Erlauben von Elementen und Entfernen von Attributen Konfiguration

Dieses Beispiel zeigt, wie Sie eine "hybride" Sanitizer-Konfiguration erstellen können, die einige Elemente erlaubt und bestimmte Attribute entfernt. Sie könnten auf ähnliche Weise eine Konfiguration festlegen, die Elemente entfernt und Attribute erlaubt.

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

Beachten Sie, dass das gleichzeitige Vorhandensein von Erlauben- und Entfernen-Arrays für Elemente oder das gleichzeitige Vorhandensein von Erlauben- und Entfernen-Arrays für Attribute keine gültige Konfiguration ist und zu einem TypeError führen würde.

Ungültige Konfigurationen

Dieser Abschnitt zeigt eine Reihe ungültiger Konfigurationen. Diese werden einen TypeError auslösen.

Ungültig, da sowohl elements als auch removeElements definiert sind:

const sanitizer1 = new Sanitizer({
 elements: ["span", "script"],
 removeElements: ["div", "b"],
});

Ungültig, da <span> sowohl in elements als auch in replaceWithChildrenElements enthalten ist:

const sanitizer2 = new Sanitizer({
 elements: ["span", "div"],
 replaceWithChildrenElements: ["span"],
});

Ungültig, da das redundante Attribut "data-test" definiert ist, wenn dataAttributes true ist:

const sanitizer3 = new Sanitizer({
 attributes: ["lang", "id", "data-test"],
 dataAttributes: true,
});

Ungültig, da sowohl removeAttributes als auch dataAttributes definiert sind:

const sanitizer4 = new Sanitizer({
 removeAttributes: ["lang", "id"],
 dataAttributes: true,
});

Spezifikationen

Browser-Kompatibilität

api.Sanitizer.get

api.Sanitizer.Sanitizer