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

Signatur

Date.prototype.setUTCDate(dateValue)

Beschreibung

setUTCDate() ändert den Tag des Monats (1–31) eines bestehenden Date-Objekts. Grundlage ist die koordinierte Weltzeit (UTC), nicht die lokale Zeitzone. Jahr, Monat und Uhrzeit (in UTC) bleiben unverändert. Das Objekt wird direkt verändert, es entsteht keine Kopie.

Werte außerhalb des normalen Bereichs werden automatisch umgerechnet: 0 steht für den letzten Tag des Vormonats, 32 im Januar für den 1. Februar, negative Werte zählen rückwärts in die Vormonate. So lassen sich Datumsberechnungen wie „+7 Tage“ oder „letzter Tag des Monats“ ohne eigene Monatslogik umsetzen.

Die Methode eignet sich vor allem für serverseitigen Code, Datenbank-Zeitstempel, APIs und alle Fälle, in denen Berechnungen unabhängig von Zeitzone und Sommerzeit laufen sollen. Wenn sich das Datum auf die lokale Zeit des Nutzers beziehen soll, nimmst du stattdessen setDate().

Parameter

Name	Typ	Default	Beschreibung
$dateValue Pflicht	number		Ganzzahl für den Tag des Monats (normal 1–31). Werte außerhalb dieses Bereichs verschieben Monat bzw. Jahr entsprechend. Nachkommastellen werden abgeschnitten, `NaN` macht das Datum ungültig.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden seit dem 1. Januar 1970 00:00:00 UTC. Ist das Ergebnis ungültig, wird NaN zurückgegeben und das Datum ist danach ein „Invalid Date“.

Beispiele

Tag des Monats in UTC setzen

const d = new Date('2024-03-10T12:00:00Z');
d.setUTCDate(25);
console.log(d.toISOString());

2024-03-25T12:00:00.000Z

Tage zeitzonensicher addieren

const addUtcDays = (date, days) => {
  const copy = new Date(date); // Original nicht verändern
  copy.setUTCDate(copy.getUTCDate() + days);
  return copy;
};

const start = new Date('2024-01-28T00:00:00Z');
console.log(addUtcDays(start, 7).toISOString());
console.log(addUtcDays(start, -30).toISOString());

2024-02-04T00:00:00.000Z 2023-12-29T00:00:00.000Z

Letzten Tag eines Monats ermitteln

const lastDayOfMonthUTC = (year, month) => {
  // month: 0 = Januar; Tag 0 des Folgemonats = letzter Tag des Monats
  const d = new Date(Date.UTC(year, month + 1, 1));
  d.setUTCDate(0);
  return d.getUTCDate();
};

console.log(lastDayOfMonthUTC(2024, 1)); // Februar 2024 (Schaltjahr)
console.log(lastDayOfMonthUTC(2023, 1));

29 28

Rückgabewert und ungültige Eingaben

const d = new Date('2024-05-01T00:00:00Z');
const ts = d.setUTCDate(15);
console.log(ts);
console.log(ts === d.getTime());

console.log(d.setUTCDate(NaN));
console.log(String(d));

1715731200000 true NaN Invalid Date

// Wichtig · Fallstricke

Verändert das Objekt direkt: Wenn das Original erhalten bleiben soll, arbeite auf einer Kopie (new Date(date)). Das ist besonders wichtig bei const-Variablen, denn const schützt nur die Bindung und nicht das Objekt.
UTC oder lokal: In Zeitzonen mit Versatz zu UTC kann der UTC-Tag vom lokalen Tag abweichen. Beispiel: In Deutschland ist 2024-03-10T23:30:00Z lokal schon der 11. Mische setUTCDate() daher nicht mit getDate().
Überlauf: setUTCDate(31) im April ergibt den 1. Mai. Wer vom 31. aus Monate addiert und danach den Tag setzt, sollte die Reihenfolge der Aufrufe bewusst wählen.
Bei einem ungültigen Datum (Invalid Date) bleibt das Ergebnis NaN, egal welcher Wert übergeben wird.
Für neuen Code lohnt sich ein Blick auf die Temporal-API (bisher nur in wenigen Umgebungen verfügbar). Sie arbeitet mit unveränderlichen Werten.
Kompatibilität: Die Methode wird von allen Browsern und von Node.js unterstützt.

Siehe auch

Date.prototype.getUTCDate() Date.prototype.setDate() Date.prototype.setUTCMonth() Date.prototype.setUTCFullYear() Date.UTC() Date