TrustedTypePolicyFactory.emptyHTML — Eigenschaft · JavaScript-Referenz

Signatur

TrustedTypePolicyFactory.emptyHTML

Beschreibung

Die Eigenschaft emptyHTML der Schnittstelle TrustedTypePolicyFactory (erreichbar über window.trustedTypes bzw. self.trustedTypes in Workern) gibt ein TrustedHTML-Objekt zurück, dessen Inhalt der leere String "" ist.

Gedacht ist sie für den häufigen Fall, dass man den Inhalt eines Elements leeren will, etwa mit element.innerHTML = .... Ist per Content-Security-Policy require-trusted-types-for 'script' aktiv, lehnt der Browser an solchen Senken (Sinks) normale Strings ab, also auch "". Ohne emptyHTML bräuchte man dafür extra eine Policy. Mit trustedTypes.emptyHTML klappt das ganz ohne Policy, auch wenn die CSP-Direktive trusted-types das Anlegen neuer Policies einschränkt.

Der Wert ist unveränderlich und besteht die Prüfung trustedTypes.isHTML(). Es gibt keine Parameter, denn es handelt sich um eine reine Getter-Eigenschaft.

Rückgabewert

Typ

TrustedHTML

Beschreibung

Ein TrustedHTML-Objekt, dessen toString() den leeren String "" liefert.

Beispiele

Element-Inhalt unter Trusted-Types-CSP leeren

// CSP: require-trusted-types-for 'script'
const container = document.querySelector('#ausgabe');

// container.innerHTML = '';  // würde einen TypeError auslösen
container.innerHTML = trustedTypes.emptyHTML;

console.log(container.childNodes.length);

Eigenschaften des Rückgabewerts prüfen

const leer = trustedTypes.emptyHTML;

console.log(trustedTypes.isHTML(leer));
console.log(leer.toString() === '');
console.log(leer instanceof TrustedHTML);
console.log(JSON.stringify(leer));

true true true ""

Fallback mit Feature-Erkennung

// Funktioniert mit und ohne Trusted-Types-Unterstützung
const leererHTMLWert = () =>
  window.trustedTypes?.emptyHTML ?? '';

const liste = document.querySelector('#trefferliste');
const leeren = () => {
  liste.innerHTML = leererHTMLWert();
};

document.querySelector('#reset')
  .addEventListener('click', leeren);

// Wichtig · Fallstricke

Browser-Kompatibilität: Trusted Types gibt es in Chromium-basierten Browsern seit Version 83. In Firefox und Safari ist die Unterstützung erst seit Kurzem vorhanden. Prüfe deshalb immer mit window.trustedTypes?.emptyHTML und nimm '' als Ausweichwert.
Jeder Zugriff liefert ein neues Objekt: Laut Spezifikation entsteht bei jedem Zugriff eine neue TrustedHTML-Instanz. Deshalb ist trustedTypes.emptyHTML === trustedTypes.emptyHTML nicht zuverlässig true. Vergleiche lieber mit toString() === ''.
Sicherheit: Ein leerer String kann kein Skript einschleusen. Deshalb ist emptyHTML ohne Policy erlaubt, und daran ändert auch eine restriktive trusted-types-Direktive nichts. Als Ersatz für das Bereinigen (Sanitizing) von Inhalten taugt es aber nicht.
Soll ein Element nur geleert werden, geht das auch ohne Trusted Types mit element.replaceChildren() oder element.textContent = ''. Das ist oft einfacher.
Für leere Skript-Werte gibt es als Gegenstück trustedTypes.emptyScript.

Siehe auch

TrustedTypePolicy.name TrustedTypePolicyFactory.emptyScript TrustedTypePolicyFactory.defaultPolicy CryptoKey.algorithm RemotePlayback.state