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

Signatur

Date.prototype.setUTCSeconds(secondsValue[, msValue])

Beschreibung

setUTCSeconds() ändert den Sekundenanteil eines Date-Objekts nach koordinierter Weltzeit (UTC). Optional lassen sich die Millisekunden gleich mitsetzen. Die Methode verändert das Objekt direkt (sie mutiert es) und gibt den neuen Zeitstempel zurück, also die Millisekunden seit dem 1. Januar 1970, 00:00:00 UTC.

Anders als setSeconds() arbeitet setUTCSeconds() unabhängig von der lokalen Zeitzone des Systems. Da Zeitzonen-Verschiebungen bei Sekunden praktisch immer ganze Minuten betragen, ist das Ergebnis meist gleich. Die UTC-Variante passt aber besser, wenn der ganze Code auf UTC-Methoden ausgelegt ist, z. B. bei Server-Logs, Zeitstempeln für APIs oder beim Runden auf volle Minuten.

Werte außerhalb des normalen Bereichs werden übertragen: setUTCSeconds(75) ergibt die nächste Minute plus 15 Sekunden, setUTCSeconds(-1) die letzte Sekunde der vorherigen Minute. Das ist praktisch für Zeitrechnungen, weil Minuten, Stunden und Tage automatisch angepasst werden.

Parameter

Name	Typ	Default	Beschreibung
$secondsValue Pflicht	number		Ganze Zahl für die Sekunden, normalerweise zwischen `0` und `59`. Andere Werte werden auf Minuten, Stunden usw. übertragen. Nachkommastellen werden abgeschnitten.
$msValue	number	Wert von getUTCMilliseconds()	Optional: ganze Zahl für die Millisekunden, normalerweise `0` bis `999`. Fehlt der Wert, bleiben die aktuellen Millisekunden erhalten.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden seit der Unix-Epoche. NaN, wenn das Datum ungültig ist oder ein Argument NaN ergibt. Das Objekt selbst wird ebenfalls verändert.

Beispiele

Sekunden und Millisekunden setzen

const d = new Date('2024-03-15T10:20:30.456Z');
const ts = d.setUTCSeconds(5, 0);

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

2024-03-15T10:20:05.000Z 1710498005000

Auf volle Minute abrunden (z. B. für Log-Gruppierung)

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

const event = new Date('2024-06-01T08:45:59.999Z');
console.log(floorToMinute(event).toISOString());
console.log(event.toISOString()); // unverändert

2024-06-01T08:45:00.000Z 2024-06-01T08:45:59.999Z

Übertrag: Sekunden addieren über Minutengrenzen hinweg

const addSeconds = (date, sec) => {
  const copy = new Date(date);
  copy.setUTCSeconds(copy.getUTCSeconds() + sec);
  return copy;
};

const start = new Date('2024-12-31T23:59:30Z');
console.log(addSeconds(start, 45).toISOString());
console.log(addSeconds(start, -90).toISOString());

2025-01-01T00:00:15.000Z 2024-12-31T23:58:00.000Z

Ungültige Eingaben ergeben NaN

const d = new Date('2024-01-01T00:00:00Z');
console.log(d.setUTCSeconds('abc'));
console.log(d.getTime());

const invalid = new Date('kein Datum');
console.log(invalid.setUTCSeconds(10));

NaN NaN NaN

// Wichtig · Fallstricke

Verändert das Objekt direkt: Das Date-Objekt wird geändert. Wird ein Datum an mehreren Stellen genutzt, vorher mit new Date(original) kopieren.
Rückgabewert ist kein Date: Zurück kommt ein Zeitstempel als Zahl. Verkettungen wie d.setUTCSeconds(0).toISOString() werfen deshalb einen TypeError.
NaN macht das Datum ungültig: Ein ungültiges Argument setzt den internen Zeitwert auf NaN, danach ist das Datum „Invalid Date“. Auf einem ungültigen Datum setzt die Methode keinen gültigen Wert mehr.
Schaltsekunden werden von Date nicht berücksichtigt. Der Wert 60 wird einfach in die nächste Minute übertragen.
Unterstützt von allen Browsern und Node.js. Für neuen Code mit Zeitzonen-Logik lohnt sich die moderne Temporal-API, sobald die Zielumgebung sie unterstützt.

Siehe auch

Date.prototype.getUTCSeconds() Date.prototype.setSeconds() Date.prototype.setUTCMinutes() Date.prototype.setUTCMilliseconds() Date.prototype.toISOString() Date