Temporal.ZonedDateTime.prototype.toJSON() — Methode · JavaScript-Referenz

Signatur

Temporal.ZonedDateTime.prototype.toJSON()

Beschreibung

toJSON() gibt einen String im erweiterten ISO-8601-/RFC-9557-Format zurück, z. B. "2025-03-30T02:30:00+02:00[Europe/Berlin]". Das Ergebnis ist dasselbe wie bei toString() ohne Optionen: Datum, Uhrzeit, Offset, Zeitzonen-Annotation in eckigen Klammern und, falls der Kalender nicht iso8601 ist, zusätzlich eine Kalender-Annotation wie [u-ca=japanese].

Selbst aufrufen muss man die Methode normalerweise nicht. Sie ist dafür da, dass JSON.stringify() ZonedDateTime-Objekte ohne Zusatzaufwand in Strings umwandeln kann, etwa beim Speichern in localStorage, beim Senden an eine REST-API oder beim Protokollieren.

Umgekehrt geht das nicht automatisch: JSON.parse() liefert nur einen String zurück. Um wieder ein Temporal.ZonedDateTime zu bekommen, übergibt man JSON.parse() eine reviver-Funktion, die Temporal.ZonedDateTime.from() aufruft.

Rückgabewert

Typ

string

Beschreibung

Ein String im RFC-9557-Format mit Datum, Uhrzeit, UTC-Offset und Zeitzonen-Annotation (gegebenenfalls auch mit Kalender-Annotation). Er ist identisch mit dem Ergebnis von zdt.toString().

Beispiele

Direkter Aufruf im Vergleich zu toString()

const zdt = Temporal.ZonedDateTime.from('2025-06-15T14:30:00[Europe/Berlin]');

console.log(zdt.toJSON());
console.log(zdt.toJSON() === zdt.toString());

2025-06-15T14:30:00+02:00[Europe/Berlin] true

Automatische Serialisierung mit JSON.stringify()

const termin = {
  titel: 'Team-Meeting',
  beginn: Temporal.ZonedDateTime.from('2025-11-03T09:00:00[America/New_York]')
};

const json = JSON.stringify(termin);
console.log(json);

{"titel":"Team-Meeting","beginn":"2025-11-03T09:00:00-05:00[America/New_York]"}

Wiederherstellen mit einer reviver-Funktion

const json = '{"titel":"Team-Meeting","beginn":"2025-11-03T09:00:00-05:00[America/New_York]"}';

const termin = JSON.parse(json, (key, value) =>
  key === 'beginn' ? Temporal.ZonedDateTime.from(value) : value
);

console.log(termin.beginn instanceof Temporal.ZonedDateTime);
console.log(termin.beginn.hour, termin.beginn.timeZoneId);

true 9 America/New_York

Kalender-Annotation im JSON-String

const zdt = Temporal.ZonedDateTime.from('2025-01-01T00:00:00[Asia/Tokyo][u-ca=japanese]');
console.log(JSON.stringify({ zdt }));

{"zdt":"2025-01-01T00:00:00+09:00[Asia/Tokyo][u-ca=japanese]"}

// Wichtig · Fallstricke

Keine automatische Deserialisierung: JSON.parse() gibt nur Strings zurück. Mit einer reviver-Funktion und Temporal.ZonedDateTime.from() baust du wieder Objekte daraus.
Nicht kompatibel mit Date: Das Format mit [Zeitzone] weicht von Date.prototype.toJSON() ab (...Z). Viele Backends und new Date(string) können die Klammer-Annotation nicht lesen. Wenn der Empfänger nur einen reinen Zeitpunkt braucht, sende besser zdt.toInstant().toJSON() oder zdt.toString({ timeZoneName: 'never' }).
Keine Formatierungsoptionen: toJSON() nimmt keine Argumente an. Für gerundete Sekunden oder andere Anzeigeformen verwende toString(options). Für Texte, die Menschen lesen sollen, ist toLocaleString() gedacht.
Browser-Unterstützung: Temporal ist neu und noch nicht in allen Engines vorhanden (z. B. fehlt es noch in Safari). In Produktion daher den Polyfill @js-temporal/polyfill verwenden oder vorher prüfen: typeof Temporal !== 'undefined'.
Wird die Methode mit einem this aufgerufen, das kein Temporal.ZonedDateTime ist, wirft sie einen TypeError.

Siehe auch

Temporal.ZonedDateTime.prototype.toString() Temporal.ZonedDateTime.from() Temporal.ZonedDateTime.prototype.toLocaleString() Temporal.Instant.prototype.toJSON() JSON.stringify() JSON.parse() Date.prototype.toJSON()