WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Das UTC-Jahr eines Date-Objekts lesen und ändern

`getUTCFullYear()` liest das UTC-Jahr. `setUTCFullYear()` ändert dasselbe `Date`-Objekt und gibt den neuen Zeitstempel zurück. Ein ausgelassenes Argument ist nicht dasselbe wie `undefined`.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

date.getUTCFullYear()
date.setUTCFullYear(year)
date.setUTCFullYear(year, monthIndex)
date.setUTCFullYear(year, monthIndex, dayOfMonth)

getUTCFullYear() nimmt keine Argumente entgegen und liefert das Kalenderjahr in UTC als Ganzzahl, nicht als vierstellige Zeichenfolge. Bei einem ungültigen Datum liefert die Methode NaN. Dagegen verwenden getFullYear() und setFullYear() die lokale Zeitzone der Laufzeitumgebung. Rund um den Jahreswechsel kann derselbe Zeitpunkt in UTC und in der Ortszeit in unterschiedliche Jahre fallen.

setUTCFullYear(year, monthIndex, dayOfMonth) ändert das vorhandene Date-Objekt und gibt den neuen Zeitstempel in Millisekunden seit der Unix-Epoche zurück. Das Jahr ist erforderlich. Der optionale Monatsindex reicht von 0 (Januar) bis 11 (Dezember), der Tag des Monats beginnt bei 1. Wer einen Tag angibt, muss auch den Monat angeben. Ausgelassene Komponenten und die Uhrzeit stammen aus dem bisherigen UTC-Datum. Werte außerhalb des üblichen Kalenderbereichs werden normalisiert: Beim Wechsel in ein Nichtschaltjahr wird der 29. Februar zum 1. März.

Die Argumente werden in Zahlen umgewandelt. Explizites undefined ist kein Auslassen: Es wird zu NaN. Wird ein Argument zu NaN oder liegt der resultierende Zeitstempel außerhalb des Date-Wertebereichs, speichert die Methode NaN und gibt es zurück. War das Datum bereits ungültig, dient 1970-01-01T00:00:00.000Z als Ausgangspunkt. Ein gültiger Aufruf kann es daher wiederherstellen.

Anders als Date.UTC() addiert setUTCFullYear() bei Jahreszahlen von 0 bis 99 nicht 1900. Beide Prototypmethoden benötigen ein echtes Date-Objekt als this; ein Aufruf mit einem ungeeigneten this löst einen TypeError aus.

Beispiele

const date = new Date('2024-02-29T12:34:56.789Z');
console.log(date.getUTCFullYear());
console.log(date.setUTCFullYear(2023));
console.log(date.toISOString());
console.log(date.setUTCFullYear(2023, undefined));
console.log(date.getUTCFullYear());
date.setUTCFullYear(7);
console.log(date.toISOString());

Ergebnis

2024
1677674096789
2023-03-01T12:34:56.789Z
NaN
NaN
0007-01-01T00:00:00.000Z

Beim Wechsel auf 2023 wird der 29. Februar zum 1. März; die UTC-Uhrzeit bleibt gleich. Explizites `undefined` macht das Datum ungültig. Das Setzen des Jahres auf `7` stellt ein gültiges Datum wieder her: den 1. Januar des Jahres 7 um Mitternacht UTC.

Zugehörige Lektionen

  • JavaScript · Lektion 5 · Fortgeschritten · Version: 4

Quellen