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

Signatur

Date.prototype.setUTCMonth(monthValue, dateValue)

Beschreibung

setUTCMonth() ändert den Monat eines vorhandenen Date-Objekts nach UTC. Die lokale Zeitzone des Systems spielt dabei keine Rolle. Optional lässt sich im selben Aufruf auch der Tag des Monats setzen. Jahr, Uhrzeit und Millisekunden bleiben unverändert. Die Methode verändert das Objekt direkt (mutierend) und gibt den neuen Zeitstempel zurück.

Die Methode ist sinnvoll, wenn Sie mit zeitzonenunabhängigen Daten arbeiten, zum Beispiel mit Zeitstempeln vom Server, ISO-8601-Zeichenketten mit Z, Abrechnungszeiträumen oder Berichten, die auf allen Rechnern gleich aussehen müssen. Das lokale Gegenstück heißt setMonth().

Monate werden ab 0 gezählt: 0 ist Januar, 11 ist Dezember. Werte außerhalb dieses Bereichs werden umgerechnet. 12 ergibt Januar des Folgejahres, -1 Dezember des Vorjahres. Gleiches gilt für den Tag: Ein Tag, den es im Zielmonat nicht gibt, wird in den nächsten Monat übertragen. So wird aus dem 31. Januar mit setUTCMonth(1) nicht der letzte Februartag, sondern ein Tag Anfang März.

Parameter

Name	Typ	Default	Beschreibung
$monthValue Pflicht	number		Monat als ganze Zahl ab 0 (`0` = Januar … `11` = Dezember). Werte außerhalb des Bereichs werden in Jahre umgerechnet. Nachkommastellen werden abgeschnitten.
$dateValue	number	Wert von getUTCDate()	Tag des Monats (`1`–`31`). Fehlt er, bleibt der bisherige Tag erhalten. `0` ergibt den letzten Tag des Vormonats, zu große Werte werden in den Folgemonat übertragen.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden seit dem 1. Januar 1970, 00:00:00 UTC. Er entspricht dem neuen Wert von getTime(). Ist das Datum danach ungültig (oder war es schon vorher), wird NaN zurückgegeben.

Beispiele

Monat nach UTC setzen und Rückgabewert nutzen

const termin = new Date(Date.UTC(2024, 0, 15, 12, 0, 0));

// Auf Juni setzen (Monat 5, Zählung ab 0)
const zeitstempel = termin.setUTCMonth(5);

console.log(termin.toISOString());
console.log(zeitstempel);
console.log(zeitstempel === termin.getTime());

2024-06-15T12:00:00.000Z 1718452800000 true

Monat und Tag gleichzeitig setzen, Werte außerhalb des Bereichs

const d = new Date('2024-03-10T08:30:00Z');

// Letzter Tag des Jahres
d.setUTCMonth(11, 31);
console.log(d.toISOString());

// Monat 12 ergibt Januar des Folgejahres
d.setUTCMonth(12, 1);
console.log(d.toISOString());

// Monat -1 ergibt Dezember des Vorjahres
d.setUTCMonth(-1);
console.log(d.toISOString());

2024-12-31T08:30:00.000Z 2025-01-01T08:30:00.000Z 2024-12-01T08:30:00.000Z

Fallstrick: Übertrag am Monatsende

const ende = new Date('2023-01-31T00:00:00Z');

// Gewünscht ist Februar – den 31. Februar gibt es aber nicht
ende.setUTCMonth(1);
console.log(ende.toISOString());

2023-03-03T00:00:00.000Z

Monate sicher addieren, der Tag wird auf das Monatsende begrenzt

const addUTCMonths = (datum, anzahl) => {
  const ergebnis = new Date(datum.getTime()); // Original nicht verändern
  const tag = ergebnis.getUTCDate();
  ergebnis.setUTCDate(1); // Übertrag vermeiden
  ergebnis.setUTCMonth(ergebnis.getUTCMonth() + anzahl);
  // Letzter Tag des Zielmonats: Tag 0 des Folgemonats
  const letzterTag = new Date(Date.UTC(
    ergebnis.getUTCFullYear(), ergebnis.getUTCMonth() + 1, 0
  )).getUTCDate();
  ergebnis.setUTCDate(Math.min(tag, letzterTag));
  return ergebnis;
};

const start = new Date('2024-01-31T00:00:00Z');
console.log(addUTCMonths(start, 1).toISOString());
console.log(addUTCMonths(start, 13).toISOString());
console.log(start.toISOString()); // unverändert

2024-02-29T00:00:00.000Z 2025-02-28T00:00:00.000Z 2024-01-31T00:00:00.000Z

// Wichtig · Fallstricke

Zählung ab 0: Mit setUTCMonth(3) wird April gesetzt, nicht März. Das ist einer der häufigsten Fehler bei Datumsangaben.
Übertrag am Monatsende: Ist der Tag im Zielmonat zu groß (z. B. der 31. bei einem Monat mit 30 Tagen), springt das Datum in den nächsten Monat. Zum Addieren von Monaten sollten Sie deshalb erst setUTCDate(1) aufrufen und den Tag danach begrenzen (siehe Beispiel).
Verändert das Objekt: Die Methode ändert das Objekt selbst. Wenn Sie das Original behalten wollen, kopieren Sie es vorher mit new Date(d.getTime()).
UTC oder lokale Zeit: setUTCMonth() und setMonth() können sich unterscheiden, wenn sich lokales und UTC-Datum zu diesem Zeitpunkt unterscheiden (etwa kurz vor oder nach Mitternacht). Mischen Sie UTC- und lokale Methoden nicht.
Ungültige Werte: Ist ein Argument NaN (z. B. undefined oder eine Zeichenkette, die keine Zahl ist), wird das Datum ungültig und die Methode gibt NaN zurück. Ein Datum, das schon ungültig ist, wird durch setUTCMonth() nicht wieder gültig.
Die Methode wird von allen Browsern und von Node.js unterstützt. Für neue Projekte ist die Temporal-API (Temporal.PlainDate.prototype.add()) eine Alternative ohne diese Fallstricke, sobald sie verfügbar ist.

Siehe auch

Date.prototype.getUTCMonth() Date.prototype.setMonth() Date.prototype.getMonth() Date.prototype.setUTCDate() Date.prototype.setUTCHours()