WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Date.prototype.toJSON: Date in der JSON-Serialisierung

toJSON liefert ISO-Text für ein gültiges Datum, null für ein ungültiges und wird automatisch von JSON.stringify aufgerufen.

Version: ECMAScript 5 (2009) onward; example target: Node.js 24.22.2

Syntax

date.toJSON(key)

date.toJSON(key) liefert normalerweise dieselbe Zeichenkette wie date.toISOString(). JSON.stringify ruft die Methode mit dem Eigenschaftsschlüssel auf, der Standardalgorithmus verwendet key aber nicht. Bei einem ungültigen Date ist die Zahlenkonvertierung nicht endlich, daher entsteht null statt des RangeError von toISOString().

Die Methode ist absichtlich generisch: Sie ermittelt erst einen Primitivwert mit Zahlenhinweis. Nur wenn dieser ein nicht endlicher Number ist, liefert sie null; sonst ruft sie die Eigenschaft toISOString des Receivers auf. Deshalb kann sie auch auf Nicht-Date-Objekten arbeiten. Fehler bei Konvertierung sowie nicht aufrufbares oder werfendes toISOString werden weitergegeben.

JSON bewahrt den Zeitpunkt als UTC-Text, verliert aber den Date-Typ; nach dem Parsen liegt ein String vor. Die Methode ist seit ECMAScript 5 (2009) standardisiert.

Beispiele

const payload = {
  when: new Date("2024-01-02T03:04:05.006Z"),
  missing: new Date(NaN),
};
console.log(JSON.stringify(payload));
console.log(payload.when.toJSON());

const custom = {valueOf: () => 0, toISOString: () => "custom-time"};
console.log(Date.prototype.toJSON.call(custom));

Ergebnis

{"when":"2024-01-02T03:04:05.006Z","missing":null}
2024-01-02T03:04:05.006Z
custom-time

Quellen