TrustedHTML.toJSON() — Methode · JavaScript-Referenz

Signatur

TrustedHTML.prototype.toJSON()

Beschreibung

Die Methode toJSON() der Schnittstelle TrustedHTML liefert den intern gespeicherten HTML-String. Das Ergebnis entspricht dem von toString(). Die Methode gibt es vor allem, damit JSON.stringify() ein TrustedHTML-Objekt sinnvoll serialisiert. Ohne toJSON() käme nur ein leeres Objekt {} heraus, weil der Wert nicht als aufzählbare Eigenschaft gespeichert ist.

Ein TrustedHTML-Objekt entsteht über eine Trusted-Types-Richtlinie, also mit trustedTypes.createPolicy() und policy.createHTML(). So ein Objekt bestätigt: Der enthaltene Markup-String ist durch die Bereinigungsfunktion der Richtlinie gelaufen und darf in DOM-Senken wie Element.innerHTML geschrieben werden.

Nützlich ist toJSON(), wenn du vertrauenswürdiges Markup protokollieren, an einen Server schicken, in localStorage speichern oder per postMessage als JSON übertragen willst. Wichtig: Beim Serialisieren geht der Typ TrustedHTML verloren. Nach JSON.parse() hast du nur noch einen gewöhnlichen String, und den lehnen Senken bei aktivem require-trusted-types-for 'script' ab.

Rückgabewert

Typ

string

Beschreibung

Der gespeicherte, von der Richtlinie bereinigte HTML-String. Er ist identisch mit dem Ergebnis von toString().

Beispiele

Direkter Aufruf von toJSON()

// 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.toJSON());
console.log(typeof trusted.toJSON());

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

Automatische Nutzung durch JSON.stringify()

const policy = trustedTypes.createPolicy('json-demo', {
  createHTML: (input) => input.replace(/</g, '&lt;'),
});

const payload = {
  id: 42,
  // JSON.stringify ruft hier intern toJSON() auf
  content: policy.createHTML('<b>Hallo</b>'),
};

console.log(JSON.stringify(payload));

{"id":42,"content":"<b>Hallo</b>"}

Speichern und wieder vertrauenswürdig machen

const policy = trustedTypes.createPolicy('storage-policy', {
  // In echten Projekten z. B. DOMPurify.sanitize(input) verwenden
  createHTML: (input) => input.replace(/<script[\s\S]*?<\/script>/gi, ''),
});

const snippet = policy.createHTML('<p>Notiz</p><script>alert(1)</script>');
localStorage.setItem('notiz', JSON.stringify(snippet));

// Beim Laden ist es nur noch ein String und muss erneut durch die Richtlinie laufen
const raw = JSON.parse(localStorage.getItem('notiz'));
console.log(raw instanceof TrustedHTML);

document.body.innerHTML = policy.createHTML(raw);

false

// Wichtig · Fallstricke

Der Typ geht verloren: Nach dem Serialisieren und JSON.parse() hast du einen normalen String. Ist die CSP-Direktive require-trusted-types-for 'script' aktiv, wirft eine Zuweisung an innerHTML dann einen TypeError. Schicke deserialisierte Daten also immer wieder durch eine Richtlinie.
Sicherheit: Das Ergebnis ist nur so sicher wie die Bereinigungsfunktion der Richtlinie. Eine Richtlinie, die ihre Eingabe unverändert zurückgibt, bietet keinen XSS-Schutz. Nimm eine erprobte Bibliothek wie DOMPurify und beschränke die erlaubten Richtliniennamen mit der CSP-Direktive trusted-types.
Daten von außen: JSON aus dem Netzwerk, aus localStorage oder aus postMessage ist nicht vertrauenswürdig, auch wenn es ursprünglich aus einem TrustedHTML stammt. Es kann unterwegs manipuliert worden sein.
Kompatibilität: Die Trusted Types API gibt es in Chromium-Browsern seit Version 83, außerdem in neueren Versionen von Safari und Firefox. In älteren Browsern fehlt trustedTypes. Prüfe das vorher mit if (window.trustedTypes) oder nutze ein Polyfill.
Die Methode verhält sich genauso wie toString(). Welche du nimmst, ist eine Frage der Lesbarkeit.

Siehe auch

JSON.stringify() LayoutShift.toJSON() TrustedHTML.toString() TrustedScript.toJSON() TrustedScriptURL.toJSON()