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

Signatur

Date.prototype.valueOf()

Beschreibung

Die Methode valueOf() liefert den internen Zeitwert eines Date-Objekts als Zahl: die Millisekunden seit der Unix-Epoche (1. Januar 1970, Mitternacht UTC). Funktional ist sie identisch mit Date.prototype.getTime().

In der Regel ruft man valueOf() nicht selbst auf. JavaScript nutzt die Methode automatisch, wenn ein Date in einen Zahlenkontext umgewandelt wird, etwa bei der Subtraktion zweier Datumswerte (b - a), beim unären Plus (+date) oder bei Vergleichen mit < und >. Deshalb kann man mit Datumswerten direkt rechnen, zum Beispiel um Zeitdifferenzen zu bestimmen oder Listen zu sortieren.

Der Rückgabewert hängt nicht von der Zeitzone ab. Zwei Date-Objekte für denselben Zeitpunkt liefern immer dieselbe Zahl, egal welche lokale Zeitzone eingestellt ist. Bei einem ungültigen Datum (Invalid Date) ist das Ergebnis NaN.

Rückgabewert

Typ

number

Beschreibung

Die Millisekunden seit dem 1. Januar 1970, 00:00:00 UTC. Werte vor der Epoche sind negativ. Bei einem ungültigen Datum ist das Ergebnis NaN.

Beispiele

Zeitwert eines Datums auslesen

const epoche = new Date(Date.UTC(1970, 0, 1));
const jahrtausend = new Date('2000-01-01T00:00:00Z');

console.log(epoche.valueOf());
console.log(jahrtausend.valueOf());
console.log(jahrtausend.valueOf() === jahrtausend.getTime());

0 946684800000 true

Implizite Umwandlung: Dauer messen

const start = new Date('2024-03-01T08:00:00Z');
const ende = new Date('2024-03-01T09:30:00Z');

// Bei der Subtraktion wird valueOf() automatisch aufgerufen
const dauerMs = ende - start;
const minuten = dauerMs / 1000 / 60;

console.log(`Dauer: ${minuten} Minuten`);

Dauer: 90 Minuten

Termine chronologisch sortieren und vergleichen

const termine = [
  { titel: 'Review', datum: new Date('2024-06-12') },
  { titel: 'Kickoff', datum: new Date('2024-06-03') },
  { titel: 'Release', datum: new Date('2024-06-28') }
];

termine.sort((a, b) => a.datum.valueOf() - b.datum.valueOf());
console.log(termine.map(t => t.titel).join(' → '));

// Gleichheit: nicht mit ===, sondern über den Zeitwert
const a = new Date('2024-06-03');
const b = new Date('2024-06-03');
console.log(a === b, a.valueOf() === b.valueOf());

Kickoff → Review → Release false true

Ungültiges Datum erkennen

const eingabe = new Date('kein Datum');

if (Number.isNaN(eingabe.valueOf())) {
  console.log('Ungültige Datumsangabe');
}

Ungültige Datumsangabe

// Wichtig · Fallstricke

Gleichheit: === und == vergleichen bei zwei Date-Objekten die Referenzen, nicht die Zeitpunkte. Für Gleichheit also immer a.valueOf() === b.valueOf() oder getTime() verwenden. <, >, <= und >= funktionieren dagegen direkt, weil dabei valueOf() aufgerufen wird.
Der Operator +: Bei date + 1 oder date + '' wird das Datum zu einem String und nicht zu einer Zahl, weil Date über Symbol.toPrimitive den Hinweis "default" wie "string" behandelt. Für Arithmetik deshalb +date, date.valueOf() oder date.getTime() verwenden.
Einheit: Das Ergebnis ist in Millisekunden. Unix-Zeitstempel sind dagegen oft in Sekunden angegeben. Umrechnung: Math.floor(date.valueOf() / 1000).
Wertebereich: Gültig sind Werte bis ±8,64 × 10¹⁵ ms, also etwa ±273.790 Jahre um die Epoche. Außerhalb davon ist das Datum ungültig und das Ergebnis NaN.
Aktuelle Zeit: Date.now() liefert denselben Wert wie new Date().valueOf(), erzeugt aber kein Objekt.
Aufrufkontext: Wird die Methode auf einem Objekt aufgerufen, das kein Date ist, etwa Date.prototype.valueOf.call({}), wird ein TypeError ausgelöst.
Die Methode wird von allen Browsern und von Node.js unterstützt.

Siehe auch

Date.prototype.getTime() Date.now() Object.prototype.valueOf() Date.UTC() Date