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

Signatur

Date.prototype.setUTCHours(hoursValue, minutesValue, secondsValue, msValue)

Beschreibung

setUTCHours() ändert die Uhrzeit eines vorhandenen Date-Objekts direkt, also in place. Anders als setHours() werden die Werte als UTC ausgelegt, nicht in der lokalen Zeitzone des Systems. Das Ergebnis ist deshalb auf jedem Rechner gleich, egal welche Zeitzone oder Sommerzeitregel dort gilt.

Typische Einsätze sind das Normalisieren eines Datums auf Mitternacht UTC (setUTCHours(0, 0, 0, 0)), das Berechnen von Tagesgrenzen für Server-APIs und Datenbanken sowie das Festlegen einer Uhrzeit, die weltweit gleich gelten soll, z. B. für Wartungsfenster oder Deadlines.

Werte außerhalb des üblichen Bereichs werden übertragen: setUTCHours(25) springt auf 1 Uhr am nächsten Tag, setUTCHours(-1) auf 23 Uhr am Vortag. Lässt man die optionalen Parameter weg, bleiben die aktuellen UTC-Werte von getUTCMinutes(), getUTCSeconds() und getUTCMilliseconds() erhalten.

Parameter

Name	Typ	Default	Beschreibung
$hoursValue Pflicht	number		Stunde in UTC, normalerweise eine ganze Zahl von `0` bis `23`. Andere Werte werden in Tage übertragen.
$minutesValue	number	getUTCMinutes()	Minuten, normalerweise `0` bis `59`.
$secondsValue	number	getUTCSeconds()	Sekunden, normalerweise `0` bis `59`. Wer `secondsValue` angibt, muss auch `minutesValue` angeben.
$msValue	number	getUTCMilliseconds()	Millisekunden, normalerweise `0` bis `999`. Setzt voraus, dass auch Minuten und Sekunden angegeben sind.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden seit dem 1. Januar 1970 00:00:00 UTC. Ist ein Argument NaN (oder nicht in eine Zahl umwandelbar) oder war das Datum schon ungültig, wird NaN zurückgegeben und das Datum ist danach ungültig.

Beispiele

Uhrzeit in UTC setzen

const meeting = new Date('2024-03-15T08:30:00Z');
meeting.setUTCHours(14, 0);
console.log(meeting.toISOString());

2024-03-15T14:00:00.000Z

Datum auf Mitternacht UTC setzen (Tagesbeginn)

const startOfUTCDay = (date) => {
  const d = new Date(date); // Kopie, damit das Original erhalten bleibt
  d.setUTCHours(0, 0, 0, 0);
  return d;
};

const jetzt = new Date('2024-06-10T17:42:13.512Z');
console.log(startOfUTCDay(jetzt).toISOString());
console.log(jetzt.toISOString());

2024-06-10T00:00:00.000Z 2024-06-10T17:42:13.512Z

Übertrag auf den nächsten Tag und Rückgabewert

const d = new Date('2024-12-31T12:00:00Z');
const ts = d.setUTCHours(26); // 26 Uhr = 2 Uhr am Folgetag
console.log(d.toISOString());
console.log(ts === d.getTime());

2025-01-01T02:00:00.000Z true

Tagesende in UTC für eine API-Abfrage

const endOfUTCDay = (date) => {
  const d = new Date(date);
  d.setUTCHours(23, 59, 59, 999);
  return d;
};

const params = new URLSearchParams({
  bis: endOfUTCDay(new Date('2024-02-29T09:15:00Z')).toISOString()
});
console.log(params.toString());

bis=2024-02-29T23%3A59%3A59.999Z

// Wichtig · Fallstricke

Veränderung in place: Die Methode verändert das Objekt selbst. Wer das Original noch braucht, sollte vorher mit new Date(original) eine Kopie anlegen.
UTC oder lokale Zeit: setUTCHours() legt nicht fest, wie das Datum angezeigt wird. toString() und toLocaleString() zeigen es weiterhin in lokaler Zeit an. Zur Kontrolle eignet sich toISOString().
Der Tag kann sich verschieben: Bei Nutzern in Zonen wie UTC−5 kann „Mitternacht UTC“ lokal noch auf dem Vortag liegen. Für die Anzeige von Tagesgrenzen nimmt man daher meist setHours(), für Speicherung und Austausch setUTCHours().
Rückgabewert: Zurückgegeben wird eine Zahl (der Zeitstempel), nicht das Date-Objekt. Aufrufe lassen sich also nicht verketten.
Ungültige Eingaben: Bei NaN, undefined als ausdrücklich übergebenem Argument oder nicht umwandelbaren Strings wird das Datum zu Invalid Date.
Die Methode wird von allen Browsern und von Node.js unterstützt. Für modernen Umgang mit Zeitzonen lohnt sich ein Blick auf die kommende Temporal-API.

Siehe auch

Date.prototype.setHours() Date.prototype.setUTCMinutes() Date.prototype.setUTCDate() Date.prototype.toISOString() Date