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

Signatur

Date.prototype.setTime(timeValue)

Beschreibung

Die Methode setTime() überschreibt den kompletten Zeitpunkt eines bestehenden Date-Objekts auf einmal. Übergeben wird ein Zeitstempel in Millisekunden seit der Epoche (Mitternacht zu Beginn des 1. Januar 1970, UTC), also genau der Wert, den getTime(), valueOf() oder Date.now() liefern.

Da der Zeitstempel immer in UTC angegeben wird, spielt die lokale Zeitzone beim Setzen keine Rolle. Das macht setTime() ideal, um ein Datum von einem anderen Date-Objekt zu übernehmen, Zeitstempel aus einer Datenbank oder API einzulesen oder mit Millisekunden-Arithmetik zu rechnen (z. B. „plus 30 Minuten“).

Die Methode verändert das Objekt direkt (sie mutiert es) und gibt den neuen Zeitstempel zurück. Ist der übergebene Wert keine gültige Zahl oder liegt er außerhalb des zulässigen Bereichs von ±8,64 × 1015 ms (±100 Millionen Tage), wird das Datum ungültig und der Rückgabewert ist NaN.

Parameter

Name	Typ	Default	Beschreibung
$timeValue Pflicht	number		Zeitstempel in Millisekunden seit dem 1. Januar 1970, 00:00:00 UTC. Wird mit `Number()` umgewandelt und auf eine Ganzzahl gekürzt (Nachkommastellen werden abgeschnitten). Negative Werte bezeichnen Zeitpunkte vor 1970.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden (identisch mit getTime() nach dem Aufruf) oder NaN, wenn der Wert ungültig bzw. außerhalb des darstellbaren Bereichs liegt.

Beispiele

Datum aus einem Zeitstempel setzen

const datum = new Date();
const rueckgabe = datum.setTime(0);

console.log(rueckgabe);
console.log(datum.toISOString());

0 1970-01-01T00:00:00.000Z

Datum eines anderen Date-Objekts übernehmen (ohne neue Instanz)

const start = new Date('2024-03-15T09:30:00Z');
const kopie = new Date();

// kopie zeigt nun auf denselben Zeitpunkt, bleibt aber ein eigenes Objekt
kopie.setTime(start.getTime());

console.log(kopie.toISOString());
console.log(kopie === start);

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

Ablaufzeit einer Sitzung verlängern

const MINUTE = 60 * 1000;
const ablauf = new Date('2024-06-01T12:00:00Z');

// Bei jeder Nutzeraktion 30 Minuten ab jetzt (hier: fester Zeitpunkt)
const verlaengern = (datum, basis) => datum.setTime(basis.getTime() + 30 * MINUTE);

verlaengern(ablauf, new Date('2024-06-01T12:10:00Z'));
console.log(ablauf.toISOString());

2024-06-01T12:40:00.000Z

Ungültige Werte erkennen

const d = new Date();

console.log(d.setTime('abc'));
console.log(Number.isNaN(d.getTime()));
console.log(d.setTime(8.64e15 + 1));
console.log(d.setTime(1718000000000.9)); // Nachkommastellen werden abgeschnitten

NaN true NaN 1718000000000

// Wichtig · Fallstricke

Mutation: setTime() verändert das bestehende Objekt. Wird dasselbe Date an mehreren Stellen genutzt (z. B. als Standardwert oder in einem State-Objekt), sind alle Referenzen betroffen. Für unveränderliche Kopien lieber new Date(zeitstempel) verwenden.
Millisekunden, nicht Sekunden: Unix-Zeitstempel aus Backends (PHP time(), JWT exp) sind oft in Sekunden angegeben und müssen mit 1000 multipliziert werden, sonst landet man im Januar 1970.
Keine Zeitzonen-Logik: Der Wert ist immer UTC-basiert. Zeitzonen-Effekte treten erst bei der Ausgabe auf (toString(), getHours()). Beim Addieren fester Millisekunden-Beträge über Sommerzeitumstellungen hinweg verschiebt sich die lokale Uhrzeit um eine Stunde – für „gleiche Uhrzeit am nächsten Tag“ besser setDate() nutzen.
Ungültige Eingaben: Strings werden per Number() umgewandelt; 'abc', undefined oder Werte jenseits von ±8,64e15 ergeben ein Invalid Date. Ohne Argument wird der Wert zu NaN.
Für moderne Datumsarithmetik ist die Temporal-API in Vorbereitung; setTime() wird von allen Browsern und Node.js unterstützt.

Siehe auch

Date.prototype.getTime() Date.now() Date.prototype.valueOf() Date.prototype.setUTCMilliseconds() Date.prototype.setDate() Date