SanitizerConfig

Instanzeigenschaften

elements

Ein Array, das die Elemente angibt, die beim Bereinigen von HTML erlaubt sind. Optional können auch deren erlaubte oder entfernte Attribute angegeben werden.

Jedes Element kann durch den 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 auf diesem (erlaubten) Element beim Bereinigen von HTML erlaubt sind.

Jedes Attribut kann durch den 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, der standardmäßig null ist.

removeAttributes Optional

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

Jedes Attribut kann durch den 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, der standardmäßig null ist.

removeElements

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

Jedes Element kann durch den 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 mit ihrem Inhalt ersetzt werden sollen, wenn HTML bereinigt wird. Dies wird hauptsächlich verwendet, um Stile von Text zu entfernen (zum Beispiel könnten Sie dies verwenden, um <b>einige Texte</b> in einige Texte zu ändern).

Jedes Element kann durch den 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 durch den 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, der standardmäßig null ist.

removeAttributes

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

Jedes Attribut kann durch den 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, der 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 müssen data-*-Attribute nicht in der attributes-Liste aufgeführt werden). Wenn false, müssen alle erlaubten data-*-Attribute in der attributes-Liste aufgeführt werden.

Beschreibung

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

Eine Instanz dieser Art kann beim Sanitizer()-Konstruktor übergeben werden, um einen Sanitizer zu konfigurieren und wird von Sanitizer.get() zurückgegeben. Es kann auch als option.sanitizer-Parameter übergeben werden, wenn die Bereinigungsmethoden aufgerufen 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 ermöglicht die Deklaration von Filteroptionen, die widersprüchlich oder redundant sind, wie das Angeben eines Elements in sowohl Erlauben- als auch Entfernungslisten oder das mehrfache Auflisten eines Attributs in einer Liste. Um jede Mehrdeutigkeit zu vermeiden, erfordern Methoden, die eine SanitizerConfig-Instanz akzeptieren, dass ein gültiges Konfigurationsobjekt übergeben wird, und werfen einen TypeError, wenn eine ungültige Konfiguration verwendet wird.

In einer gültigen Sanitizer-Konfiguration:

• Entweder das elements- oder das removeElements-Array kann definiert sein, aber nicht beide.

  Hinweis: Es ist unmöglich, für Elemente spezifische Attribute zu definieren, wenn das removeElements-Array definiert ist, da diese den Elementen im elements-Array hinzugefügt werden.

• Entweder das globale attributes- oder das removeAttributes-Array kann definiert sein, aber nicht beide.

• Das replaceWithChildrenElements-Array, wenn definiert, darf keine gemeinsamen Elemente mit elements oder removeElements haben.

• Kein Array darf doppelte Elemente oder Attribute enthalten.

• Wenn das globale attributes-Array definiert ist:

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

• Wenn das globale removeAttributes-Array definiert ist:

  • Ein Element kann entweder attributes oder removeAttributes angeben, aber nicht beides.
  • Ein Element's attributes- oder removeAttributes-Array, je nachdem welches (wenn überhaupt) definiert ist, darf keine gemeinsamen Werte mit dem globalen removeAttributes-Array haben.
  • Die dataAttributes-Boolescherwert 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) spezifizieren kann.

Eine Konfiguration, die über die elements- und/oder attributes-Arrays verfügt, wird als Erlauben-Konfiguration bezeichnet, da sie das Bereinigungsverhalten in Bezug auf die Werte definiert, die im Ausgang erlaubt sind. Eine Entfernen-Konfiguration ist eine, die entweder removeElements und/oder removeAttributes enthält und das Verhalten in Bezug auf die Werte definiert, die aus dem Ausgang entfernt werden.

Beispiele

Erstellen einer "erlauben" Konfiguration

Dieses Beispiel zeigt, wie Sie eine "erlauben" Sanitizer-Konfiguration erstellen könnten, die spezifische Elemente und Attribute erlaubt, <b>-Elemente durch ihre Kinder ersetzt, erlaubt, dass Kommentare in der Ausgabe enthalten sind, und erfordert, dass data-*-Attribute explizit in der attributes-Liste aufgeführt werden, um enthalten zu sein. Das Konfigurationsobjekt wird dem Sanitizer()-Konstruktor übergeben.

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

Erstellen einer "entfernen" Konfiguration

Dieses Beispiel zeigt, wie Sie eine "entfernen" Sanitizer-Konfiguration erstellen könnten, 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 "hybrid" Sanitizer-Konfiguration erstellen könnten, die einige Elemente erlaubt und bestimmte Attribute entfernt. Sie könnten ähnlich eine Konfiguration spezifizieren, 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 sowohl Erlauben- als auch 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 von ungültigen Konfigurationen. Diese werden einen TypeError werfen.

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

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

Ungültig, weil <span> sowohl in elements als auch in removeElements enthalten ist.

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

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

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

Ungültig, weil es removeAttributes und dataAttributes definiert hat.

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

Spezifikationen

Browser-Kompatibilität

api.Sanitizer.get

api.Sanitizer.Sanitizer