Temporal.ZonedDateTime.prototype.yearOfWeek — Eigenschaft · JavaScript-Referenz

Signatur

get Temporal.ZonedDateTime.prototype.yearOfWeek

Beschreibung

Die schreibgeschützte Zugriffseigenschaft yearOfWeek gibt das Jahr zurück, zu dem die Kalenderwoche (weekOfYear) eines Temporal.ZonedDateTime gehört. Im ISO-8601-Kalender beginnt eine Woche am Montag. Woche 1 ist die Woche mit dem ersten Donnerstag des Jahres. Deshalb können die ersten Tage im Januar noch zur letzten Woche des Vorjahres gehören. Umgekehrt können die letzten Tage im Dezember schon in Woche 1 des Folgejahres fallen.

Diesen Wert brauchst du, wenn du Kalenderwochen eindeutig benennen willst, etwa als ISO-Wochendatum 2025-W01. Das gilt auch für Berichte, Sprintplanung oder Gruppierungen nach Woche. Verwende weekOfYear nie zusammen mit year: Sonst würde der 30.12.2024 fälschlich als „Woche 1 von 2024“ erscheinen.

Bei ZonedDateTime gilt immer das lokale Datum in der Zeitzone des Objekts. Derselbe Zeitpunkt kann also je nach Zeitzone in einem anderen Wochenjahr liegen. Der Wert hängt außerdem vom Kalender ab: Hat ein Kalender kein festgelegtes Wochensystem, ist das Ergebnis undefined.

Rückgabewert

Typ

number | undefined

Beschreibung

Eine Ganzzahl mit dem Wochenjahr, oder undefined, wenn der Kalender kein festgelegtes Wochensystem hat.

Beispiele

Wochenjahr weicht vom Kalenderjahr ab

const neujahr = Temporal.ZonedDateTime.from("2021-01-01T10:00[Europe/Berlin]");
console.log(neujahr.year, neujahr.weekOfYear, neujahr.yearOfWeek);

const silvesterWoche = Temporal.ZonedDateTime.from("2024-12-30T10:00[Europe/Berlin]");
console.log(silvesterWoche.year, silvesterWoche.weekOfYear, silvesterWoche.yearOfWeek);

2021 53 2020 2024 1 2025

ISO-Wochendatum für Berichte erzeugen

const isoWoche = (zdt) =>
  zdt.yearOfWeek === undefined
    ? null
    : `${zdt.yearOfWeek}-W${String(zdt.weekOfYear).padStart(2, "0")}-${zdt.dayOfWeek}`;

const jetzt = Temporal.ZonedDateTime.from("2027-01-02T08:15[Europe/Berlin]");
console.log(isoWoche(jetzt));

2026-W53-6

Die Zeitzone bestimmt das Wochenjahr

const instant = Temporal.Instant.from("2024-12-29T23:30:00Z");

const utc = instant.toZonedDateTimeISO("UTC");
const berlin = instant.toZonedDateTimeISO("Europe/Berlin");

console.log(utc.toPlainDate().toString(), utc.weekOfYear, utc.yearOfWeek);
console.log(berlin.toPlainDate().toString(), berlin.weekOfYear, berlin.yearOfWeek);

2024-12-29 52 2024 2024-12-30 1 2025

Kalender ohne Wochensystem

const zdt = Temporal.ZonedDateTime.from("2024-03-15T12:00[Asia/Tokyo][u-ca=hebrew]");
console.log(zdt.yearOfWeek); // Implementierungsabhängig, oft undefined
console.log(zdt.withCalendar("iso8601").yearOfWeek);

undefined 2024

// Wichtig · Fallstricke

Nicht mit year kombinieren: Kombiniere weekOfYear immer mit yearOfWeek. Mit year entstehen rund um den Jahreswechsel falsche Wochenbezeichnungen.
Schreibgeschützt: Eine Zuweisung hat keine Wirkung, im Strict Mode gibt es einen TypeError. Auch with() akzeptiert yearOfWeek nicht als Feld. Für Berechnungen nach Wochen verwendest du add({ weeks }) oder subtract({ weeks }).
undefined abfangen: Bei Kalendern außer iso8601 (und ggf. gregory) kann der Wert undefined sein. Wandle das Datum für eine einheitliche Wochenzählung mit withCalendar("iso8601") um.
Zeitzone beachten: Ausschlaggebend ist die lokale Wanduhrzeit. Kurz vor Mitternacht kann derselbe Zeitpunkt in zwei Zeitzonen in unterschiedlichen Wochenjahren liegen.
Kompatibilität: Temporal ist neu (Firefox 139+, Chromium 144+). Safari und ältere Node.js-Versionen unterstützen es noch nicht vollständig. Als Ersatz dient z. B. das Polyfill @js-temporal/polyfill.

Siehe auch

Temporal.ZonedDateTime.prototype.weekOfYear Temporal.ZonedDateTime.prototype.year Temporal.ZonedDateTime.prototype.dayOfWeek Temporal.PlainDate.prototype.yearOfWeek Temporal.ZonedDateTime.prototype.withCalendar() Temporal.ZonedDateTime