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

Signatur

get Temporal.ZonedDateTime.prototype.hoursInDay

Beschreibung

Die Zugriffs-Eigenschaft hoursInDay gibt zurück, wie viele Stunden der Kalendertag, auf den ein Temporal.ZonedDateTime fällt, in der zugehörigen Zeitzone wirklich hat. Gemessen wird vom Tagesbeginn (startOfDay()) bis zum Beginn des nächsten Tages. An normalen Tagen ist das 24. An Tagen mit Zeitumstellung kommt ein anderer Wert heraus: in Mitteleuropa 23 bei der Umstellung auf Sommerzeit und 25 bei der Rückstellung.

Anders als die MDN-Kurzbeschreibung nahelegt, ist der Wert nicht zwingend eine Ganzzahl. Manche Zeitzonen verschieben die Uhr um 30 Minuten, etwa Australia/Lord_Howe. Dort liefert die Eigenschaft Werte wie 23.5 oder 24.5. Der Wert ist aber immer positiv.

Die Eigenschaft ist praktisch, wenn Tageswerte richtig berechnet werden sollen, etwa bei Stundenlöhnen für Nachtschichten, Zählerständen pro Stunde, Kalenderrastern mit einer Zeile pro Stunde oder bei der Prüfung, ob ein Tag eine Zeitumstellung enthält. Weil die Zeitzone nötig ist, gibt es hoursInDay nur bei Temporal.ZonedDateTime. Temporal.PlainDate und Temporal.PlainDateTime haben diese Eigenschaft nicht.

Die Eigenschaft kann nur gelesen werden. Die Uhrzeit innerhalb des Tages spielt keine Rolle: Alle Zeitpunkte desselben Kalendertags in derselben Zeitzone liefern denselben Wert.

Rückgabewert

Typ

number

Beschreibung

Positive Zahl: die Stunden zwischen dem Beginn dieses Tages und dem Beginn des nächsten Tages in der Zeitzone der Instanz. Meist 24, an Tagen mit Zeitumstellung z. B. 23, 25 oder 23.5.

Beispiele

Normaler Tag und Tage mit Zeitumstellung in Berlin

const normal = Temporal.ZonedDateTime.from('2024-06-15T12:00[Europe/Berlin]');
const sommerzeit = Temporal.ZonedDateTime.from('2024-03-31T12:00[Europe/Berlin]');
const winterzeit = Temporal.ZonedDateTime.from('2024-10-27T12:00[Europe/Berlin]');

console.log(normal.hoursInDay);
console.log(sommerzeit.hoursInDay);
console.log(winterzeit.hoursInDay);

24 23 25

Halbstündige Umstellung: keine Ganzzahl

// Lord-Howe-Insel stellt die Uhr nur um 30 Minuten um
const start = Temporal.ZonedDateTime.from('2024-10-06T12:00[Australia/Lord_Howe]');
const ende = Temporal.ZonedDateTime.from('2024-04-07T12:00[Australia/Lord_Howe]');

console.log(start.hoursInDay);
console.log(ende.hoursInDay);

23.5 24.5

Alle Tage mit Zeitumstellung eines Jahres finden

const findeUmstellungstage = (jahr, zeitzone) => {
  const ergebnis = [];
  let tag = Temporal.PlainDate.from({ year: jahr, month: 1, day: 1 })
    .toZonedDateTime(zeitzone);

  while (tag.year === jahr) {
    if (tag.hoursInDay !== 24) {
      ergebnis.push(`${tag.toPlainDate()}: ${tag.hoursInDay} h`);
    }
    tag = tag.add({ days: 1 });
  }
  return ergebnis;
};

console.log(findeUmstellungstage(2024, 'Europe/Berlin'));
console.log(findeUmstellungstage(2024, 'UTC'));

[ '2024-03-31: 23 h', '2024-10-27: 25 h' ] []

Stundenraster für eine Kalenderansicht

const tag = Temporal.Now.zonedDateTimeISO('Europe/Berlin').startOfDay();

// Genau so viele Zeilen wie der Tag Stunden hat (auf ganze Stunden gerundet)
const zeilen = Array.from({ length: Math.ceil(tag.hoursInDay) }, (_, i) =>
  tag.add({ hours: i }).toPlainTime().toString({ smallestUnit: 'minute' })
);

console.log(zeilen.length, zeilen.slice(0, 3));

24 [ '00:00', '01:00', '02:00' ] // an Umstellungstagen 23 bzw. 25 Zeilen

// Wichtig · Fallstricke

Nicht immer ganzzahlig: Bei 30-Minuten-Umstellungen (z. B. Australia/Lord_Howe) oder historischen Offset-Änderungen kann ein Bruchwert herauskommen. Vergleiche daher nicht nur mit 23 und 25, sondern prüfe auf !== 24.
Nicht einfach 24 annehmen: Rechnungen wie tage * 24 sind bei Zeitumstellungen falsch. Nutze stattdessen hoursInDay oder since()/until() mit largestUnit: 'hour'.
Übersprungene Mitternacht: In manchen Zeitzonen (historisch z. B. America/Sao_Paulo) beginnt der Tag an Umstellungstagen erst um 01:00 Uhr. hoursInDay berücksichtigt das richtig, weil ab startOfDay() gezählt wird.
Feste Offsets: Bei UTC oder Offset-Zeitzonen wie +02:00 ist der Wert immer 24.
Zeitzonendaten: Das Ergebnis hängt von der IANA-Zeitzonendatenbank der Laufzeitumgebung ab. Für künftige Jahre kann es sich ändern, wenn Staaten ihre Regeln ändern.
Kompatibilität: Temporal ist noch nicht in allen Engines verfügbar (Firefox ab 139, Chromium ab 144, Safari noch nicht). Für ältere Umgebungen gibt es das Polyfill @js-temporal/polyfill.

Siehe auch

Temporal.ZonedDateTime.prototype.hour Temporal.ZonedDateTime.prototype.day Temporal.ZonedDateTime.prototype.daysInYear Temporal.ZonedDateTime.prototype.monthsInYear Temporal.ZonedDateTime.prototype.daysInWeek