Date.prototype.toJSON() — Methode · JavaScript-Referenz

Signatur

Date.prototype.toJSON()

Beschreibung

toJSON() liefert eine Zeichenkette, die das Datum im vereinfachten ISO-8601-Format YYYY-MM-DDTHH:mm:ss.sssZ in UTC darstellt. Das Ergebnis ist dasselbe wie bei toISOString(). Es gibt einen wichtigen Unterschied: Bei einem ungültigen Datum (Invalid Date) gibt toJSON() den Wert null zurück. toISOString() wirft in diesem Fall einen RangeError.

Direkt ruft man die Methode nur selten auf. Sie ist vor allem für JSON.stringify() gedacht: Findet JSON.stringify() beim Serialisieren ein Objekt mit einer toJSON-Methode, verwendet es deren Rückgabewert. Deshalb erscheinen Date-Objekte in JSON automatisch als ISO-Strings, etwa in API-Anfragen, im localStorage oder in Logdateien.

Die Methode ist absichtlich generisch gebaut. Zuerst wandelt sie this in einen primitiven Wert mit dem Hinweis „number“ um. Ist das Ergebnis eine Zahl, die nicht endlich ist (z. B. NaN), gibt sie null zurück. Andernfalls ruft sie this.toISOString() auf. Deshalb funktioniert sie auch bei Objekten, die keine Date-Instanzen sind, solange sie eine toISOString-Methode haben.

Wichtig: Der umgekehrte Weg passiert nicht automatisch. JSON.parse() macht aus ISO-Strings keine Date-Objekte. Dafür braucht man eine Reviver-Funktion oder eine eigene Umwandlung.

Parameter

Name	Typ	Default	Beschreibung
$key	string		Wird von der Methode ignoriert. `JSON.stringify()` übergibt jeder `toJSON`-Methode den Eigenschaftsnamen, `Date.prototype.toJSON()` wertet ihn aber nicht aus. Beim direkten Aufruf übergibt man keine Argumente.

Rückgabewert

Typ

string | null

Beschreibung

Ein ISO-8601-String in UTC, z. B. "2024-01-15T10:30:00.000Z". Bei einem ungültigen Datum ist der Rückgabewert null.

Beispiele

Direkter Aufruf und Vergleich mit toISOString()

const termin = new Date(Date.UTC(2024, 0, 15, 10, 30));

console.log(termin.toJSON());
console.log(termin.toJSON() === termin.toISOString());

2024-01-15T10:30:00.000Z true

Automatische Serialisierung mit JSON.stringify()

const bestellung = {
  id: 4711,
  artikel: 'Tastatur',
  erstelltAm: new Date(Date.UTC(2024, 5, 1, 8, 0, 0)),
  geliefertAm: new Date('kein Datum') // ungültig
};

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

{"id":4711,"artikel":"Tastatur","erstelltAm":"2024-06-01T08:00:00.000Z","geliefertAm":null}

Rückweg: ISO-Strings beim Parsen per Reviver in Date umwandeln

const ISO_DATUM = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;

const reviver = (key, value) =>
  typeof value === 'string' && ISO_DATUM.test(value) ? new Date(value) : value;

const gespeichert = JSON.stringify({ login: new Date(Date.UTC(2024, 2, 10, 12)) });
const daten = JSON.parse(gespeichert, reviver);

console.log(daten.login instanceof Date);
console.log(daten.login.getUTCHours());

true 12

Unterschied bei ungültigem Datum und generischer Aufruf

const kaputt = new Date('31.12.2024'); // dieses Format wird nicht zuverlässig erkannt

console.log(kaputt.toJSON()); // null statt Fehler

try {
  kaputt.toISOString();
} catch (err) {
  console.log(err.name);
}

// Generisch: funktioniert mit jedem Objekt, das toISOString() besitzt
const pseudo = { valueOf: () => 0, toISOString: () => 'eigenes Format' };
console.log(Date.prototype.toJSON.call(pseudo));

null RangeError eigenes Format

// Wichtig · Fallstricke

Immer UTC: Die Ausgabe endet stets auf Z, die lokale Zeitzone geht verloren. new Date(2024, 0, 1) in Berlin ergibt zum Beispiel \"2023-12-31T23:00:00.000Z\". Wer die lokale Zeit oder den Zeitzonen-Versatz behalten will, muss beides selbst formatieren.
Stilles null: Ungültige Datumswerte erzeugen keinen Fehler, sondern landen als null im JSON. Bei wichtigen Daten sollte man deshalb vor dem Serialisieren mit Number.isNaN(datum.getTime()) prüfen, ob das Datum gültig ist.
Kein automatischer Rückweg: JSON.parse() liefert Strings, keine Date-Objekte. Die Umwandlung zurück braucht einen Reviver oder eine Schema-Bibliothek.
Erweiterte Jahreszahlen: Jahre vor 0 oder nach 9999 werden sechsstellig mit Vorzeichen ausgegeben, z. B. \"+010000-01-01T00:00:00.000Z\". Manche Parser anderer Sprachen können damit nicht umgehen.
Überschreiben: Date.prototype.toJSON lässt sich global überschreiben, etwa um Unix-Zeitstempel auszugeben. Das betrifft aber jedes JSON.stringify() in der ganzen Anwendung und in allen Bibliotheken. Besser ist eine replacer-Funktion. Achtung: Ein replacer bekommt den Wert erst nach dem Aufruf von toJSON(), also bereits als String. Das ursprüngliche Date findet man über this[key].
Die Methode wird seit ES5.1 in allen modernen Browsern und in Node.js unterstützt.

Siehe auch

Date.prototype.toISOString() JSON.stringify() JSON.parse() Date.prototype.toUTCString() Date.prototype.getTime() Date