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

Signatur

get Temporal.PlainDateTime.prototype.yearOfWeek

Beschreibung

Die schreibgeschützte Zugriffs-Eigenschaft yearOfWeek liefert das Jahr, zu dem die Kalenderwoche aus weekOfYear gehört. Im ISO-8601-Kalender (iso8601) ist das das ISO-Wochenjahr: Woche 1 ist die Woche mit dem ersten Donnerstag des Jahres, Wochen beginnen am Montag.

Um den Jahreswechsel herum kann yearOfWeek deshalb von year abweichen. Der 1. Januar 2021 gehört zum Beispiel zur Woche 53 des Jahres 2020, und der 30. Dezember 2024 schon zur Woche 1 des Jahres 2025. Wer Kalenderwochen anzeigt oder speichert (z. B. als 2025-W01), muss weekOfYear immer zusammen mit yearOfWeek nutzen und nicht mit year.

Hat der Kalender der Instanz kein festgelegtes Wochensystem, ist der Wert undefined. Das gilt dann genauso für weekOfYear. Die Uhrzeit-Anteile einer PlainDateTime spielen für den Wert keine Rolle.

Rückgabewert

Typ

number | undefined

Beschreibung

Ganzzahl für das Wochen-Jahr passend zu weekOfYear. undefined, wenn der Kalender kein Wochensystem hat.

Beispiele

Abweichung vom Kalenderjahr am Jahreswechsel

const neujahr = Temporal.PlainDateTime.from("2021-01-01T09:30");
console.log(neujahr.year);       // Kalenderjahr
console.log(neujahr.weekOfYear); // ISO-Woche
console.log(neujahr.yearOfWeek); // Wochen-Jahr

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

2021 53 2020 2024 1 2025

ISO-Wochenbezeichnung für Berichte erzeugen

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

const termine = [
  "2024-12-29T10:00",
  "2024-12-30T08:15",
  "2025-01-05T23:59",
  "2025-01-06T00:00"
].map((s) => Temporal.PlainDateTime.from(s));

for (const t of termine) {
  console.log(t.toString(), "→", isoWoche(t));
}

2024-12-29T10:00:00 → 2024-W52 2024-12-30T08:15:00 → 2025-W01 2025-01-05T23:59:00 → 2025-W01 2025-01-06T00:00:00 → 2025-W02

Termine nach Kalenderwoche gruppieren

const eintraege = [
  "2026-12-31T14:00",
  "2027-01-01T09:00",
  "2027-01-04T11:00"
].map((s) => Temporal.PlainDateTime.from(s));

const proWoche = Object.groupBy(eintraege, (dt) =>
  dt.yearOfWeek === undefined
    ? "ohne Woche"
    : `${dt.yearOfWeek}-W${String(dt.weekOfYear).padStart(2, "0")}`
);

console.log(Object.keys(proWoche));

[ '2026-W53', '2027-W01' ]

// Wichtig · Fallstricke

Häufigster Fehler: year mit weekOfYear kombinieren. Das ergibt um den Jahreswechsel falsche Angaben wie „2021-W53“. Richtig ist die Kombination mit yearOfWeek.
Nur lesbar: Eine Zuweisung hat keine Wirkung (im Strict Mode gibt es einen TypeError). Zum Ändern nutzt man with(), add() oder subtract().
Bei Kalendern ohne festgelegtes Wochensystem ist der Wert undefined. Vor einer Formatierung also prüfen, ob ein Wert vorhanden ist. Zuverlässig definiert ist nur iso8601.
Die ISO-Regel (Wochenbeginn Montag, erster Donnerstag) passt nicht zu jeder regionalen Wochenzählung, zum Beispiel in den USA mit Wochenbeginn am Sonntag.
Browser-Unterstützung: Temporal gibt es erst in neueren Browsern (Firefox 139+, Chrome 144+). Für ältere Umgebungen und Node.js braucht man einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDateTime.prototype.weekOfYear Temporal.PlainDateTime.prototype.year Temporal.PlainDateTime.prototype.dayOfWeek Temporal.PlainDateTime.prototype.daysInWeek Temporal.PlainDate.prototype.yearOfWeek Temporal.ZonedDateTime.prototype.yearOfWeek Temporal.PlainDateTime