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

Signatur

Date.prototype.toISOString()

Beschreibung

toISOString() wandelt eine Date-Instanz in einen String im Date Time String Format von ECMAScript um. Das Format ist eine vereinfachte Form von ISO 8601 und ist immer 24 Zeichen lang (YYYY-MM-DDTHH:mm:ss.sssZ). Bei Jahren außerhalb von 0000–9999 sind es 27 Zeichen mit erweitertem Jahr und Vorzeichen (±YYYYYY-MM-DDTHH:mm:ss.sssZ).

Die Ausgabe ist immer in UTC, zu erkennen am Suffix Z. Die lokale Zeitzone der Laufzeitumgebung spielt keine Rolle. Deshalb eignet sich die Methode gut, um Zeitpunkte eindeutig und unabhängig von der Zeitzone zu speichern oder zu übertragen, etwa in JSON-APIs, Datenbanken, Logdateien oder als Sortierschlüssel. Weil alle Stellen mit führenden Nullen aufgefüllt werden, lassen sich die Strings innerhalb desselben Jahresbereichs auch lexikografisch sortieren.

Diese Methode steckt auch hinter Date.prototype.toJSON(). Deshalb landen Date-Objekte in JSON.stringify() automatisch als ISO-String im Ergebnis. Umgekehrt können new Date(isoString) und Date.parse() diesen String zuverlässig in allen Umgebungen einlesen.

Rückgabewert

Typ

string

Beschreibung

Ein String im Format YYYY-MM-DDTHH:mm:ss.sssZ (bzw. ±YYYYYY-MM-DDTHH:mm:ss.sssZ bei erweiterten Jahren), der den Zeitpunkt in UTC darstellt. Bei einem ungültigen Datum wird ein RangeError geworfen.

Beispiele

Grundlegende Umwandlung in UTC

// Zeitpunkt als UTC-Millisekunden angeben, damit das Ergebnis eindeutig ist
const d = new Date(Date.UTC(2024, 2, 15, 9, 30, 5, 123));
console.log(d.toISOString());

// Lokale Uhrzeit wird nach UTC umgerechnet
const lokal = new Date('2024-03-15T10:30:00+01:00');
console.log(lokal.toISOString());

2024-03-15T09:30:05.123Z 2024-03-15T09:30:00.000Z

Zeitstempel für API-Request und JSON

const payload = {
  event: 'login',
  createdAt: new Date(Date.UTC(2024, 0, 1, 12, 0, 0))
};

// JSON.stringify ruft intern toJSON() → toISOString() auf
const body = JSON.stringify(payload);
console.log(body);

// Beim Einlesen wieder in ein Date zurückverwandeln
const parsed = JSON.parse(body, (key, value) =>
  key === 'createdAt' ? new Date(value) : value
);
console.log(parsed.createdAt instanceof Date);

{"event":"login","createdAt":"2024-01-01T12:00:00.000Z"} true

Nur das Datum (YYYY-MM-DD) extrahieren – mit Vorsicht

const d = new Date(Date.UTC(2024, 11, 24, 23, 15));

// UTC-Datum
const utcDatum = d.toISOString().slice(0, 10);
console.log(utcDatum);

// Lokales Datum im ISO-Format (Zeitzonenversatz ausgleichen)
const lokalesDatum = (date) => {
  const offsetMs = date.getTimezoneOffset() * 60_000;
  return new Date(date.getTime() - offsetMs).toISOString().slice(0, 10);
};
console.log(lokalesDatum(d)); // z. B. in Europe/Berlin

2024-12-24 2024-12-25

Ungültiges Datum sicher behandeln

const toIsoSafe = (value) => {
  const d = new Date(value);
  return Number.isNaN(d.getTime()) ? null : d.toISOString();
};

console.log(toIsoSafe('2024-05-01T08:00:00Z'));
console.log(toIsoSafe('kein Datum'));

try {
  new Date('kein Datum').toISOString();
} catch (err) {
  console.log(err.name);
}

2024-05-01T08:00:00.000Z null RangeError

// Wichtig · Fallstricke

RangeError bei ungültigem Datum: Ist das Datum ungültig (Invalid Date, also getTime() ergibt NaN), wirft toISOString() einen RangeError. toJSON() gibt in diesem Fall dagegen null zurück. Prüfen Sie Eingaben vorher mit Number.isNaN(date.getTime()).
Immer UTC: Die Ausgabe enthält nie den lokalen Zeitzonenversatz. Wer mit .slice(0, 10) das „heutige Datum“ ausliest, bekommt kurz vor oder nach Mitternacht womöglich den Vortag oder Folgetag. Für lokale Darstellung eignen sich toLocaleDateString() oder Intl.DateTimeFormat.
Keine Mikrosekunden: Date rechnet nur in Millisekunden. Die Ausgabe hat daher immer genau drei Nachkommastellen, auch wenn diese .000 lauten.
Erweiterte Jahre: Bei Jahren unter 0 oder über 9999 ist die Ausgabe 27 Zeichen lang (z. B. +010000-01-01T00:00:00.000Z). Code, der fest mit 24 Zeichen rechnet, bricht dann.
Kompatibilität: Die Methode gibt es seit ES5 in allen Browsern und in Node.js. Das Einlesen von ISO-Strings mit Date.parse() ist nur für genau dieses Format überall garantiert. Andere Formate sind implementierungsabhängig.
Die künftige Temporal-API bietet mit Temporal.Instant.prototype.toString() eine genauere Alternative (Nanosekunden, explizite Zeitzonen).

Siehe auch

Date.prototype.toJSON() Date.prototype.toUTCString() Date.prototype.toLocaleDateString() Date.parse() Date.UTC() Date.prototype.getTimezoneOffset() JSON.stringify() Intl.DateTimeFormat