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

Signatur

get Temporal.PlainDateTime.prototype.weekOfYear

Beschreibung

Die schreibgeschützte Zugriffseigenschaft weekOfYear gibt für eine Temporal.PlainDateTime-Instanz die Nummer der Kalenderwoche als positive ganze Zahl zurück. Die Uhrzeit spielt dabei keine Rolle, entscheidend ist nur der Datumsanteil.

Beim Standardkalender iso8601 gelten die Regeln der ISO 8601: Eine Woche beginnt am Montag, und Woche 1 ist die Woche, in der der erste Donnerstag des Jahres liegt. Das Jahr hat also 52 oder 53 Wochen. Das ist die übliche Zählweise für Kalenderwochen in Deutschland und Europa (z. B. „KW 11“).

Wichtig: Die Wochennummer gehört zu yearOfWeek und nicht unbedingt zu year. Anfang Januar kann ein Datum noch zur letzten Woche des Vorjahres gehören (Woche 52 oder 53), Ende Dezember kann es schon in Woche 1 des Folgejahres liegen. Für eindeutige Schlüssel wie 2025-W01 kombiniert man deshalb immer yearOfWeek mit weekOfYear.

Hat der verwendete Kalender kein festgelegtes Wochensystem (etwa viele Nicht-ISO-Kalender wie chinese oder hebrew), ist der Wert undefined. Die Eigenschaft hat keinen Setter. Eine Instanz mit einer anderen Woche erzeugt man über add() oder subtract() mit { weeks: n }.

Rückgabewert

Typ

number | undefined

Beschreibung

Ganze Zahl von 1 bis 53 (bei ISO 8601) für die Woche innerhalb von yearOfWeek. undefined, wenn der Kalender kein Wochensystem festlegt.

Beispiele

Kalenderwoche eines Termins ermitteln

const termin = Temporal.PlainDateTime.from("2024-03-15T14:30");
console.log(termin.weekOfYear);  // Woche
console.log(termin.yearOfWeek);  // Jahr der Woche
console.log(termin.dayOfWeek);   // 5 = Freitag

11 2024 5

Jahreswechsel: Woche gehört zu einem anderen Jahr

const neujahr = Temporal.PlainDateTime.from("2021-01-01T00:00");
console.log(neujahr.year, neujahr.yearOfWeek, neujahr.weekOfYear);

const silvesterWoche = Temporal.PlainDateTime.from("2024-12-30T09:00");
console.log(silvesterWoche.year, silvesterWoche.yearOfWeek, silvesterWoche.weekOfYear);

2021 2020 53 2024 2025 1

Zeiterfassung nach ISO-Wochen gruppieren

const buchungen = [
  "2024-12-30T08:00",
  "2025-01-02T16:45",
  "2025-01-07T10:15"
].map((s) => Temporal.PlainDateTime.from(s));

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

const gruppen = Object.groupBy(buchungen, wochenSchluessel);
for (const [woche, eintraege] of Object.entries(gruppen)) {
  console.log(woche, eintraege.length);
}

2025-W01 2 2025-W02 1

Kalender ohne Wochensystem

const dt = Temporal.PlainDateTime.from("2024-03-15T12:00[u-ca=chinese]");
const kw = dt.weekOfYear ?? dt.withCalendar("iso8601").weekOfYear;
console.log(dt.weekOfYear, kw);

undefined 11

// Wichtig · Fallstricke

Nicht mit year kombinieren: Ein Schlüssel wie `${dt.year}-W${dt.weekOfYear}` ist rund um den Jahreswechsel falsch (z. B. „2021-W53“ für den 01.01.2021). Verwende immer yearOfWeek.
Die Wochen beginnen nach ISO 8601 am Montag. Wochen, die am Sonntag beginnen (wie in den USA üblich), lassen sich mit weekOfYear nicht abbilden, dafür musst du selbst rechnen.
Bei Nicht-ISO-Kalendern kann der Wert undefined sein. Prüfe ihn deshalb oder wandle vorher mit withCalendar(\"iso8601\") um.
Die Eigenschaft ist schreibgeschützt, und with() nimmt kein weekOfYear an.
Kompatibilität: Temporal gibt es in Firefox ab Version 139 und in Chromium-Browsern ab Version 144. Safari und ältere Node.js-Versionen unterstützen es noch nicht. Dort brauchst du einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDateTime.prototype.yearOfWeek Temporal.PlainDateTime.prototype.dayOfWeek Temporal.PlainDateTime.prototype.daysInWeek Temporal.PlainDateTime.prototype.dayOfYear Temporal.PlainDate.prototype.weekOfYear Temporal.PlainDateTime