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

Signatur

Temporal.Instant.prototype.toJSON()

Beschreibung

Die Methode toJSON() von Temporal.Instant-Instanzen gibt eine Zeichenkette zurück, die den Zeitpunkt im RFC 9557-Format darstellt, z. B. "2024-03-15T12:30:00Z". Das Ergebnis ist dasselbe wie bei einem Aufruf von toString() ohne Argumente: Die Zeit wird in UTC ausgegeben, mit dem Suffix Z und nur so vielen Nachkommastellen wie nötig (bis zu Nanosekunden).

Normalerweise ruft man toJSON() nicht direkt auf. JSON.stringify() ruft die Methode automatisch auf, wenn es ein Temporal.Instant serialisiert. So landen Zeitpunkte in Objekten ohne eigenen Code als lesbare, sortierbare ISO-Zeichenketten im JSON, etwa für REST-APIs, Logs oder localStorage.

Beim Rückweg funktioniert das nicht automatisch: JSON.parse() erzeugt aus der Zeichenkette kein Temporal.Instant. Man muss sie selbst mit Temporal.Instant.from() umwandeln, am besten in einer Reviver-Funktion.

Rückgabewert

Typ

string

Beschreibung

Eine Zeichenkette im RFC 9557- bzw. ISO 8601-Format in UTC, z. B. "2024-03-15T12:30:00.123Z". Sie ist identisch mit instant.toString().

Beispiele

Direkter Aufruf im Vergleich zu toString()

const instant = Temporal.Instant.from("2024-03-15T13:30:00.5+01:00");

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

2024-03-15T12:30:00.5Z true

Automatische Serialisierung mit JSON.stringify()

const event = {
  id: 42,
  typ: "login",
  zeitpunkt: Temporal.Instant.fromEpochMilliseconds(1710505800000),
};

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

{"id":42,"typ":"login","zeitpunkt":"2024-03-15T12:30:00Z"}

Rückweg: Instant per Reviver wiederherstellen

const json = '{"id":42,"zeitpunkt":"2024-03-15T12:30:00Z"}';

const daten = JSON.parse(json, (key, value) =>
  key === "zeitpunkt" ? Temporal.Instant.from(value) : value
);

console.log(daten.zeitpunkt instanceof Temporal.Instant);
console.log(daten.zeitpunkt.epochMilliseconds);

true 1710505800000

Eigenes Format statt toJSON() mit einem Replacer

const log = { ts: Temporal.Instant.from("2024-03-15T12:30:00.123456789Z") };

// Auf Sekunden runden und als Zeitzonen-Offset ausgeben
const json = JSON.stringify(log, function (key, value) {
  const original = this[key];
  return original instanceof Temporal.Instant
    ? original.toString({ smallestUnit: "second", timeZone: "Europe/Berlin" })
    : value;
});

console.log(json);

{"ts":"2024-03-15T13:30:00+01:00"}

// Wichtig · Fallstricke

Keine Optionen: toJSON() nimmt keine Argumente. Wenn du eine andere Genauigkeit, eine Rundung oder einen Zeitzonen-Offset brauchst, nimm toString(options), zum Beispiel in einem Replacer für JSON.stringify(). Beachte: Der Replacer bekommt den Wert erst nach dem Aufruf von toJSON(). Das Original erreichst du nur über this[key].
Kein automatischer Rückweg: JSON.parse() liefert eine normale Zeichenkette. Für ein Instant brauchst du Temporal.Instant.from().
Unterschied zu Date: Date.prototype.toJSON() gibt immer genau drei Nachkommastellen aus (Millisekunden). Temporal.Instant gibt nur so viele aus wie nötig, bis zu neun (Nanosekunden). Wenn ein Parser feste Längen erwartet, kann das Probleme machen.
Kompatibilität: Temporal ist noch recht neu. Firefox ab Version 139 und Chrome ab Version 144 unterstützen es. In Safari und älteren Umgebungen brauchst du einen Polyfill, z. B. @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

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