Signatur
Beschreibung
Die Accessor-Eigenschaft offset gibt den Abstand zwischen der lokalen Wanduhrzeit der Instanz und UTC als String zurück, zum Beispiel "+02:00" oder "-05:00". Dieser Wert hängt nicht nur von der Zeitzone ab, sondern auch vom konkreten Zeitpunkt: In Europe/Berlin ergibt sich im Winter "+01:00" und während der Sommerzeit "+02:00".
Normalerweise hat der String das Format ±HH:mm. Bei historischen Offsets, die nicht auf ganze Minuten fallen (etwa die lokale mittlere Ortszeit vor Einführung der Standardzeitzonen), kommen Sekunden und ggf. Sekundenbruchteile dazu: ±HH:mm:ss bzw. ±HH:mm:ss.sssssssss. Brauchst du den Offset zum Rechnen, nimm offsetNanoseconds. Diese Eigenschaft liefert denselben Wert als Zahl.
Nützlich ist offset vor allem beim Anzeigen von Zeitstempeln mit Offset, beim Erzeugen von RFC-3339-/ISO-8601-Strings für APIs und beim Auflösen mehrdeutiger Uhrzeiten während der Zeitumstellung. In der Rückstunde gibt es dieselbe Wanduhrzeit zweimal, und nur der Offset unterscheidet die beiden Zeitpunkte.
Die Eigenschaft ist schreibgeschützt, denn es gibt nur einen Getter. Um einen anderen Offset zu wählen, erzeugst du mit with({ offset }) und der Option offset eine neue Instanz. ZonedDateTime-Objekte sind unveränderlich.
Rückgabewert
±HH:mm, bei Offsets unterhalb einer Minute im Format ±HH:mm:ss bzw. ±HH:mm:ss.sssssssss. UTC ergibt "+00:00".Beispiele
Winter- und Sommerzeit in Berlin
const winter = Temporal.ZonedDateTime.from("2024-01-15T12:00[Europe/Berlin]");
const sommer = Temporal.ZonedDateTime.from("2024-07-15T12:00[Europe/Berlin]");
console.log(winter.offset);
console.log(sommer.offset);
console.log(sommer.offsetNanoseconds / 3.6e12, "Stunden");Mehrdeutige Uhrzeit bei der Zeitumstellung unterscheiden
// Am 27.10.2024 gibt es 02:30 in Berlin zweimal
const frueh = Temporal.ZonedDateTime.from(
"2024-10-27T02:30[Europe/Berlin]",
{ disambiguation: "earlier" }
);
const spaet = Temporal.ZonedDateTime.from(
"2024-10-27T02:30[Europe/Berlin]",
{ disambiguation: "later" }
);
console.log(frueh.offset, spaet.offset);
// Offset gezielt wechseln (liefert eine neue Instanz)
const umgestellt = frueh.with({ offset: "+01:00" }, { offset: "prefer" });
console.log(umgestellt.offset, umgestellt.equals(spaet));Historischer Offset mit Sekunden und Zeitstempel für eine API
const alt = Temporal.ZonedDateTime.from("1900-01-01T00:00[Asia/Shanghai]");
console.log(alt.offset);
// RFC-3339-String ohne Zeitzonen-Annotation, z. B. für ein Backend
const jetzt = Temporal.ZonedDateTime.from("2024-03-10T09:15:00[America/New_York]");
const stamp = jetzt.toString({ timeZoneName: "never", smallestUnit: "second" });
console.log(jetzt.offset, stamp);// Wichtig · Fallstricke
- Schreibgeschützt: Eine Zuweisung wie
zdt.offset = "+01:00"hat keine Wirkung und löst im Strict Mode einenTypeErroraus. Einen anderen Offset setzt du mitzdt.with({ offset }, { offset: "prefer" | "reject" | "use" | "ignore" }). - Offset ist keine Zeitzone: Wenn du nur
"+01:00"speicherst, fehlen die Regeln für die Sommerzeit. Für spätere Berechnungen speicherst du deshalb die IANA-Zeitzone (timeZoneId). Der Offset allein reicht nur, um einen Zeitpunkt eindeutig festzuhalten. - Sekunden-Offsets: Historische Daten können Offsets wie
"+00:53:28"liefern. Parser, die strikt±HH:mmerwarten, können daran scheitern. - Offset in Zeitzonen-Datenbanken: Das Ergebnis hängt von der IANA-Datenbank der Laufzeitumgebung ab. Bei neuen Regeländerungen können sich Browser und Node.js-Versionen daher unterscheiden.
- Kompatibilität: Temporal ist erst in neueren Engines verfügbar (Firefox ab 139, neuere Chromium-Versionen). Safari und ältere Umgebungen brauchen einen Polyfill wie
@js-temporal/polyfill. Prüfe die Unterstützung mittypeof Temporal !== "undefined".