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

Signatur

Date.prototype.setMilliseconds(millisecondsValue)

Beschreibung

setMilliseconds() ändert den Millisekundenanteil (0–999) eines bestehenden Date-Objekts nach lokaler Zeit. Alle anderen Bestandteile wie Jahr, Monat, Tag, Stunde, Minute und Sekunde bleiben erhalten, solange der übergebene Wert im gültigen Bereich liegt.

Die Methode verändert das Objekt direkt und gibt eine neue Instanz nicht zurück. Der Rückgabewert ist der neue interne Zeitstempel in Millisekunden seit dem 1. Januar 1970 UTC, also derselbe Wert, den anschließend getTime() liefert.

Liegt der Wert außerhalb von 0–999, rechnet JavaScript automatisch um: 1500 erhöht die Sekunden um 1 und setzt die Millisekunden auf 500, -1 springt auf 999 Millisekunden der vorherigen Sekunde. Das lässt sich gezielt für Zeitrechnungen nutzen, etwa um zu einem Zeitpunkt eine beliebige Anzahl Millisekunden zu addieren.

Typische Einsatzfälle sind das Abschneiden auf volle Sekunden mit setMilliseconds(0), zum Beispiel für Vergleiche, Cache-Schlüssel oder die Ausgabe ohne Sekundenbruchteile, sowie das Normalisieren von Zeitstempeln aus verschiedenen Quellen.

Parameter

Name	Typ	Default	Beschreibung
$millisecondsValue Pflicht	number		Ganzzahl, die üblicherweise zwischen `0` und `999` liegt. Größere oder negative Werte werden in die Sekunden (und ggf. weitere Felder) übertragen. Nachkommastellen werden abgeschnitten. `NaN` macht das Datum ungültig.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden seit der Unix-Epoche (UTC). Ergibt der Parameter NaN oder ist das Datum bereits ungültig, wird NaN zurückgegeben und das Datum ist bzw. bleibt ungültig (Invalid Date).

Beispiele

Millisekunden gezielt setzen

const d = new Date(2024, 0, 15, 10, 30, 45, 0);
d.setMilliseconds(250);
console.log(d.getSeconds(), d.getMilliseconds());

45 250

Auf volle Sekunde abschneiden (ohne Original zu verändern)

const aufSekundeKuerzen = (date) => {
  const kopie = new Date(date); // Kopie, da setMilliseconds mutiert
  kopie.setMilliseconds(0);
  return kopie;
};

const a = new Date(2024, 5, 1, 12, 0, 0, 123);
const b = new Date(2024, 5, 1, 12, 0, 0, 987);
console.log(a.getTime() === b.getTime());
console.log(aufSekundeKuerzen(a).getTime() === aufSekundeKuerzen(b).getTime());
console.log(a.getMilliseconds()); // Original unverändert

false true 123

Überlauf und negative Werte

const d = new Date(2024, 0, 15, 10, 30, 45, 0);

d.setMilliseconds(1500); // +1 Sekunde, 500 ms
console.log(d.getSeconds(), d.getMilliseconds());

d.setMilliseconds(-1); // 999 ms der vorherigen Sekunde
console.log(d.getSeconds(), d.getMilliseconds());

46 500 45 999

Rückgabewert als Zeitstempel nutzen

const d = new Date(2024, 0, 15, 10, 30, 45, 999);
const ts = d.setMilliseconds(0);
console.log(ts === d.getTime());
console.log(typeof ts);

true number

// Wichtig · Fallstricke

Mutation: Die Methode verändert das bestehende Objekt. Wenn das Original erhalten bleiben soll, vorher mit new Date(date) kopieren. Das gilt besonders für Datumswerte, die als Argument übergeben oder im Zustand von React, Vue usw. gespeichert sind.
Rückgabewert ist kein Date: d.setMilliseconds(0).getSeconds() wirft einen TypeError, weil eine Zahl zurückgegeben wird.
Ungültige Eingaben: setMilliseconds(NaN) oder nicht umwandelbare Werte wie "abc" machen das Datum dauerhaft ungültig. Ein bereits ungültiges Datum wird durch setMilliseconds() nicht wieder gültig.
Nachkommastellen werden abgeschnitten, zum Beispiel wird 12.9 zu 12. Date rechnet nicht genauer als auf ganze Millisekunden. Für hochauflösende Messungen besser performance.now() verwenden.
Lokale Zeit und UTC unterscheiden sich bei Millisekunden praktisch nie, weil Zeitzonen-Verschiebungen in ganzen Minuten angegeben werden. Für Code, der konsequent mit UTC arbeitet, ist trotzdem setUTCMilliseconds() die klarere Wahl.
Wird in allen Browsern und in Node.js unterstützt. Für neue Projekte lohnt sich ein Blick auf die Temporal-API, die mit unveränderlichen Objekten arbeitet (bisher nur in einem Teil der Umgebungen verfügbar).

Siehe auch

Date.prototype.getMilliseconds() Date.prototype.setUTCMilliseconds() Date.prototype.setSeconds() Date.prototype.setTime() Date.prototype.getTime() Date