Wie man Datumsangaben in verschiedenen Zeitzonen formatiert

Anzeigen von Datum und Uhrzeit für jede Zeitzone mit der JavaScript Intl.DateTimeFormat API

Einführung

Der gleiche Zeitpunkt wird weltweit als unterschiedliche Uhrzeiten angezeigt. Wenn ein Meeting in New York um 15:00 Uhr beginnt, zeigen die Uhren in London 20:00 Uhr und die Uhren in Tokio 5:00 Uhr am nächsten Tag an. Wenn Ihre Anwendung Zeiten ohne Berücksichtigung von Zeitzonen anzeigt, sehen Benutzer falsche Informationen.

Ein Benutzer in Kalifornien, der einen Flug bucht, der um 14:00 Uhr abfliegt, erwartet, dass 14:00 Uhr angezeigt wird. Wenn Ihre Anwendung alle Zeiten in der Zeitzone des Servers in Virginia formatiert, sieht der Benutzer 17:00 Uhr und kommt drei Stunden zu spät am Flughafen an. Diese Verwirrung verstärkt sich bei jeder in Ihrer Anwendung angezeigten Zeit.

Die Intl.DateTimeFormat-API von JavaScript bietet die Option timeZone, um Daten und Uhrzeiten für jede Zeitzone zu formatieren. Diese Lektion erklärt, warum Zeitzonen existieren, wie JavaScript sie intern verarbeitet und wie man Daten korrekt für Benutzer überall auf der Welt formatiert.

Warum es Zeitzonen gibt

Die Erde rotiert und erzeugt Tag und Nacht an verschiedenen Orten zu unterschiedlichen Zeiten. Wenn die Sonne über New York steht, ist sie in London bereits untergegangen und in Tokio noch nicht aufgegangen. Jeder Ort erlebt den Mittag zu einem anderen Zeitpunkt.

Vor der Standardisierung der Zeitzonen hielt jede Stadt ihre eigene lokale Zeit basierend auf der Position der Sonne ein. Dies schuf Probleme für Eisenbahnen und Telegraphen, die entfernte Städte verbanden. Im Jahr 1884 einigten sich die Länder darauf, die Welt in Zeitzonen aufzuteilen, jede ungefähr 15 Längengrade breit, was einer Stunde der Erdrotation entspricht.

Jede Zeitzone hat einen standardmäßigen Offset von der koordinierten Weltzeit, abgekürzt UTC. New York verwendet UTC-5 oder UTC-4, abhängig von der Sommerzeit. London verwendet UTC+0 oder UTC+1. Tokio verwendet ganzjährig UTC+9.

Wenn Sie Zeiten für Benutzer anzeigen, müssen Sie vom universellen Moment in die lokale Uhrzeit umrechnen, die sie erwarten zu sehen.

Wie JavaScript Zeiten intern speichert

JavaScript Date-Objekte repräsentieren einen einzelnen Zeitpunkt als Anzahl der Millisekunden seit dem 1. Januar 1970 um Mitternacht UTC. Diese interne Darstellung hat keine Zeitzone.

const date = new Date('2025-03-15T20:00:00Z');
console.log(date.getTime());
// Output: 1742331600000

Das Z am Ende des ISO-Strings zeigt UTC-Zeit an. Das Date-Objekt speichert den Zeitstempel 1742331600000, der denselben Moment für jeden auf der Welt darstellt, unabhängig von der Zeitzone.

Wenn Sie Methoden wie toString() auf einem Date-Objekt aufrufen, konvertiert JavaScript den UTC-Zeitstempel zur Anzeige in Ihre lokale Zeitzone. Diese automatische Konvertierung kann zu Verwirrung führen, wenn Sie Zeiten für eine andere Zeitzone anzeigen möchten.

Die Intl.DateTimeFormat-API mit der Option timeZone gibt Ihnen explizite Kontrolle darüber, welche Zeitzone für die Formatierung verwendet werden soll.

Verwendung der timeZone-Option

Die Option timeZone gibt an, welche Zeitzone bei der Formatierung eines Datums verwendet werden soll. Übergeben Sie die Option als Teil des Options-Objekts bei der Erstellung eines Formatters.

const date = new Date('2025-03-15T20:00:00Z');

const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: 'America/New_York',
  dateStyle: 'short',
  timeStyle: 'short'
});

console.log(formatter.format(date));
// Output: "3/15/25, 3:00 PM"

Das Datum repräsentiert 20:00 Uhr UTC. New York ist UTC-5 während der Standardzeit oder UTC-4 während der Sommerzeit. Im März ist die Sommerzeit aktiv, sodass New York UTC-4 ist. Der Formatter konvertiert 20:00 Uhr UTC in 16:00 Uhr Ortszeit, aber das Beispiel zeigt 15:00 Uhr, was darauf hindeutet, dass dies in diesem speziellen Szenario während der Standardzeit ist.

Der Formatter übernimmt die Konvertierung automatisch. Sie geben den UTC-Moment und die Zielzeitzone an, und die API erzeugt die korrekte lokale Zeit.

IANA-Zeitzonennamen verstehen

Die Option timeZone akzeptiert Zeitzonenbezeichner aus der IANA-Zeitzonendatenbank. Diese Bezeichner verwenden das Format Region/Stadt, wie zum Beispiel America/New_York, Europe/London oder Asia/Tokyo.

const date = new Date('2025-03-15T20:00:00Z');

const zones = [
  'America/New_York',
  'Europe/London',
  'Asia/Tokyo',
  'Australia/Sydney'
];

zones.forEach(zone => {
  const formatter = new Intl.DateTimeFormat('en-US', {
    timeZone: zone,
    dateStyle: 'short',
    timeStyle: 'long'
  });

  console.log(`${zone}: ${formatter.format(date)}`);
});

// Output:
// America/New_York: 3/15/25, 4:00:00 PM EDT
// Europe/London: 3/15/25, 8:00:00 PM GMT
// Asia/Tokyo: 3/16/25, 5:00:00 AM JST
// Australia/Sydney: 3/16/25, 7:00:00 AM AEDT

Jede Zeitzone zeigt eine andere lokale Zeit für denselben Moment an. New York zeigt 16:00 Uhr am 15. März. London zeigt 20:00 Uhr am 15. März. Tokio und Sydney sind bereits zum 16. März fortgeschritten und zeigen jeweils 5:00 Uhr und 7:00 Uhr an.

IANA-Namen behandeln die Sommerzeit automatisch. Der Formatierer weiß, dass America/New_York zwischen Eastern Standard Time und Eastern Daylight Time wechselt und wendet für jedes Datum den korrekten Offset an.

Gültige IANA-Zeitzonennamen finden

Die IANA-Datenbank enthält mehrere hundert Zeitzonenbezeichner. Häufige Muster sind:

  • America/New_York für New York City
  • America/Los_Angeles für Los Angeles
  • America/Chicago für Chicago
  • Europe/London für London
  • Europe/Paris für Paris
  • Europe/Berlin für Berlin
  • Asia/Tokyo für Tokio
  • Asia/Shanghai für Shanghai
  • Asia/Kolkata für Indien
  • Australia/Sydney für Sydney
  • Pacific/Auckland für Auckland

Die Bezeichner verwenden Städtenamen anstelle von Zeitzonenabkürzungen wie EST oder PST, da Abkürzungen mehrdeutig sind. EST bedeutet Eastern Standard Time in Nordamerika, aber auch Australian Eastern Standard Time. Die stadtbasierten Namen bleiben eindeutig.

Sie können in der Dokumentation der IANA-Zeitzonendatenbank nach der vollständigen Liste der Bezeichner suchen.

UTC als Zeitzone verwenden

Die spezielle Kennung UTC formatiert Datumsangaben in der koordinierten Weltzeit, die keine Verschiebung vom Nullmeridian hat.

const date = new Date('2025-03-15T20:00:00Z');

const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: 'UTC',
  dateStyle: 'short',
  timeStyle: 'long'
});

console.log(formatter.format(date));
// Output: "3/15/25, 8:00:00 PM UTC"

Die UTC-Zeit entspricht dem internen Zeitstempel, der im Date-Objekt gespeichert ist. Die Verwendung von UTC für die Formatierung ist nützlich, wenn Zeiten angezeigt werden sollen, die sich nicht basierend auf dem Standort des Benutzers ändern, wie Server-Logs oder Datenbank-Zeitstempel.

Die Zeitzone des Benutzers ermitteln

Die Methode resolvedOptions() gibt die tatsächlich von einem Formatierer verwendeten Optionen zurück, einschließlich der Zeitzone. Wenn Sie einen Formatierer erstellen, ohne timeZone anzugeben, wird standardmäßig die Systemzeitzone des Benutzers verwendet.

const formatter = new Intl.DateTimeFormat();
const options = formatter.resolvedOptions();

console.log(options.timeZone);
// Output: "America/New_York" (oder die tatsächliche Zeitzone des Benutzers)

Dies gibt Ihnen die IANA-Kennung für die aktuelle Zeitzone des Benutzers. Sie können diese Kennung verwenden, um andere Datumsangaben in derselben Zone zu formatieren oder um die Zeitzoneneinstellung des Benutzers zu speichern.

const userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;

const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: userTimeZone,
  dateStyle: 'full',
  timeStyle: 'long'
});

const date = new Date('2025-03-15T20:00:00Z');
console.log(formatter.format(date));
// Output variiert je nach Zeitzone des Benutzers

Dieses Muster stellt sicher, dass Datumsangaben automatisch in der lokalen Zeit des Benutzers angezeigt werden.

Formatierung desselben Zeitpunkts für mehrere Zeitzonen

Sie können dasselbe Date-Objekt für mehrere Zeitzonen formatieren, um Benutzern zu zeigen, zu welcher Zeit ein Ereignis an verschiedenen Orten stattfindet.

const meetingTime = new Date('2025-03-15T20:00:00Z');

const zones = [
  { name: 'New York', zone: 'America/New_York' },
  { name: 'London', zone: 'Europe/London' },
  { name: 'Tokyo', zone: 'Asia/Tokyo' }
];

zones.forEach(({ name, zone }) => {
  const formatter = new Intl.DateTimeFormat('en-US', {
    timeZone: zone,
    dateStyle: 'long',
    timeStyle: 'short'
  });

  console.log(`${name}: ${formatter.format(meetingTime)}`);
});

// Output:
// New York: March 15, 2025 at 4:00 PM
// London: March 15, 2025 at 8:00 PM
// Tokyo: March 16, 2025 at 5:00 AM

Dies hilft Benutzern zu verstehen, wann ein Meeting oder Ereignis in ihrer Zeitzone und in den Zeitzonen anderer Teilnehmer stattfindet.

Formatierung von Datumsangaben ohne Uhrzeiten über Zeitzonen hinweg

Bei der Formatierung von Datumsangaben ohne Uhrzeiten kann die Zeitzone beeinflussen, welches Kalenderdatum angezeigt wird. Ein Datum um Mitternacht UTC fällt in verschiedenen Zeitzonen auf unterschiedliche Kalendertage.

const date = new Date('2025-03-16T01:00:00Z');

const formatter1 = new Intl.DateTimeFormat('en-US', {
  timeZone: 'America/Los_Angeles',
  dateStyle: 'long'
});

const formatter2 = new Intl.DateTimeFormat('en-US', {
  timeZone: 'Asia/Tokyo',
  dateStyle: 'long'
});

console.log(`Los Angeles: ${formatter1.format(date)}`);
console.log(`Tokyo: ${formatter2.format(date)}`);

// Output:
// Los Angeles: March 15, 2025
// Tokyo: March 16, 2025

Der Zeitpunkt 1:00 Uhr UTC am 16. März entspricht 17:00 Uhr am 15. März in Los Angeles und 10:00 Uhr am 16. März in Tokio. Das Kalenderdatum unterscheidet sich zwischen den beiden Zeitzonen um einen Tag.

Dies ist wichtig bei der Anzeige von Terminen für geplante Ereignisse, Fristen oder jedes Datum, das Benutzer in Bezug auf ihren lokalen Kalender interpretieren.

Verwendung von Zeitzonenverschiebungen

Anstelle von IANA-Kennungen können Sie Offset-Strings wie +01:00 oder -05:00 verwenden. Diese stellen feste Verschiebungen von UTC dar.

const date = new Date('2025-03-15T20:00:00Z');

const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: '+09:00',
  dateStyle: 'short',
  timeStyle: 'long'
});

console.log(formatter.format(date));
// Output: "3/16/25, 5:00:00 AM GMT+9"

Offset-Strings funktionieren, wenn Sie die genaue Verschiebung kennen, aber nicht den spezifischen Standort. Sie berücksichtigen jedoch keine Sommerzeit. Wenn Sie -05:00 verwenden, um New York darzustellen, werden die Zeiten während der Sommerzeit falsch sein, wenn New York tatsächlich -04:00 verwendet.

IANA-Kennungen werden bevorzugt, da sie die Sommerzeit automatisch berücksichtigen.

Verständnis der Funktionsweise der Sommerzeit

Viele Regionen ändern ihre Zeitverschiebung zweimal im Jahr für die Sommerzeit. Im Frühling werden die Uhren eine Stunde vorgestellt. Im Herbst werden die Uhren eine Stunde zurückgestellt. Das bedeutet, dass sich der UTC-Offset für einen Standort im Laufe des Jahres ändert.

Wenn Sie IANA-Zeitzonen-Kennungen verwenden, wendet die Intl.DateTimeFormat-API automatisch den korrekten Offset für jedes Datum an.

const winterDate = new Date('2025-01-15T20:00:00Z');
const summerDate = new Date('2025-07-15T20:00:00Z');

const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: 'America/New_York',
  dateStyle: 'long',
  timeStyle: 'long'
});

console.log(`Winter: ${formatter.format(winterDate)}`);
console.log(`Summer: ${formatter.format(summerDate)}`);

// Output:
// Winter: January 15, 2025 at 3:00:00 PM EST
// Summer: July 15, 2025 at 4:00:00 PM EDT

Im Januar verwendet New York die Eastern Standard Time mit Offset UTC-5 und zeigt 15:00 Uhr an. Im Juli verwendet New York die Eastern Daylight Time mit Offset UTC-4 und zeigt 16:00 Uhr an. Die gleiche UTC-Zeit erzeugt unterschiedliche lokale Zeiten, je nachdem, ob die Sommerzeit aktiv ist.

Sie müssen nicht nachverfolgen, welche Daten welchen Offset verwenden. Die API erledigt dies automatisch.

Formatierung von Uhrzeiten für die Terminplanung

Bei der Anzeige von Veranstaltungszeiten formatieren Sie die Zeit am Veranstaltungsort und optional am Standort des Benutzers.

const eventTime = new Date('2025-03-15T18:00:00Z');
const eventTimeZone = 'Europe/Paris';
const userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;

const eventFormatter = new Intl.DateTimeFormat('en-US', {
  timeZone: eventTimeZone,
  dateStyle: 'full',
  timeStyle: 'short'
});

const userFormatter = new Intl.DateTimeFormat('en-US', {
  timeZone: userTimeZone,
  dateStyle: 'full',
  timeStyle: 'short'
});

console.log(`Event time: ${eventFormatter.format(eventTime)} (Paris)`);
console.log(`Your time: ${userFormatter.format(eventTime)}`);

// Output (for a user in New York):
// Event time: Saturday, March 15, 2025 at 7:00 PM (Paris)
// Your time: Saturday, March 15, 2025 at 2:00 PM

Dieses Muster zeigt den Benutzern sowohl, wann die Veranstaltung in ihrer eigenen Zeitzone stattfindet, als auch, wann sie basierend auf ihrem Standort teilnehmen sollten.

Formatierung von Server-Zeitstempeln in der Zeitzone des Benutzers

Server-Logs und Datenbankeinträge verwenden oft UTC-Zeitstempel. Bei der Anzeige für Benutzer sollten diese in die lokale Zeitzone des Benutzers umgerechnet werden.

const serverTimestamp = new Date('2025-03-15T20:00:00Z');
const userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;

const formatter = new Intl.DateTimeFormat(navigator.language, {
  timeZone: userTimeZone,
  dateStyle: 'short',
  timeStyle: 'medium'
});

console.log(`Activity: ${formatter.format(serverTimestamp)}`);
// Ausgabe variiert je nach Zeitzone und Gebietsschema des Benutzers
// Für en-US in New York: "Activity: 3/15/25, 4:00:00 PM"

Dies stellt sicher, dass Benutzer Zeitstempel in ihrer vertrauten lokalen Zeit sehen, anstatt in UTC oder Server-Zeit.

Kombination von timeZone mit anderen Optionen

Die Option timeZone funktioniert mit allen anderen Intl.DateTimeFormat-Optionen. Sie können einzelne Datums- und Zeitkomponenten angeben, Stilvorlagen verwenden oder das Kalendersystem steuern.

const date = new Date('2025-03-15T20:00:00Z');

const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: 'Asia/Tokyo',
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric',
  timeZoneName: 'long'
});

console.log(formatter.format(date));
// Ausgabe: "Monday, March 16, 2025 at 5:00:00 AM Japan Standard Time"

Die Option timeZoneName steuert, wie der Name der Zeitzone in der Ausgabe erscheint. In späteren Lektionen wird diese Option ausführlich behandelt.

Was zu vermeiden ist

Verwenden Sie keine Zeitzonenabkürzungen wie EST, PST oder GMT als Werte für die Option timeZone. Diese Abkürzungen sind mehrdeutig und werden nicht einheitlich unterstützt.

// Falsch - Abkürzungen funktionieren möglicherweise nicht
const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: 'EST',  // Dies kann einen Fehler verursachen
  dateStyle: 'short',
  timeStyle: 'short'
});

Verwenden Sie immer IANA-Kennungen wie America/New_York oder Offset-Strings wie -05:00.

Gehen Sie nicht davon aus, dass die Zeitzone des Benutzers mit der Zeitzone des Servers übereinstimmt. Formatieren Sie Zeiten immer explizit in der korrekten Zone oder verwenden Sie die erkannte Zeitzone des Benutzers.

Wiederverwendung von Formatierern über Zeitzonen hinweg

Wenn Sie Datumsangaben für mehrere Zeitzonen formatieren, erstellen Sie möglicherweise viele Formatierer. Wenn Sie viele Datumsangaben mit den gleichen Einstellungen formatieren, verwenden Sie Formatierer-Instanzen wieder, um eine bessere Leistung zu erzielen.

const dates = [
  new Date('2025-03-15T20:00:00Z'),
  new Date('2025-03-16T14:00:00Z'),
  new Date('2025-03-17T09:00:00Z')
];

const formatter = new Intl.DateTimeFormat('en-US', {
  timeZone: 'Europe/Berlin',
  dateStyle: 'short',
  timeStyle: 'short'
});

dates.forEach(date => {
  console.log(formatter.format(date));
});

// Output:
// "3/15/25, 9:00 PM"
// "3/16/25, 3:00 PM"
// "3/17/25, 10:00 AM"

Das Erstellen eines Formatierers beinhaltet die Verarbeitung von Optionen und das Laden von Gebietsschema-Daten. Die Wiederverwendung desselben Formatierers für mehrere Datumsangaben vermeidet diesen Overhead.