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

Signatur

Date.prototype.getUTCFullYear()

Beschreibung

getUTCFullYear() liefert das Jahr des Zeitpunkts, den ein Date-Objekt repräsentiert, und zwar bezogen auf UTC statt auf die lokale Zeitzone der Laufzeitumgebung. Es wird immer das vollständige Jahr zurückgegeben (z. B. 2024, nicht 124 wie beim veralteten getYear()).

Die Methode ist dann die richtige Wahl, wenn Datumswerte zeitzonenunabhängig verarbeitet werden sollen – etwa beim Serialisieren, beim Gruppieren von Server-Logdaten, bei ISO-Zeitstempeln oder beim Vergleich von Daten, die aus unterschiedlichen Zeitzonen stammen. Für die Anzeige an Benutzer ist dagegen meist getFullYear() oder Intl.DateTimeFormat geeigneter.

Rund um den Jahreswechsel kann sich das UTC-Jahr vom lokalen Jahr unterscheiden: Am 31. Dezember um 23:30 Uhr in New York (UTC−5) ist in UTC bereits das neue Jahr angebrochen. Bei ungültigen Datumsobjekten liefert die Methode NaN.

Rückgabewert

Typ

number

Beschreibung

Das Jahr gemäß UTC als ganze Zahl (auch negativ für Jahre vor 1 v. Chr. bzw. Jahr 0 möglich). NaN, wenn das Datum ungültig ist.

Beispiele

UTC-Jahr eines festen Zeitpunkts auslesen

const release = new Date('2024-06-15T12:00:00Z');
console.log(release.getUTCFullYear());

2024

Unterschied zwischen lokalem Jahr und UTC-Jahr am Jahreswechsel

// 1. Januar 2025, 00:30 Uhr in UTC+2
const d = new Date('2025-01-01T00:30:00+02:00');

console.log('UTC-Jahr:', d.getUTCFullYear());
// Lokales Jahr hängt von der Zeitzone der Umgebung ab
console.log('Lokal (z. B. Berlin):', d.getFullYear());

UTC-Jahr: 2024 Lokal (z. B. Berlin): 2025

Log-Einträge zeitzonenunabhängig nach Jahr gruppieren

const logs = [
  { msg: 'Start', ts: '2023-12-31T23:59:00Z' },
  { msg: 'Update', ts: '2024-01-01T00:01:00Z' },
  { msg: 'Deploy', ts: '2024-03-10T08:00:00Z' }
];

const byYear = logs.reduce((acc, { msg, ts }) => {
  const year = new Date(ts).getUTCFullYear();
  (acc[year] ??= []).push(msg);
  return acc;
}, {});

console.log(byYear);

{ '2023': [ 'Start' ], '2024': [ 'Update', 'Deploy' ] }

Ungültiges Datum erkennen

const invalid = new Date('kein Datum');
const year = invalid.getUTCFullYear();

console.log(Number.isNaN(year) ? 'Ungültiges Datum' : year);

Ungültiges Datum

// Wichtig · Fallstricke

UTC vs. lokal: Am Jahreswechsel können getUTCFullYear() und getFullYear() unterschiedliche Werte liefern. Für Benutzeranzeigen lieber die lokale Variante oder Intl.DateTimeFormat verwenden.
Parsing-Falle: Reine Datumsstrings wie '2024-01-01' werden als UTC interpretiert, Strings mit Uhrzeit ohne Offset ('2024-01-01T00:00') dagegen als lokale Zeit – das beeinflusst das Ergebnis.
Nicht mit getYear() verwechseln: getYear() ist veraltet und gibt das Jahr minus 1900 zurück.
Ungültige Datumsobjekte liefern NaN – vor der Weiterverarbeitung mit Number.isNaN() prüfen.
Wird die Methode auf einem Nicht-Date-Objekt aufgerufen, wird ein TypeError geworfen.
In allen Browsern und Node.js-Versionen uneingeschränkt verfügbar.

Siehe auch

Date.prototype.getFullYear() Date.prototype.setUTCFullYear() Date.prototype.getUTCMonth() Date.prototype.getUTCDate() Date.prototype.toISOString() Date