TrustedScriptURL.toJSON() — Methode · JavaScript-Referenz

Signatur

TrustedScriptURL.prototype.toJSON()

Beschreibung

Die Methode toJSON() der Schnittstelle TrustedScriptURL liefert die geprüfte Skript-URL als einfachen String zurück. Diesen Wert enthält das Objekt intern, seit es über eine Trusted-Types-Policy mit createScriptURL() erzeugt wurde.

Aufrufen muss man die Methode meist nicht selbst: JSON.stringify() ruft toJSON() automatisch auf, sobald es auf ein TrustedScriptURL-Objekt stößt. Ohne diese Methode würde ein solches Objekt als leeres Objekt {} serialisiert, weil es keine eigenen aufzählbaren Eigenschaften hat. Mit toJSON() steht die URL dagegen als String im JSON.

Das ist nützlich für Logging, Telemetrie, Debug-Ausgaben oder wenn Konfigurationsobjekte mit geprüften Skript-URLs an einen Server oder einen Worker übertragen werden. Das Ergebnis ist identisch mit dem von toString().

Rückgabewert

Typ

string

Beschreibung

Die gespeicherte, von der Policy geprüfte Skript-URL als einfacher String.

Beispiele

Direkter Aufruf von toJSON()

// Policy anlegen, die nur Skripte vom eigenen CDN erlaubt
const policy = trustedTypes.createPolicy('cdn-policy', {
  createScriptURL: (url) => {
    const parsed = new URL(url, location.href);
    if (parsed.origin !== 'https://cdn.example.com') {
      throw new TypeError(`Unerlaubte Skript-Quelle: ${url}`);
    }
    return parsed.href;
  }
});

const scriptUrl = policy.createScriptURL('https://cdn.example.com/app.js');
console.log(scriptUrl.toJSON());

https://cdn.example.com/app.js

Automatische Nutzung durch JSON.stringify()

const policy = trustedTypes.createPolicy('loader', {
  createScriptURL: (url) => url // nur zur Demonstration, keine Prüfung
});

const config = {
  name: 'analytics',
  src: policy.createScriptURL('https://cdn.example.com/analytics.js'),
  async: true
};

// JSON.stringify ruft src.toJSON() automatisch auf
console.log(JSON.stringify(config));

{"name":"analytics","src":"https://cdn.example.com/analytics.js","async":true}

Geladene Skripte fürs Monitoring protokollieren

const policy = trustedTypes.createPolicy('monitor', {
  createScriptURL: (url) => new URL(url, location.origin).href
});

const loaded = [];

const loadScript = (path) => {
  const url = policy.createScriptURL(path);
  const script = document.createElement('script');
  script.src = url; // TrustedScriptURL wird akzeptiert
  document.head.append(script);
  loaded.push({ url, time: Date.now() });
};

loadScript('/js/widget.js');

// Protokoll an den Server senden – die URLs landen als Strings im JSON
navigator.sendBeacon('/log', JSON.stringify(loaded));
console.log(JSON.stringify(loaded[0].url));

"https://www.example.com/js/widget.js"

// Wichtig · Fallstricke

Browser-Unterstützung: Die Trusted Types API gibt es in Chromium-Browsern (Chrome, Edge, Opera) seit Version 83, in Firefox seit Version 133 und in Safari erst seit neueren Versionen. Vorher auf 'trustedTypes' in window prüfen oder ein Polyfill wie trusted-types nutzen.
Kein Rückweg: Der zurückgegebene String ist kein vertrauenswürdiger Typ mehr. Wird er per JSON.parse() zurückgelesen und einer Senke wie script.src zugewiesen, blockiert der Browser das bei aktiver CSP-Direktive require-trusted-types-for 'script'. Man muss ihn dann erneut durch eine Policy schicken.
Sicherheit: Die Serialisierung macht die URL nicht sicherer. Die Sicherheit hängt allein von der Prüflogik in createScriptURL ab. Eine Policy, die Eingaben ungeprüft durchreicht (wie im zweiten Beispiel), untergräbt den Schutz vor XSS.
Das Ergebnis ist identisch mit toString(). Beim Übertragen an einen Worker per postMessage() wird das Objekt nicht automatisch umgewandelt; dort den String ausdrücklich übergeben.

Siehe auch

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