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

Signatur

get Temporal.ZonedDateTime.prototype.weekOfYear

Beschreibung

Die schreibgeschützte Zugriffs-Eigenschaft weekOfYear gibt für eine Temporal.ZonedDateTime-Instanz die Nummer der Woche im Jahr als positive Ganzzahl zurück. Grundlage ist das Datum in der Wanduhrzeit der gespeicherten Zeitzone, nicht der UTC-Zeitpunkt.

Im ISO-8601-Kalender ("iso8601", Standard) gilt die übliche Regel für Kalenderwochen: Wochen beginnen am Montag, und Woche 1 ist die Woche mit dem ersten Donnerstag des Jahres. Ein Jahr hat dann 52 oder 53 Wochen. Deshalb können die ersten Januartage noch zur letzten Woche des Vorjahres gehören und die letzten Dezembertage schon zu Woche 1 des Folgejahres. Das zugehörige Jahr steht in yearOfWeek. Dieser Wert kann von year abweichen.

Brauchbar ist die Eigenschaft z. B. für Wochenberichte, Schichtpläne, Sprint-Übersichten oder Beschriftungen wie „KW 7/2025“. Kombiniere weekOfYear immer mit yearOfWeek und nie mit year, damit du keine falschen Paare wie „KW 1/2025“ für den 30.12.2025 bekommst.

Bei Kalendern ohne festgelegtes Wochensystem (z. B. "hebrew", "islamic-civil") ist der Wert undefined.

Rückgabewert

Typ

number | undefined

Beschreibung

Positive Ganzzahl (im ISO-Kalender 1 bis 53) für die Woche innerhalb von yearOfWeek oder undefined, wenn der Kalender keine Wochennummerierung hat.

Beispiele

Kalenderwoche am Jahreswechsel

const zdt = Temporal.ZonedDateTime.from('2021-01-01T12:00[Europe/Berlin]');
console.log(zdt.year);       // Kalenderjahr
console.log(zdt.weekOfYear); // Woche
console.log(zdt.yearOfWeek); // Jahr, zu dem die Woche gehört

2021 53 2020

KW-Beschriftung für einen Wochenbericht

const kwLabel = (zdt) =>
  zdt.weekOfYear === undefined
    ? 'keine Kalenderwoche'
    : `KW ${String(zdt.weekOfYear).padStart(2, '0')}/${zdt.yearOfWeek}`;

const termin = Temporal.ZonedDateTime.from('2025-12-30T09:00[Europe/Berlin]');
console.log(kwLabel(termin));
console.log(kwLabel(Temporal.Now.zonedDateTimeISO('Europe/Berlin')));

KW 01/2026 (z. B.) KW 07/2025

Die Zeitzone ändert die Woche

const instant = Temporal.Instant.from('2025-12-28T23: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);

2025-12-28 52 2025 2025-12-29 1 2026

Kalender ohne Wochensystem

const zdt = Temporal.ZonedDateTime.from('2024-03-15T10:00[Europe/Berlin]');
console.log(zdt.weekOfYear);
console.log(zdt.withCalendar('hebrew').weekOfYear);

11 undefined

// Wichtig · Fallstricke

Nur mit yearOfWeek kombinieren: Die Kombination year + weekOfYear ist um den Jahreswechsel herum falsch (z. B. 1.1.2021 liegt in KW 53/2020).
Schreibgeschützt: Eine Zuweisung hat keine Wirkung (im strikten Modus gibt es einen TypeError). Auch with() nimmt weekOfYear nicht an. Einen bestimmten Wochentag einer KW musst du selbst berechnen, z. B. mit add({ weeks }) und dayOfWeek.
Nur ISO-Regeln: Die Wochenzählung richtet sich nach ISO 8601 (Montag als erster Tag, Woche mit dem ersten Donnerstag = Woche 1). Die US-Zählung (Sonntag als erster Tag, Woche mit dem 1. Januar = Woche 1) liefert die Eigenschaft nicht.
Zeitzonenabhängig: Derselbe Zeitpunkt kann je nach Zeitzone in unterschiedlichen Wochen liegen.
Vor der Nutzung auf undefined prüfen: Bei Nicht-ISO-Kalendern kann der Wert undefined sein. Prüfe das, bevor du damit rechnest.
Kompatibilität: Temporal ist relativ neu (Firefox 139+, Chromium 144+). In älteren Browsern, in Safari und in Node.js ohne Flag brauchst du ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill. Prüfe die Unterstützung mit typeof Temporal !== 'undefined'.

Siehe auch

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