Signatur
Beschreibung
Die Accessor-Eigenschaft timeZoneId liefert den Bezeichner der Zeitzone, die zu einer Temporal.ZonedDateTime-Instanz gehört. Ein ZonedDateTime besteht intern aus einem exakten Zeitpunkt (Nanosekunden seit der Unix-Epoche), einer Zeitzone und einem Kalender. Aus der Zeitzone ergeben sich Wanduhrzeit, UTC-Versatz und das Verhalten bei Sommerzeitumstellungen.
Der Wert ist entweder ein IANA-Bezeichner wie "America/New_York" oder "UTC" oder ein fester Versatz wie "+05:30" oder "-08:00". Die Groß-/Kleinschreibung von IANA-Namen wird normalisiert ("europe/berlin" wird zu "Europe/Berlin"). Aliasnamen werden aber nicht durch den Hauptnamen ersetzt: "Asia/Calcutta" bleibt "Asia/Calcutta" und wird nicht zu "Asia/Kolkata".
Typische Einsatzfälle sind das Protokollieren oder Speichern der Zeitzone neben einem Zeitstempel, das Anzeigen der Zeitzone in einer Oberfläche und das Weitergeben der Zeitzone an andere APIs wie Intl.DateTimeFormat oder Temporal.ZonedDateTime.from(). Die Eigenschaft ist nur lesbar. Wenn du die Zeitzone wechseln willst, nimm withTimeZone(). Das ergibt eine neue Instanz mit demselben exakten Zeitpunkt.
Rückgabewert
"Europe/Berlin", "UTC") oder ein Versatz im Format ±HH:MM (z. B. "+05:30").Beispiele
Zeitzone eines geparsten Datums auslesen
const termin = Temporal.ZonedDateTime.from('2024-03-10T12:00[America/New_York]');
console.log(termin.timeZoneId);
console.log(termin.offset);
// Groß-/Kleinschreibung wird normalisiert
const berlin = Temporal.ZonedDateTime.from('2024-06-01T09:00[europe/berlin]');
console.log(berlin.timeZoneId);Aktuelle Systemzeitzone und feste Versätze
const jetzt = Temporal.Now.zonedDateTimeISO();
console.log(`Lokale Zeitzone: ${jetzt.timeZoneId}`);
const mitVersatz = Temporal.ZonedDateTime.from('2024-01-01T00:00+05:30[+05:30]');
console.log(mitVersatz.timeZoneId);
const utc = Temporal.Instant.fromEpochMilliseconds(0).toZonedDateTimeISO('UTC');
console.log(utc.timeZoneId);Zeitzone wechseln und für die Speicherung serialisieren
const meeting = Temporal.ZonedDateTime.from('2024-11-05T15:00[Europe/Berlin]');
// withTimeZone() behält den exakten Zeitpunkt bei
const inTokio = meeting.withTimeZone('Asia/Tokyo');
console.log(inTokio.timeZoneId, inTokio.toPlainTime().toString());
// Zeitzone getrennt speichern, z. B. in einer Datenbank
const datensatz = {
epochMs: meeting.epochMilliseconds,
zone: meeting.timeZoneId,
};
const wiederhergestellt = Temporal.Instant
.fromEpochMilliseconds(datensatz.epochMs)
.toZonedDateTimeISO(datensatz.zone);
console.log(wiederhergestellt.equals(meeting));// Wichtig · Fallstricke
- Nur lesbar: Es gibt nur einen Getter. Eine Zuweisung wie
zdt.timeZoneId = 'UTC'wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einenTypeErroraus. Nimm stattdessenwithTimeZone(). - Aliase bleiben erhalten:
"Asia/Calcutta"und"Asia/Kolkata"bezeichnen dieselbe Zone, aber ein Stringvergleich dertimeZoneId-Werte ergibtfalse.equals()dagegen behandelt beide als gleichwertig. - Versatz ist keine echte Zeitzone: Ein fester Versatz wie
"+01:00"kennt keine Sommerzeit. Für Berechnungen über Umstellungsgrenzen hinweg solltest du einen IANA-Namen verwenden. - Frühere Proposal-Versionen: Ältere Polyfills hatten eine Eigenschaft
timeZone, die ein Objekt zurückgab. In der endgültigen Spezifikation gibt es nur nochtimeZoneIdals String. - Kompatibilität: Temporal wird noch nicht in allen Browsern unterstützt (u. a. fehlt es in Safari). Für den produktiven Einsatz empfiehlt sich ein Polyfill wie
@js-temporal/polyfillodertemporal-polyfill.