Temporal.PlainDate.prototype.weekOfYear — Eigenschaft · JavaScript-Referenz

Signatur

get Temporal.PlainDate.prototype.weekOfYear

Beschreibung

Die schreibgeschützte Zugriffs-Eigenschaft weekOfYear gibt für eine Temporal.PlainDate-Instanz die Nummer der Kalenderwoche als positive ganze Zahl zurück. Im Standardkalender iso8601 gelten die Regeln der ISO 8601: Die Woche beginnt am Montag, und Woche 1 ist die Woche mit dem ersten Donnerstag des Jahres (also die Woche, in der der 4. Januar liegt). Ein Jahr hat dadurch 52 oder 53 Wochen.

Wichtig: Die Wochennummer bezieht sich nicht auf year, sondern auf yearOfWeek. Tage Ende Dezember können schon zu Woche 1 des Folgejahres gehören, Tage Anfang Januar noch zur Woche 52 oder 53 des Vorjahres. Für Beschriftungen wie „2025-W01“ sollte man deshalb immer yearOfWeek zusammen mit weekOfYear verwenden.

Typische Einsatzfälle sind Kalenderwochen-Anzeigen in Planungs- und Zeiterfassungs-Tools, das Gruppieren von Datensätzen nach Woche oder Berichte im Format „KW 11/2024“. Bei Kalendern ohne festgelegtes Wochensystem (derzeit alle Kalender außer iso8601, z. B. gregory) ist der Wert undefined.

Rückgabewert

Typ

number | undefined

Beschreibung

Ganze Zahl von 1 bis 53 (ISO-Kalender) oder undefined, wenn der Kalender keine Wochennummerierung definiert.

Beispiele

Kalenderwoche eines Datums ermitteln

const datum = Temporal.PlainDate.from("2024-03-15");
console.log(datum.weekOfYear);
console.log(datum.dayOfWeek); // 5 = Freitag

11 5

Jahreswechsel: weekOfYear immer mit yearOfWeek kombinieren

const kwLabel = (d) =>
  `${d.yearOfWeek}-W${String(d.weekOfYear).padStart(2, "0")}`;

const a = Temporal.PlainDate.from("2021-01-01");
const b = Temporal.PlainDate.from("2024-12-30");

console.log(a.year, kwLabel(a)); // gehört noch zum Vorjahr
console.log(b.year, kwLabel(b)); // gehört schon zum Folgejahr

2021 2020-W53 2024 2025-W01

Termine nach Kalenderwoche gruppieren

const termine = ["2024-03-11", "2024-03-14", "2024-03-18", "2024-03-24"]
  .map((s) => Temporal.PlainDate.from(s));

const proWoche = Object.groupBy(
  termine,
  (d) => `KW ${d.weekOfYear}/${d.yearOfWeek}`
);

for (const [woche, tage] of Object.entries(proWoche)) {
  console.log(woche, tage.map(String));
}

KW 11/2024 [ '2024-03-11', '2024-03-14' ] KW 12/2024 [ '2024-03-18', '2024-03-24' ]

Anzahl der ISO-Wochen eines Jahres und Nicht-ISO-Kalender

// Der 28. Dezember liegt immer in der letzten ISO-Woche des Jahres
const wochenImJahr = (jahr) =>
  Temporal.PlainDate.from({ year: jahr, month: 12, day: 28 }).weekOfYear;

console.log(wochenImJahr(2020), wochenImJahr(2021));

const greg = Temporal.PlainDate.from("2024-03-15[u-ca=gregory]");
console.log(greg.weekOfYear);

53 52 undefined

// Wichtig · Fallstricke

Jahresfalle: weekOfYear gehört zu yearOfWeek, nicht zu year. Wer `${d.year}-W${d.weekOfYear}` baut, erzeugt um den Jahreswechsel falsche Bezeichnungen (z. B. „2024-W01“ für den 30.12.2024).
Nicht-ISO-Kalender: Für Kalender wie gregory, hebrew oder japanese ist der Wert undefined. Deshalb vor Berechnungen prüfen oder das Datum mit withCalendar(\"iso8601\") umwandeln.
Keine regionalen Wochenregeln: Die US-Zählung (Woche beginnt am Sonntag, 1. Januar liegt immer in Woche 1) wird nicht unterstützt. Dafür braucht man eine eigene Berechnung oder Intl.Locale.prototype.getWeekInfo().
Die Eigenschaft ist schreibgeschützt. Ein Datum lässt sich nicht direkt über with({ weekOfYear }) setzen.
Kompatibilität: Temporal ist erst in neueren Browsern verfügbar (Firefox 139+, Chrome/Edge 144+). In Safari und Node.js braucht man je nach Version einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDate.prototype.yearOfWeek Temporal.PlainDate.prototype.dayOfWeek Temporal.PlainDate.prototype.daysInWeek Temporal.PlainDate.prototype.dayOfYear Temporal.PlainDate.prototype.withCalendar() Temporal.PlainDate