TrustedHTML.toString() — Methode · JavaScript-Referenz

Signatur

TrustedHTML.prototype.toString()

Beschreibung

Die Methode toString() eines TrustedHTML-Objekts liefert den HTML-String, den die zugehörige TrustedTypePolicy beim Aufruf von createHTML() erzeugt hat. Das Objekt selbst dient als Typ-Nachweis: Es zeigt, dass der Inhalt durch eine Richtlinie gelaufen ist und in eine Einfügestelle (Sink) wie Element.innerHTML, outerHTML, insertAdjacentHTML() oder document.write() gelangen darf.

In der Praxis ruft man toString() selten direkt auf. Die Einfügestellen nehmen das TrustedHTML-Objekt direkt an, und bei String-Umwandlungen (Template-Literal, Verkettung, String()) wird toString() automatisch aufgerufen. Direkt nützlich ist die Methode beim Protokollieren, Debuggen, Testen oder wenn der Inhalt an eine API geht, die ausdrücklich einen normalen String erwartet.

Wichtig: Der zurückgegebene Wert ist ein gewöhnlicher String. Die Vertrauensmarkierung geht dabei verloren. Weist man diesen String bei aktiver CSP-Direktive require-trusted-types-for 'script' einer Einfügestelle zu, wird er wieder als unsicher eingestuft und blockiert, oder er läuft durch die Standardrichtlinie default. Das Ergebnis entspricht dem von TrustedHTML.prototype.toJSON().

Rückgabewert

Typ

string

Beschreibung

Der von der Richtlinie erzeugte HTML-String, ohne Vertrauensmarkierung.

Beispiele

Richtlinie anlegen und Inhalt auslesen

// 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(trusted instanceof TrustedHTML);
console.log(trusted.toString());

true <img src=x onerror=alert(1)>

Direkt zuweisen statt vorher umwandeln

const policy = trustedTypes.createPolicy('ui', {
  createHTML: (s) => DOMPurify.sanitize(s) // DOMPurify muss eingebunden sein
});

const html = policy.createHTML('<b>Hallo</b><script>alert(1)</script>');
const box = document.querySelector('#box');

// Richtig: TrustedHTML-Objekt direkt übergeben
box.innerHTML = html;

// Falsch unter require-trusted-types-for: normaler String wird blockiert
try {
  box.innerHTML = html.toString();
} catch (err) {
  console.error(err.name); // TypeError
}

TypeError

Automatische Umwandlung beim Protokollieren und in Tests

const policy = trustedTypes.createPolicy('test', {
  createHTML: (s) => s.trim()
});

const t = policy.createHTML('   <p>Text</p>   ');

// Template-Literal und String() rufen toString() implizit auf
console.log(`Inhalt: ${t}`);
console.assert(String(t) === '<p>Text</p>', 'Bereinigung fehlgeschlagen');
console.log(JSON.stringify({ t })); // nutzt toJSON()

Inhalt: <p>Text</p> {"t":"<p>Text</p>"}

// Wichtig · Fallstricke

Vertrauensmarkierung geht verloren: Das Ergebnis von toString() ist ein normaler String. Wenn Trusted Types per CSP erzwungen werden (Content-Security-Policy: require-trusted-types-for 'script'), blockiert der Browser ihn an Einfügestellen wie innerHTML mit einem TypeError, sofern keine default-Richtlinie greift. Übergib deshalb immer das TrustedHTML-Objekt selbst.
Keine eigene Bereinigung: toString() prüft oder bereinigt nichts. Wie sicher das Ergebnis ist, hängt allein von der createHTML-Funktion der Richtlinie ab. Eine Richtlinie, die ihre Eingabe unverändert zurückgibt, öffnet XSS-Lücken. Nutze erprobte Bereinigungsbibliotheken wie DOMPurify und begrenze die Richtliniennamen mit der CSP-Direktive trusted-types.
Browser-Unterstützung: Chromium-Browser (Chrome, Edge, Opera) unterstützen die API seit Version 83. In Firefox und Safari kam sie erst später. Prüfe die Verfügbarkeit mit 'trustedTypes' in window oder nutze den offiziellen Polyfill (trusted-types).
Die API steht auch in Web Workers zur Verfügung (self.trustedTypes).

Siehe auch

TrustedHTML TrustedHTML.toJSON() TrustedTypePolicy.createHTML() TrustedTypePolicyFactory.createPolicy() TrustedTypePolicyFactory.isHTML() Element.innerHTML CSSStyleValue.toString()