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

Signatur

Date.prototype.setUTCMilliseconds(millisecondsValue)

Beschreibung

Die Methode setUTCMilliseconds() ändert den Millisekundenanteil eines Date-Objekts nach koordinierter Weltzeit (UTC). Das Objekt wird dabei direkt verändert. Zurückgegeben wird der neue interne Zeitstempel, also die Millisekunden seit dem 1. Januar 1970, 00:00:00 UTC.

Liegt der übergebene Wert außerhalb von 0–999, rechnet die Methode automatisch um: 1500 erhöht die Sekunden um 1 und setzt die Millisekunden auf 500, -1 geht eine Millisekunde in die vorherige Sekunde zurück. Dieses Überlaufverhalten eignet sich gut für Zeitberechnungen, zum Beispiel um eine feste Anzahl Millisekunden aufzuaddieren.

Weil Millisekunden in jeder Zeitzone gleich sind, ergibt setUTCMilliseconds() im Normalfall dasselbe wie setMilliseconds(). Ein Unterschied entsteht erst, wenn ein Überlauf eine Stunden- oder Tagesgrenze überschreitet und die lokale Zeitzone eine Sommerzeitumstellung hat. Für Code, der unabhängig von der Zeitzone arbeiten soll (Server, Protokolle, Zeitstempel für APIs), sind die UTC-Varianten deshalb die sichere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$millisecondsValue Pflicht	number		Ganzzahl für die Millisekunden, normalerweise zwischen `0` und `999`. Werte außerhalb dieses Bereichs laufen in die Sekunden (und größere Einheiten) über. Nachkommastellen werden abgeschnitten.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden seit der Unix-Epoche (UTC). Ist der Parameter NaN oder fehlt er, wird das Datum ungültig und die Methode gibt NaN zurück.

Beispiele

Millisekunden gezielt setzen

const d = new Date('2024-03-15T12:30:45.000Z');
const ts = d.setUTCMilliseconds(250);

console.log(d.toISOString());
console.log(ts);

2024-03-15T12:30:45.250Z 1710505845250

Überlauf: Werte größer als 999 und negative Werte

const d = new Date('2024-03-15T12:30:45.000Z');

d.setUTCMilliseconds(1500); // +1 Sekunde, 500 ms
console.log(d.toISOString());

d.setUTCMilliseconds(-1); // eine Millisekunde vor Sekunde 46
console.log(d.toISOString());

2024-03-15T12:30:46.500Z 2024-03-15T12:30:45.999Z

Zeitstempel auf volle Sekunden abrunden (z. B. für Cache-Schlüssel)

const truncateToSecond = (date) => {
  const copy = new Date(date); // Original nicht verändern
  copy.setUTCMilliseconds(0);
  return copy;
};

const now = new Date('2024-06-01T08:15:30.987Z');
console.log(truncateToSecond(now).toISOString());
console.log(now.toISOString()); // unverändert

2024-06-01T08:15:30.000Z 2024-06-01T08:15:30.987Z

Ungültige Eingabe erkennen

const d = new Date('2024-01-01T00:00:00Z');
const result = d.setUTCMilliseconds(Number('abc'));

console.log(result);
console.log(Number.isNaN(d.getTime()));

NaN true

// Wichtig · Fallstricke

Verändert das Objekt direkt: Das Date-Objekt wird in-place geändert. Wer das Original behalten will, legt vorher mit new Date(original) eine Kopie an.
Rückgabewert ist kein Date: Zurückgegeben wird eine Zahl (der Zeitstempel) und nicht das Objekt selbst. Aufrufe lassen sich also nicht verketten, wie etwa d.setUTCMilliseconds(0).toISOString(). Das führt zu einem TypeError.
NaN macht das Datum ungültig: Ein fehlendes Argument oder ein nicht-numerischer Wert setzt das Datum auf Invalid Date. Folgende Aufrufe wie toISOString() werfen dann einen RangeError.
Nachkommastellen werden abgeschnitten: setUTCMilliseconds(12.9) setzt 12 ms. Eine höhere Genauigkeit als Millisekunden gibt es bei Date nicht. Für Mikrosekunden eignen sich performance.now() oder künftig Temporal.
Kompatibilität: Die Methode wird von allen Browsern und von Node.js unterstützt.

Siehe auch

Date.prototype.getUTCMilliseconds() Date.prototype.setMilliseconds() Date.prototype.setUTCSeconds() Date.prototype.setTime() Date.prototype.toISOString() Date