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

Signatur

Date.prototype.setUTCFullYear(yearValue, monthValue, dateValue)

Beschreibung

setUTCFullYear() ändert das Jahr eines Date-Objekts nach koordinierter Weltzeit (UTC). Optional lassen sich im selben Aufruf auch Monat und Tag setzen. Die lokale Zeitzone und die Sommerzeit spielen dabei keine Rolle. Das Objekt wird direkt verändert (mutiert). Zurückgegeben wird der neue Zeitstempel in Millisekunden seit dem 1. Januar 1970, 00:00:00 UTC.

Die Methode eignet sich überall dort, wo Datumswerte unabhängig von der Zeitzone verarbeitet werden: Server-Logik, Speicherung in Datenbanken, API-Zeitstempel im ISO-Format oder Berechnungen, die auf jedem Client dasselbe Ergebnis liefern sollen. Für Berechnungen in der lokalen Zeitzone gibt es das Gegenstück setFullYear().

Liegen Werte außerhalb ihres Bereichs, rechnet die Methode sie automatisch um: monthValue = 12 ergibt Januar des Folgejahres, dateValue = 0 den letzten Tag des Vormonats. Werden monthValue oder dateValue weggelassen, übernimmt die Methode die Werte aus getUTCMonth() und getUTCDate().

Anders als die übrigen Setter funktioniert setUTCFullYear() auch bei einem ungültigen Datum (NaN). In diesem Fall geht die Methode vom 1. Januar 1970, 00:00:00 UTC aus und setzt das Jahr darauf.

Parameter

Name	Typ	Default	Beschreibung
$yearValue Pflicht	number		Das Jahr als volle Zahl, z. B. `2024`. Auch negative Werte und Jahre unter 100 werden wörtlich übernommen, anders als beim `Date`-Konstruktor.
$monthValue	number	getUTCMonth()	Monat von `0` (Januar) bis `11` (Dezember). Werte außerhalb dieses Bereichs werden auf die Nachbarjahre umgerechnet.
$dateValue	number	getUTCDate()	Tag im Monat von `1` bis `31`. Wird nur berücksichtigt, wenn auch `monthValue` angegeben ist. `0` ergibt den letzten Tag des Vormonats.

Rückgabewert

Typ

number

Beschreibung

Der neue Zeitstempel in Millisekunden seit der Unix-Epoche (UTC). Das Ergebnis ist NaN, wenn ein Argument NaN ist oder das Datum außerhalb des gültigen Bereichs liegt (±8,64·10¹⁵ ms). Das Objekt wird dann ungültig.

Beispiele

Jahr nach UTC ändern

const d = new Date('2023-06-15T12:00:00Z');
const ts = d.setUTCFullYear(2030);

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

2030-06-15T12:00:00.000Z 1907668800000

Jahr, Monat und Tag in einem Aufruf setzen

const d = new Date('2024-01-01T08:30:00Z');
d.setUTCFullYear(2025, 11, 24); // Monat 11 = Dezember

console.log(d.toISOString());

2025-12-24T08:30:00.000Z

Ablaufdatum berechnen, ohne das Original zu verändern

const addYearsUTC = (date, years) => {
  const copy = new Date(date.getTime()); // Kopie statt Mutation
  copy.setUTCFullYear(copy.getUTCFullYear() + years);
  return copy;
};

const start = new Date('2024-03-10T00:00:00Z');
const ablauf = addYearsUTC(start, 2);

console.log(start.toISOString());
console.log(ablauf.toISOString());

2024-03-10T00:00:00.000Z 2026-03-10T00:00:00.000Z

Schaltjahr-Überlauf am 29. Februar

const d = new Date('2024-02-29T00:00:00Z');
d.setUTCFullYear(2025); // 2025 hat keinen 29. Februar

console.log(d.toISOString());

// Letzter Tag im Februar 2025 über dateValue = 0
const ende = new Date(0);
ende.setUTCFullYear(2025, 2, 0);
console.log(ende.toISOString().slice(0, 10));

2025-03-01T00:00:00.000Z 2025-02-28

// Wichtig · Fallstricke

Mutation: Die Methode verändert das bestehende Objekt. Wer das Original behalten will, arbeitet vorher mit einer Kopie (new Date(d.getTime())).
Schaltjahre: Wird vom 29. Februar aus ein Jahr ohne Schalttag gesetzt, springt das Datum auf den 1. März. Soll stattdessen auf den Monatsletzten gekürzt werden, muss man das selbst prüfen.
Monat ab 0: monthValue zählt ab 0. Mit 12 landet man im Januar des Folgejahres.
UTC oder lokal: setUTCFullYear() und setFullYear() können in der Nähe von Mitternacht oder Jahreswechseln zu verschiedenen Ergebnissen führen, wenn die lokale Zeitzone von UTC abweicht. Mischen Sie UTC- und lokale Getter/Setter nicht.
Zweistellige Jahre: setUTCFullYear(99) setzt wirklich das Jahr 99 n. Chr. und nicht 1999. Nur der Konstruktor und das veraltete setYear() behandeln solche Werte anders.
Kompatibilität: Wird in allen Browsern und in Node.js unterstützt. Für neuen Code, der viel mit Zeitzonen arbeitet, lohnt sich ein Blick auf die kommende Temporal-API.

Siehe auch

Date.prototype.getUTCFullYear() Date.prototype.setFullYear() Date.prototype.setUTCMonth() Date.prototype.setUTCDate() Date.UTC() Date.prototype.toISOString() Date