TrustedTypePolicyFactory.isHTML() — Methode · JavaScript-Referenz

Signatur

TrustedTypePolicyFactory.prototype.isHTML(value)

Beschreibung

Die Methode isHTML() gehört zur Schnittstelle TrustedTypePolicyFactory, die über das globale Objekt trustedTypes (in Fenstern und Workern) erreichbar ist. Sie gibt true zurück, wenn der übergebene Wert ein echtes TrustedHTML-Objekt ist, also eines, das über TrustedTypePolicy.createHTML() einer registrierten Richtlinie erzeugt wurde.

Gebraucht wird sie vor allem in Bibliotheken und Frameworks, die HTML sowohl als einfachen String als auch als bereits geprüftes TrustedHTML annehmen. Mit isHTML() lässt sich entscheiden, ob ein Wert direkt an eine Senke wie innerHTML weitergereicht werden darf oder erst noch durch eine Richtlinie laufen muss.

Die Prüfung erkennt nur echte Instanzen. Ein Objekt, das mit Object.create(TrustedHTML.prototype) oder als String mit gleichem Inhalt nachgebaut wurde, liefert false. Deshalb ist isHTML() verlässlicher als ein Test mit instanceof, weil sich die Prototypkette verändern lässt.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	any		Der zu prüfende Wert, meist ein Objekt, das ein `TrustedHTML` sein könnte, oder ein einfacher String.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn value ein gültiges TrustedHTML-Objekt ist, sonst false.

Beispiele

Richtlinie anlegen und Ergebnis prüfen

// Einfache Richtlinie, die spitze Klammern maskiert
const escapePolicy = trustedTypes.createPolicy('escape-policy', {
  createHTML: (input) => input.replace(/</g, '&lt;').replace(/>/g, '&gt;')
});

const trusted = escapePolicy.createHTML('<img src=x onerror=alert(1)>');

console.log(trustedTypes.isHTML(trusted));
console.log(trustedTypes.isHTML('<b>Hallo</b>'));

true false

Nachgebaute Objekte werden erkannt

const fake = Object.create(TrustedHTML.prototype);

console.log(fake instanceof TrustedHTML);   // lässt sich täuschen
console.log(trustedTypes.isHTML(fake));     // nicht täuschbar

true false

Bibliotheksfunktion, die String oder TrustedHTML annimmt

const sanitizerPolicy = trustedTypes.createPolicy('app-sanitizer', {
  // Nur zur Demonstration: in der Praxis z. B. DOMPurify verwenden
  createHTML: (input) => input.replace(/<script[\s\S]*?<\/script>/gi, '')
});

const render = (element, html) => {
  const safe = trustedTypes.isHTML(html)
    ? html                              // bereits geprüft
    : sanitizerPolicy.createHTML(html); // erst durch die Richtlinie schicken
  element.innerHTML = safe;
};

const box = document.createElement('div');
render(box, '<p>Text</p><script>alert(1)</script>');
console.log(box.innerHTML);

// Wichtig · Fallstricke

Browser-Unterstützung: Die Trusted Types API gibt es seit Langem in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen sie erst seit Kurzem. Vorher auf das globale Objekt prüfen, z. B. if (window.trustedTypes?.isHTML) { … }, oder ein Polyfill einbinden.
isHTML() prüft nur, ob ein Wert ein echtes TrustedHTML ist. Ob der Inhalt wirklich sicher ist, hängt allein davon ab, wie gut die createHTML-Funktion der Richtlinie bereinigt. Eine schwache Richtlinie erzeugt trotzdem „vertrauenswürdige“ Objekte.
Für die Typprüfung isHTML() statt instanceof TrustedHTML verwenden, denn instanceof lässt sich durch Veränderung der Prototypkette täuschen.
Die Methode funktioniert auch ohne aktive CSP-Direktive require-trusted-types-for 'script'. Erst mit dieser Direktive erzwingt der Browser aber Trusted Types an Senken wie innerHTML.
Verwandte Methoden: isScript() und isScriptURL() für die anderen Trusted-Typen.

Siehe auch

TrustedTypePolicyFactory.isScript() TrustedTypePolicyFactory.isScriptURL() TrustedTypePolicyFactory.createPolicy() TrustedTypePolicyFactory.getAttributeType() TrustedTypePolicyFactory.getPropertyType()