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

Signatur

get Temporal.ZonedDateTime.prototype.dayOfYear

Beschreibung

Die Zugriffs-Eigenschaft dayOfYear gibt eine positive Ganzzahl zurück, die angibt, der wievielte Tag des Jahres das Datum ist. Der erste Tag des Jahres hat den Wert 1. Im ISO-8601-Kalender liegt der Wert zwischen 1 und 365 bzw. in Schaltjahren zwischen 1 und 366. Der Höchstwert entspricht immer daysInYear.

Weil ein Temporal.ZonedDateTime einen exakten Zeitpunkt mit einer Zeitzone verbindet, hängt dayOfYear von der Wanduhrzeit in dieser Zeitzone ab. Ein und derselbe Zeitpunkt kann in Berlin schon auf den 1. Januar (Tag 1) fallen, während es in UTC noch der 31. Dezember (Tag 365 oder 366) ist.

Typische Einsatzfälle sind Tagesnummern in Berichten, Fortschrittsanzeigen für das Jahr („Tag 196 von 365“), julianisch anmutende Datumsformate wie YYYY-DDD (ISO-Ordinaldatum) oder das tageweise Verteilen von Inhalten, etwa bei einem „Tipp des Tages“.

Die Eigenschaft ist schreibgeschützt: Es gibt keinen Setter. Wer ein Datum für einen bestimmten Tag im Jahr braucht, nimmt den 1. Januar per with() und addiert dann mit add() die fehlenden Tage.

Rückgabewert

Typ

number

Beschreibung

Positive Ganzzahl ab 1: der Tag im Jahr nach dem Kalender der Instanz. Im ISO-Kalender 1–365 bzw. 1–366.

Beispiele

Tag im Jahr ermitteln (Schaltjahr und Gemeinjahr)

const schaltjahr = Temporal.ZonedDateTime.from("2024-03-01T12:00[Europe/Berlin]");
const gemeinjahr = Temporal.ZonedDateTime.from("2023-03-01T12:00[Europe/Berlin]");

console.log(schaltjahr.dayOfYear); // 29. Februar zählt mit
console.log(gemeinjahr.dayOfYear);

61 60

Die Zeitzone bestimmt den Tag

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

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

console.log(utc.toPlainDate().toString(), utc.dayOfYear);
console.log(berlin.toPlainDate().toString(), berlin.dayOfYear);

2024-12-31 366 2025-01-01 1

Jahresfortschritt und Resttage anzeigen

const jetzt = Temporal.ZonedDateTime.from("2025-07-15T09:00[America/New_York]");

const rest = jetzt.daysInYear - jetzt.dayOfYear;
const prozent = ((jetzt.dayOfYear / jetzt.daysInYear) * 100).toFixed(1);

console.log(`Tag ${jetzt.dayOfYear} von ${jetzt.daysInYear} – noch ${rest} Tage (${prozent} %)`);

Tag 196 von 365 – noch 169 Tage (53.7 %)

Datum aus einer Tagesnummer bilden (kein Setter vorhanden)

const imJahr = (zdt, tag) =>
  zdt.with({ month: 1, day: 1 }).add({ days: tag - 1 });

const basis = Temporal.ZonedDateTime.from("2024-06-01T10:00[Europe/Berlin]");
const tagDesProgrammierers = imJahr(basis, 256);

console.log(tagDesProgrammierers.toPlainDate().toString());
console.log(tagDesProgrammierers.dayOfYear);

2024-09-12 256

// Wichtig · Fallstricke

Browser-Kompatibilität: Temporal ist noch recht neu. Firefox unterstützt es ab Version 139, Chromium-Browser ab Version 144, Safari und ältere Node.js-Versionen teils noch nicht. In Produktion daher per typeof Temporal !== "undefined" prüfen oder einen Polyfill wie @js-temporal/polyfill laden.
Schreibgeschützt: zdt.dayOfYear = 10 ändert nichts. Im Strict Mode wirft die Zuweisung einen TypeError. Temporal-Objekte sind unveränderlich. Neue Werte entstehen über with() oder add().
Zeitzone beachten: Der Wert bezieht sich auf das lokale Datum in der Zeitzone der Instanz, nicht auf UTC. Beim Vergleich von Tagesnummern aus verschiedenen Zeitzonen können Unterschiede von ±1 auftreten.
Kalenderabhängig: Bei anderen Kalendern als iso8601 (z. B. hebrew oder islamic-umalqura) zählt dayOfYear ab dem Jahresanfang dieses Kalenders. Die Zahl weicht dann vom gregorianischen Wert ab, und daysInYear kann z. B. 353–385 betragen.
Nicht verwechseln mit weekOfYear (ISO-Kalenderwoche) oder day (Tag im Monat).

Siehe auch

Temporal.ZonedDateTime.prototype.daysInYear Temporal.ZonedDateTime.prototype.day Temporal.ZonedDateTime.prototype.dayOfWeek Temporal.ZonedDateTime.prototype.weekOfYear Temporal.ZonedDateTime.prototype.with() Temporal.PlainDate.prototype.dayOfYear