Temporal.ZonedDateTime.prototype.getTimeZoneTransition() — Methode · JavaScript-Referenz

Signatur

Temporal.ZonedDateTime.prototype.getTimeZoneTransition(direction)

Beschreibung

Die Methode getTimeZoneTransition() sucht ausgehend vom Zeitpunkt der Instanz den nächsten ("next") oder vorherigen ("previous") Zeitzonenwechsel. Ein Wechsel ist jede Änderung des UTC-Offsets, also typischerweise die Umstellung auf oder von Sommerzeit, aber auch historische oder politisch bedingte Änderungen des Standard-Offsets.

Das Ergebnis ist ein neues Temporal.ZonedDateTime in derselben Zeitzone und demselben Kalender. Es steht für den ersten exakten Zeitpunkt, an dem schon der neue Offset gilt. Bei der Sommerzeit-Umstellung in Berlin am 31.03.2024 ist das zum Beispiel 2024-03-31T03:00:00+02:00[Europe/Berlin], weil die Uhrzeiten zwischen 02:00 und 03:00 an diesem Tag gar nicht vorkommen.

Gibt es in der gewünschten Richtung keinen Wechsel, liefert die Methode null. Das gilt für UTC, für feste Offsets wie "+05:30" und für Zeitzonen, die ihre Umstellungen dauerhaft abgeschafft haben (in Richtung "next"). Praktisch ist die Methode für Hinweise wie „Die Uhr wird in 3 Tagen umgestellt“, für Kalender- und Planungsanwendungen und zum Prüfen, ob ein Zeitraum eine Umstellung enthält.

Parameter

Name	Typ	Default	Beschreibung
$direction Pflicht	"next" \| "previous" \| { direction: "next" \| "previous" }		Suchrichtung. Entweder direkt als String oder als Optionsobjekt mit der Eigenschaft `direction`. `"next"` sucht den ersten Wechsel nach dem Zeitpunkt der Instanz, `"previous"` den letzten Wechsel davor.

Rückgabewert

Typ

Temporal.ZonedDateTime | null

Beschreibung

Ein neues Temporal.ZonedDateTime für den ersten Zeitpunkt mit dem neuen Offset, oder null, wenn es in dieser Richtung keinen Wechsel gibt.

Beispiele

Nächste und vorherige Sommerzeit-Umstellung finden

const jetzt = Temporal.ZonedDateTime.from('2024-01-15T12:00[Europe/Berlin]');

const naechste = jetzt.getTimeZoneTransition('next');
const vorherige = jetzt.getTimeZoneTransition({ direction: 'previous' });

console.log(naechste?.toString());
console.log(vorherige?.toString());

2024-03-31T03:00:00+02:00[Europe/Berlin] 2023-10-29T02:00:00+01:00[Europe/Berlin]

Zeitzonen ohne Umstellung liefern null

const utc = Temporal.ZonedDateTime.from('2024-06-01T12:00[UTC]');
const fest = Temporal.ZonedDateTime.from('2024-06-01T12:00+05:30[+05:30]');

console.log(utc.getTimeZoneTransition('next'));
console.log(fest.getTimeZoneTransition('previous'));

null null

Alle Umstellungen eines Jahres auflisten

const umstellungenImJahr = (jahr, zeitzone) => {
  const ende = Temporal.ZonedDateTime.from({ year: jahr + 1, month: 1, day: 1, timeZone: zeitzone });
  let zdt = Temporal.ZonedDateTime.from({ year: jahr, month: 1, day: 1, timeZone: zeitzone });
  const ergebnis = [];

  while ((zdt = zdt.getTimeZoneTransition('next')) &&
         Temporal.ZonedDateTime.compare(zdt, ende) < 0) {
    ergebnis.push(`${zdt.toPlainDate()} → Offset ${zdt.offset}`);
  }
  return ergebnis;
};

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

[ '2024-03-31 → Offset +02:00', '2024-10-27 → Offset +01:00' ]

Nutzer vor einer bevorstehenden Zeitumstellung warnen

const jetzt = Temporal.Now.zonedDateTimeISO('Europe/Berlin');
const wechsel = jetzt.getTimeZoneTransition('next');

if (wechsel) {
  const tage = jetzt.until(wechsel, { largestUnit: 'day' }).days;
  if (tage <= 7) {
    console.log(`Achtung: In ${tage} Tag(en) wird die Uhr umgestellt (neuer Offset ${wechsel.offset}).`);
  }
}

// Wichtig · Fallstricke

Das Argument ist Pflicht: Ohne Argument wirft die Methode einen TypeError, bei einem ungültigen Wert wie "forward" einen RangeError.
Immer auf null prüfen, bevor du mit dem Ergebnis weiterrechnest. Optional Chaining (?.) ist hier praktisch.
Die Suche schließt den Ausgangszeitpunkt aus: Liegt die Instanz genau auf einem Wechsel, liefert "next" den darauf folgenden Wechsel und "previous" den davor.
Es zählen nur Änderungen des UTC-Offsets. Ändert sich nur der Name oder die Abkürzung einer Zeitzone, wird das nicht als Wechsel gemeldet.
Die Ergebnisse hängen von der Zeitzonen-Datenbank (IANA tzdata) der Laufzeitumgebung ab. Künftige Umstellungen können sich durch politische Entscheidungen noch ändern.
In älteren Entwürfen von Temporal gab es dafür Temporal.TimeZone.prototype.getNextTransition() und getPreviousTransition(). Beide wurden zusammen mit Temporal.TimeZone entfernt.
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar. Für eine breite Unterstützung brauchst du ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.ZonedDateTime Temporal.ZonedDateTime.prototype.offset Temporal.ZonedDateTime.prototype.hoursInDay Temporal.ZonedDateTime.prototype.withTimeZone() Temporal.ZonedDateTime.prototype.startOfDay() Temporal.ZonedDateTime.compare()