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

Signatur

Temporal.PlainDateTime.prototype.toJSON()

Beschreibung

Die Methode toJSON() einer Temporal.PlainDateTime-Instanz liefert einen String wie "2021-08-01T12:34:56". Das Ergebnis ist identisch mit dem Aufruf von toString() ohne Argumente. Das Format folgt RFC 9557 (einer Erweiterung von ISO 8601 bzw. RFC 3339). Eine Kalender-Annotation wie [u-ca=hebrew] wird nur angehängt, wenn der Kalender nicht iso8601 ist.

Normalerweise ruft man toJSON() nicht selbst auf. JSON.stringify() ruft sie automatisch auf, sobald ein Temporal.PlainDateTime-Objekt in den zu serialisierenden Daten vorkommt. Temporal-Objekte lassen sich deshalb direkt in Objekte packen, die du per fetch() verschickst, in localStorage ablegst oder in Logdateien schreibst.

Umgekehrt funktioniert es nicht automatisch: JSON.parse() macht aus dem String kein Temporal-Objekt. Dafür brauchst du eine Reviver-Funktion, die die betreffenden Felder mit Temporal.PlainDateTime.from() umwandelt. Wenn du das Ausgabeformat steuern willst (z. B. Sekundenbruchteile abschneiden oder die Kalender-Annotation erzwingen), nimm toString(options). toJSON() nimmt keine Optionen an.

Rückgabewert

Typ

string

Beschreibung

Ein String im RFC-9557-Format, z. B. "2021-08-01T12:34:56" oder "2021-08-01T12:34:56.5". Er enthält keine Zeitzone und keinen UTC-Versatz. Bei einem Kalender außer ISO kommt eine Annotation wie [u-ca=hebrew] dazu.

Beispiele

Direkter Aufruf und Vergleich mit toString()

const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:56");

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

// Sekunden werden immer ausgegeben, Sekundenbruchteile nur bei Bedarf
const ohneSekunden = new Temporal.PlainDateTime(2021, 8, 1, 12, 34);
console.log(ohneSekunden.toJSON());

const mitBruchteil = new Temporal.PlainDateTime(2021, 8, 1, 12, 34, 56, 500);
console.log(mitBruchteil.toJSON());

2021-08-01T12:34:56 true 2021-08-01T12:34:00 2021-08-01T12:34:56.5

Automatische Serialisierung mit JSON.stringify()

const termin = {
  titel: "Team-Meeting",
  beginn: Temporal.PlainDateTime.from("2025-03-14T09:30"),
  ende: Temporal.PlainDateTime.from("2025-03-14T10:15"),
};

// JSON.stringify ruft toJSON() für jedes Temporal-Objekt auf
const json = JSON.stringify(termin);
console.log(json);

{"titel":"Team-Meeting","beginn":"2025-03-14T09:30:00","ende":"2025-03-14T10:15:00"}

Zurück in Temporal-Objekte umwandeln (Reviver)

const json = '{"titel":"Team-Meeting","beginn":"2025-03-14T09:30:00","ende":"2025-03-14T10:15:00"}';

const datumsFelder = new Set(["beginn", "ende"]);

const termin = JSON.parse(json, (key, value) =>
  datumsFelder.has(key) ? Temporal.PlainDateTime.from(value) : value
);

const dauer = termin.beginn.until(termin.ende);
console.log(termin.beginn instanceof Temporal.PlainDateTime);
console.log(dauer.toString());

true PT45M

Kalender außer ISO: Annotation im JSON

const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:00").withCalendar("hebrew");

console.log(JSON.stringify({ zeitpunkt: dt }));

// Beim Einlesen bleibt der Kalender dank Annotation erhalten
const zurueck = Temporal.PlainDateTime.from("2021-08-01T12:34:00[u-ca=hebrew]");
console.log(zurueck.calendarId);

{"zeitpunkt":"2021-08-01T12:34:00[u-ca=hebrew]"} hebrew

// Wichtig · Fallstricke

Keine Zeitzone: Der String beschreibt eine „Wanduhrzeit“ ohne Versatz und ohne Zeitzone. Andere Systeme deuten ihn womöglich falsch. new Date("2021-08-01T12:34:56") etwa liest ihn als lokale Zeit. Wenn du einen eindeutigen Zeitpunkt übertragen willst, nimm Temporal.ZonedDateTime oder Temporal.Instant.
Kein automatisches Einlesen: JSON.parse() gibt nur einen String zurück. Um wieder ein Temporal-Objekt zu bekommen, brauchst du einen Reviver mit Temporal.PlainDateTime.from().
Keine Optionen: Argumente werden nicht ausgewertet. Für Formate wie smallestUnit, fractionalSecondDigits oder calendarName nimm toString(options). Für lesbare Ausgaben für Menschen nimm toLocaleString().
Vergleiche: valueOf() wirft einen TypeError, damit < und > nicht aus Versehen verwendet werden. Vergleiche sollten über Temporal.PlainDateTime.compare() laufen, nicht über die JSON-Strings. Diese sind nur bei gleichem Kalender und Jahren zwischen 0 und 9999 lexikografisch sortierbar.
Kompatibilität: Temporal ist erst seit Kurzem in Firefox (139+) und Chromium-Browsern (ab etwa Version 144) verfügbar, in Safari noch nicht. Für ältere Umgebungen oder Node.js gibt es ein Polyfill, z. B. @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

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