Date — Klasse · JavaScript-Referenz

Signatur

Date

Beschreibung

JavaScript-Date-Objekte repräsentieren einen einzelnen Zeitpunkt in einem plattformunabhängigen Format. Date-Objekte kapseln eine ganzzahlige Zahl, die die Millisekunden seit Mitternacht zu Beginn des 1. Januar 1970 UTC (der epoch) repräsentiert.

Hinweis: Mit der Einführung der Temporal-API gilt das Date-Objekt als Legacy-Feature. Erwäge, Temporal für neuen Code zu verwenden und bestehenden Code nach Möglichkeit dorthin zu migrieren.

Die epoch, Timestamps und Invalid Date

Ein JavaScript-Datum ist grundlegend als die Zeit in Millisekunden spezifiziert, die seit der epoch verstrichen ist, welche als Mitternacht zu Beginn des 1. Januar 1970 UTC definiert ist (äquivalent zur UNIX-Epoch). Dieser Timestamp ist zeitzonenunabhängig und definiert eindeutig einen Moment in der Geschichte.

Hinweis: Während der Zeitwert im Herzen eines Date-Objekts UTC ist, arbeiten die grundlegenden Methoden zum Abrufen von Datum, Zeit oder deren Bestandteilen alle in der lokalen (d. h. Host-System) Zeitzone und deren Offset.

Der maximale von einem Date-Objekt darstellbare Timestamp ist etwas kleiner als der maximale sichere Integer (Number.MAX_SAFE_INTEGER, was 9.007.199.254.740.991 entspricht). Ein Date-Objekt kann maximal ±8.640.000.000.000.000 Millisekunden bzw. ±100.000.000 (einhundert Millionen) Tage relativ zur epoch darstellen. Das ist der Bereich vom 20. April 271821 v. Chr. bis zum 13. September 275760 n. Chr. Jeder Versuch, eine Zeit außerhalb dieses Bereichs darzustellen, führt dazu, dass das Date-Objekt den Timestamp-Wert NaN hält, was ein "Invalid Date" ist.

Es gibt verschiedene Methoden, mit denen man mit dem im Datum gespeicherten Timestamp interagieren kann:

Man kann direkt mit dem Timestamp-Wert über die Methoden getTime() und setTime() interagieren.
Die Methoden valueOf() und [Symbol.toPrimitive]() (wenn "number" übergeben wird) — die bei der number coercion automatisch aufgerufen werden — geben den Timestamp zurück, sodass sich Date-Objekte in Zahlenkontexten wie ihre Timestamps verhalten.
Alle statischen Methoden (Date.now(), Date.parse() und Date.UTC()) geben Timestamps anstelle von Date-Objekten zurück.
Der Date()-Konstruktor kann mit einem Timestamp als einzigem Argument aufgerufen werden.

Datumsbestandteile und Zeitzonen

Ein Datum wird intern als einzelne Zahl, der Timestamp, repräsentiert. Bei der Interaktion mit ihm muss der Timestamp als strukturierte Datum-und-Zeit-Repräsentation interpretiert werden. Es gibt immer zwei Möglichkeiten, einen Timestamp zu interpretieren: als lokale Zeit oder als Coordinated Universal Time (UTC), der globalen Standardzeit, die durch den World Time Standard definiert ist. Die lokale Zeitzone wird nicht im Date-Objekt gespeichert, sondern durch die Host-Umgebung (Gerät des Nutzers) bestimmt.

Hinweis: UTC sollte nicht mit der Greenwich Mean Time (GMT) verwechselt werden, da sie nicht immer gleich sind.

Zum Beispiel repräsentiert der Timestamp 0 einen eindeutigen Moment in der Geschichte, kann aber auf zwei Arten interpretiert werden:

Als UTC-Zeit ist es Mitternacht zu Beginn des 1. Januar 1970 UTC,
Als lokale Zeit in New York (UTC-5) ist es 19:00:00 am 31. Dezember 1969.

Die Methode getTimezoneOffset() gibt die Differenz zwischen UTC und der lokalen Zeit in Minuten zurück. Zu beachten ist, dass der Zeitzonen-Offset nicht nur von der aktuellen Zeitzone abhängt, sondern auch von der durch das Date-Objekt repräsentierten Zeit, wegen Sommerzeit und historischen Änderungen. Im Wesentlichen ist der Zeitzonen-Offset der Offset von der UTC-Zeit, zum durch das Date-Objekt repräsentierten Zeitpunkt und am Standort der Host-Umgebung.

Es gibt zwei Gruppen von Date-Methoden: Eine Gruppe holt und setzt verschiedene Datumsbestandteile, indem der Timestamp als lokale Zeit interpretiert wird, während die andere UTC verwendet.

Der Date()-Konstruktor kann mit zwei oder mehr Argumenten aufgerufen werden; in diesem Fall werden sie als Jahr, Monat, Tag, Stunde, Minute, Sekunde bzw. Millisekunde in lokaler Zeit interpretiert. Date.UTC() funktioniert ähnlich, interpretiert die Komponenten jedoch als UTC-Zeit und akzeptiert auch ein einzelnes Argument, das das Jahr repräsentiert.

Hinweis: Einige Methoden, einschließlich des Date()-Konstruktors, Date.UTC() und der veralteten Methoden getYear()/setYear(), interpretieren ein zweistelliges Jahr als Jahr in den 1900er Jahren. Zum Beispiel wird new Date(99, 5, 24) als 24. Juni 1999 interpretiert, nicht als 24. Juni 99.

Wenn ein Segment seinen erwarteten Bereich über- oder unterschreitet, wird üblicherweise in das höhere Segment übertragen oder von diesem geborgt. Wird beispielsweise der Monat auf 12 gesetzt (Monate sind nullbasiert, Dezember ist also 11), wird daraus der Januar des nächsten Jahres. Wird der Tag des Monats auf 0 gesetzt, wird daraus der letzte Tag des Vormonats. Dies gilt auch für Daten, die im date time string format angegeben werden.

Beim Versuch, die lokale Zeit auf einen Zeitpunkt innerhalb eines Offset-Übergangs (üblicherweise Sommerzeit) zu setzen, wird die exakte Zeit mit demselben Verhalten wie die disambiguation: "compatible"-Option von Temporal abgeleitet. Das heißt, wenn die lokale Zeit zwei Instants entspricht, wird der frühere gewählt; wenn die lokale Zeit nicht existiert (es gibt eine Lücke), gehen wir um die Länge der Lücke vorwärts.

Date time string format

Es gibt viele Möglichkeiten, ein Datum als String zu formatieren. Die JavaScript-Spezifikation spezifiziert nur ein universell unterstütztes Format: das date time string format, eine Vereinfachung des ISO-8601-Kalenderdatum-Extended-Formats. Das Format lautet:

YYYY-MM-DDTHH:mm:ss.sssZ

YYYY ist das Jahr, mit vier Ziffern (0000 bis 9999), oder als expanded year mit + oder - gefolgt von sechs Ziffern. Das Vorzeichen ist für expanded years erforderlich. -000000 ist explizit als gültiges Jahr unzulässig.
MM ist der Monat, mit zwei Ziffern (01 bis 12). Standard ist 01.
DD ist der Tag des Monats, mit zwei Ziffern (01 bis 31). Standard ist 01.
T ist ein literales Zeichen, das den Beginn des time-Teils des Strings anzeigt. Das T ist erforderlich, wenn der Zeitteil angegeben wird.
HH ist die Stunde, mit zwei Ziffern (00 bis 23). Als Sonderfall ist 24:00:00 erlaubt und wird als Mitternacht zu Beginn des nächsten Tages interpretiert. Standard ist 00.
mm ist die Minute, mit zwei Ziffern (00 bis 59). Standard ist 00.
ss ist die Sekunde, mit zwei Ziffern (00 bis 59). Standard ist 00.
sss ist die Millisekunde, mit drei Ziffern (000 bis 999). Standard ist 000.
Z ist der Zeitzonen-Offset, der entweder das literale Zeichen Z (UTC anzeigend) sein kann, oder + bzw. - gefolgt von HH:mm, dem Offset in Stunden und Minuten von UTC.

Verschiedene Komponenten können weggelassen werden, sodass die folgenden alle gültig sind:

Nur-Datum-Form: YYYY, YYYY-MM, YYYY-MM-DD
Datum-Zeit-Form: eine der obigen Nur-Datum-Formen, gefolgt von T, gefolgt von HH:mm, HH:mm:ss oder HH:mm:ss.sss. Jede Kombination kann von einem Zeitzonen-Offset gefolgt werden.

Beispielsweise sind "2011-10-10" (Nur-Datum-Form), "2011-10-10T14:48:00" (Datum-Zeit-Form) oder "2011-10-10T14:48:00.000+09:00" (Datum-Zeit-Form mit Millisekunden und Zeitzone) alles gültige date time strings.

Wenn der Zeitzonen-Offset fehlt, werden Nur-Datum-Formen als UTC-Zeit und Datum-Zeit-Formen als lokale Zeit interpretiert. Die Interpretation als UTC-Zeit geht auf einen historischen Spezifikationsfehler zurück, der nicht mit ISO 8601 konsistent war, aber aufgrund der Web-Kompatibilität nicht geändert werden konnte.

Date.parse() und der Date()-Konstruktor akzeptieren beide Strings im date time string format als Eingabe. Darüber hinaus dürfen Implementierungen andere Datumsformate unterstützen, wenn die Eingabe nicht diesem Format entspricht.

Die Methode toISOString() gibt eine String-Repräsentation des Datums im date time string format zurück, wobei der Zeitzonen-Offset immer auf Z (UTC) gesetzt ist.

Hinweis: Es wird empfohlen sicherzustellen, dass deine Eingabe dem obigen date time string format entspricht, um maximale Kompatibilität zu erreichen, da die Unterstützung anderer Formate nicht garantiert ist. Es gibt jedoch einige Formate, die in allen größeren Implementierungen unterstützt werden — wie das RFC-2822-Format — in welchem Fall ihre Verwendung akzeptabel sein kann. Führe immer Cross-Browser-Tests durch.

Nicht-standardisierte Strings können auf jede von der Implementierung gewünschte Weise geparst werden, einschließlich der Zeitzone — die meisten Implementierungen verwenden standardmäßig die lokale Zeitzone. Implementierungen sind nicht verpflichtet, ein invalid date für Datumsbestandteile außerhalb der Grenzen zurückzugeben, tun dies aber meist. Ein String kann Datumsbestandteile innerhalb der Grenzen (mit den oben definierten Grenzen) haben, aber tatsächlich kein reales Datum repräsentieren (zum Beispiel "February 30"). Implementierungen verhalten sich in diesem Fall inkonsistent.

Andere Möglichkeiten, ein Datum zu formatieren

toISOString() gibt einen String im Format 1970-01-01T00:00:00.000Z zurück (das oben eingeführte date time string format, das vereinfachtes ISO 8601 ist). toJSON() ruft toISOString() auf und gibt das Ergebnis zurück.
toString() gibt einen String im Format Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time) zurück, während toDateString() und toTimeString() die Datums- bzw. Zeitteile des Strings zurückgeben. [Symbol.toPrimitive]() (wenn "string" oder "default" übergeben wird) ruft toString() auf und gibt das Ergebnis zurück.
toUTCString() gibt einen String im Format Thu, 01 Jan 1970 00:00:00 GMT zurück (verallgemeinertes RFC 7231).
toLocaleDateString(), toLocaleTimeString() und toLocaleString() verwenden locale-spezifische Datums- und Zeitformate, üblicherweise bereitgestellt durch die Intl-API.

Parameter

Name	Typ	Default	Beschreibung
$value	number\|string\|Date\|undefined	aktuelle Systemzeit	Entweder ein numerischer Unix-Timestamp (ms), ein Datums-String (z. B. `'2024-06-15'`), ein anderes `Date`-Objekt oder weggelassen für die aktuelle Zeit.
$year	number		Vierstellige Jahreszahl bei Verwendung der Mehrteiligen Signatur `new Date(year, month, …)`.
$month	number		0-basierter Monat (0 = Januar, 11 = Dezember). Pflichtangabe bei Verwendung der Komponentenform.
$day	number	1	Tag des Monats (1–31).
$hours	number	0	Stunden (0–23) in Ortszeit.
$minutes	number	0	Minuten (0–59).
$seconds	number	0	Sekunden (0–59).
$milliseconds	number	0	Millisekunden (0–999).

Rückgabewert

Typ

Date

Beschreibung

Eine neue Date-Instanz, die den angegebenen Zeitpunkt repräsentiert. Ist der übergebene Wert ungültig, enthält das Objekt NaN als internen Timestamp — prüfbar via isNaN(date).

Beispiele

Mehrere Möglichkeiten, ein Date-Objekt zu erstellen

const today = new Date();
const birthday = new Date("December 17, 1995 03:24:00"); // DISCOURAGED: may not work in all runtimes
const birthday2 = new Date("1995-12-17T03:24:00"); // This is standardized and will work reliably
const birthday3 = new Date(1995, 11, 17); // the month is 0-indexed
const birthday4 = new Date(1995, 11, 17, 3, 24, 0);
const birthday5 = new Date(628021800000); // passing epoch timestamp

Formate der Rückgabewerte der toString-Methode

const date = new Date("2020-05-12T23:50:21.817Z");
date.toString(); // Tue May 12 2020 18:50:21 GMT-0500 (Central Daylight Time)
date.toDateString(); // Tue May 12 2020
date.toTimeString(); // 18:50:21 GMT-0500 (Central Daylight Time)
date[Symbol.toPrimitive]("string"); // Tue May 12 2020 18:50:21 GMT-0500 (Central Daylight Time)

date.toISOString(); // 2020-05-12T23:50:21.817Z
date.toJSON(); // 2020-05-12T23:50:21.817Z

date.toUTCString(); // Tue, 12 May 2020 23:50:21 GMT

date.toLocaleString(); // 5/12/2020, 6:50:21 PM
date.toLocaleDateString(); // 5/12/2020
date.toLocaleTimeString(); // 6:50:21 PM

Datum, Monat, Jahr oder Zeit abrufen

const date = new Date("2000-01-17T16:45:30");
const [month, day, year] = [
  date.getMonth(),
  date.getDate(),
  date.getFullYear(),
];
// [0, 17, 2000] as month are 0-indexed
const [hour, minutes, seconds] = [
  date.getHours(),
  date.getMinutes(),
  date.getSeconds(),
];
// [16, 45, 30]

Interpretation zweistelliger Jahre

let date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date = new Date(22, 1); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)
date = new Date("2/1/22"); // Tue Feb 01 2022 00:00:00 GMT+0000 (GMT)

// Legacy method; always interprets two-digit year values as relative to 1900
date.setYear(98);
date.toString(); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date.setYear(22);
date.toString(); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)

setFullYear/getFullYear bevorzugen

// Preferred method; never interprets any value as being a relative offset,
// but instead uses the year value as-is
date.setFullYear(98);
date.getFullYear(); // 98 (not 1998)
date.setFullYear(22);
date.getFullYear(); // 22 (not 1922, not 2022)

Verstrichene Zeit berechnen (Date.now)

// Using Date objects
const start = Date.now();

// The event to time goes here:
doSomethingForALongTime();

const end = Date.now();
const elapsed = end - start; // elapsed time in milliseconds

Verstrichene Zeit berechnen (getTime)

// Using built-in methods
const start = new Date();

// The event to time goes here:
doSomethingForALongTime();
const end = new Date();
const elapsed = end.getTime() - start.getTime(); // elapsed time in milliseconds

Funktion testen und Rückgabewert erhalten

// To test a function and get back its return
function printElapsedTime(testFn) {
  const startTime = Date.now();
  const result = testFn();
  const endTime = Date.now();

  console.log(`Elapsed time: ${String(endTime - startTime)} milliseconds`);
  return result;
}

const yourFunctionReturn = printElapsedTime(yourFunction);

Anzahl der Sekunden seit der ECMAScript-Epoch

const seconds = Math.floor(Date.now() / 1000);

Grenzen des darstellbaren Timestamps

console.log(new Date(8.64e15).toString()); // "Sat Sep 13 275760 00:00:00 GMT+0000 (Coordinated Universal Time)"
console.log(new Date(8.64e15 + 1).toString()); // "Invalid Date"

Verhalten bei Sommerzeit-Übergängen

// Assume America/New_York local time zone
// 2024-03-10 02:30 is within the spring-forward transition and does not exist
// 01:59 (UTC-5) jumps to 03:00 (UTC-4), so 02:30 moves forward by one hour
console.log(new Date(2024, 2, 10, 2, 30).toString());
// Sun Mar 10 2024 03:30:00 GMT-0400 (Eastern Daylight Time)

// 2024-11-03 01:30 is within the fall-back transition and exists twice
// 01:59 (UTC-4) jumps to 01:00 (UTC-5), so the earlier 01:30 (UTC-4) is chosen
console.log(new Date(2024, 10, 3, 1, 30).toString());
// Sun Nov 03 2024 01:30:00 GMT-0400 (Eastern Daylight Time)

// Wichtig · Fallstricke

Häufige Fallstricke:

0-basierter Monat: new Date(2024, 0, 1) ist der 1. Januar, nicht der 1. Februar.
String-Parsing: Das Verhalten von new Date(string) ist browser-abhängig. ISO-8601-Strings ('YYYY-MM-DD') gelten als UTC, während 'YYYY/MM/DD' als lokal interpretiert werden kann. Explizites Parsen oder eine Bibliothek sind sicherer.
Mutabilität: Date-Objekte sind veränderlich; Setter wie setMonth() ändern das Objekt in-place. Für unveränderliche Datumswerte eine Kopie erstellen: new Date(original.getTime()).
Zeitzonenfalle: Getter ohne UTC-Präfix (getHours()) liefern Werte in der lokalen Systemzeit — auf Servern (Node.js) kann diese Zeitzone von der des Clients abweichen.
Zukunft: Die Temporal-API (TC39 Stage 3) soll Date langfristig ablösen und bietet unveränderliche Objekte mit vollständiger Zeitzonen-Unterstützung.

Siehe auch

Date.now() Date.parse() Date.prototype.toISOString() Date.prototype.toLocaleDateString() Intl.DateTimeFormat Date.prototype.getTime() Date.prototype.setFullYear()

← Vorheriger Eintrag DataView Nächster Eintrag → decodeURI()