JavaScript Temporal API: Moderne Datums- und Zeitmanipulation

Das JavaScript-Date-Objekt ist seit langem eine Quelle der Frustration für Entwickler. Seine Veränderbarkeit, das Fehlen einer integrierten Zeitzonenunterstützung und die umständliche API haben zu unzähligen Bibliotheken und Workarounds geführt. Glücklicherweise zielt die Temporal API darauf ab, diese Mängel zu beheben, indem sie eine moderne, intuitive und zeitzonenbewusste Lösung für die Datums- und Zeitmanipulation in JavaScript bietet.

Was ist die Temporal API?

Die Temporal API ist ein neues globales Objekt, Temporal, das eine moderne und standardisierte Methode zur Arbeit mit Daten und Zeiten in JavaScript bietet. Sie wurde entwickelt, um das veraltete Date-Objekt zu ersetzen und bietet erhebliche Verbesserungen in Bezug auf API-Design, Unveränderlichkeit, Zeitzonenunterstützung und allgemeine Benutzerfreundlichkeit. Sie ist Teil des ECMAScript-Vorschlags und wird in wichtigen JavaScript-Engines implementiert.

Hauptvorteile der Temporal API:

• Unveränderlichkeit (Immutability): Temporal-Objekte sind unveränderlich, was bedeutet, dass Operationen an ihnen neue Objekte zurückgeben, anstatt das Original zu modifizieren. Dies hilft, unerwartete Nebeneffekte zu vermeiden und den Code leichter verständlich zu machen.
• Klare API: Die API ist intuitiver und konsistenter gestaltet als das veraltete Date-Objekt.
• Zeitzonenunterstützung: Temporal bietet eine robuste Unterstützung für Zeitzonen, sodass Sie mit Daten und Zeiten an verschiedenen Orten weltweit arbeiten können.
• Kalenderunterstützung: Über den Gregorianischen Kalender hinaus ermöglicht die API die Verwendung anderer Kalendersysteme, was globale Anwendungen erleichtert.
• Handhabung von Schaltsekunden: Die Temporal API berücksichtigt Schaltsekunden und bietet so genauere Zeitberechnungen.

Erste Schritte mit Temporal

Obwohl die Temporal API sich noch in der Entwicklung befindet und noch nicht vollständig in allen Browsern und Node.js-Umgebungen unterstützt wird, können Sie ein Polyfill verwenden, um noch heute damit zu experimentieren. Sie können das Polyfill über npm installieren:

            npm install @js-temporal/polyfill
            

              
                Copy
              
            
          

Importieren Sie dann das Polyfill in Ihrem JavaScript-Code:

            import { Temporal } from '@js-temporal/polyfill';
            

              
                Copy
              
            
          

Sobald das Polyfill installiert ist, können Sie das Temporal-Objekt und seine verschiedenen Klassen verwenden.

Wichtige Temporal-Klassen

Die Temporal API bietet mehrere Schlüsselklassen für die Arbeit mit Daten und Zeiten:

• Temporal.PlainDate: Repräsentiert ein Kalenderdatum (Jahr, Monat und Tag) ohne Zeitzonen- oder Tageszeitinformationen.
• Temporal.PlainTime: Repräsentiert eine Tageszeit (Stunde, Minute, Sekunde und Bruchteil einer Sekunde) ohne Datums- oder Zeitzoneninformationen.
• Temporal.PlainDateTime: Repräsentiert ein Datum und eine Uhrzeit ohne Zeitzoneninformationen.
• Temporal.ZonedDateTime: Repräsentiert ein Datum und eine Uhrzeit mit einer bestimmten Zeitzone.
• Temporal.Instant: Repräsentiert einen bestimmten Zeitpunkt, gemessen in Nanosekunden seit der Unix-Epoche (1. Januar 1970, 00:00:00 Koordinierte Weltzeit (UTC)).
• Temporal.TimeZone: Repräsentiert eine Zeitzone.
• Temporal.Duration: Repräsentiert eine Zeitdauer, wie Stunden, Minuten oder Sekunden.
• Temporal.Now: Bietet Zugriff auf das aktuelle Datum und die aktuelle Uhrzeit.

Arbeiten mit PlainDate

Die Klasse Temporal.PlainDate repräsentiert ein Datum ohne Zeitzonen- oder Tageszeitinformationen. Sie ist nützlich für die Darstellung von Geburtstagen, Jahrestagen oder anderen datumsbasierten Ereignissen.

Erstellen eines PlainDate:

            const plainDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26 });
console.log(plainDate.toString()); // Output: 2024-10-26
            

              
                Copy
              
            
          

Sie können auch ein PlainDate aus einem String im ISO 8601-Format erstellen:

            const plainDateFromString = Temporal.PlainDate.from('2024-12-25');
console.log(plainDateFromString.toString()); // Output: 2024-12-25
            

              
                Copy
              
            
          

Zugriff auf Datumskomponenten:

            const year = plainDate.year; // 2024
const month = plainDate.month; // 10
const day = plainDate.day;   // 26
const dayOfWeek = plainDate.dayOfWeek; // Day of the week (1-7, Monday-Sunday)
const dayOfYear = plainDate.dayOfYear; // Day of the year (1-366)
const daysInMonth = plainDate.daysInMonth; // Number of days in the month
const isLeapYear = plainDate.isLeapYear;   // Boolean indicating if the year is a leap year
            

              
                Copy
              
            
          

Hinzufügen und Subtrahieren von Tagen:

            const nextDay = plainDate.add({ days: 1 });
console.log(nextDay.toString()); // Output: 2024-10-27

const previousWeek = plainDate.subtract({ weeks: 1 });
console.log(previousWeek.toString()); // Output: 2024-10-19
            

              
                Copy
              
            
          

Vergleichen von Daten:

            const anotherDate = Temporal.PlainDate.from({ year: 2024, month: 11, day: 15 });

if (plainDate.equals(anotherDate)) {
  console.log('Dates are equal');
} else if (plainDate.lessThan(anotherDate)) {
  console.log('plainDate is earlier than anotherDate');
} else {
  console.log('plainDate is later than anotherDate');
}
// Output: plainDate is earlier than anotherDate
            

              
                Copy
              
            
          

Arbeiten mit PlainTime

Die Klasse Temporal.PlainTime repräsentiert eine Tageszeit ohne Datums- oder Zeitzoneninformationen. Sie ist nützlich für die Darstellung von Öffnungszeiten, Besprechungszeiten oder anderen zeitbasierten Ereignissen.

Erstellen eines PlainTime:

            const plainTime = Temporal.PlainTime.from({ hour: 14, minute: 30, second: 0 });
console.log(plainTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

Sie können auch ein PlainTime aus einem String im ISO 8601-Format erstellen:

            const plainTimeFromString = Temporal.PlainTime.from('09:00:00');
console.log(plainTimeFromString.toString()); // Output: 09:00:00
            

              
                Copy
              
            
          

Zugriff auf Zeitkomponenten:

            const hour = plainTime.hour;   // 14
const minute = plainTime.minute; // 30
const second = plainTime.second; // 0
const millisecond = plainTime.millisecond; // 0
const microsecond = plainTime.microsecond; // 0
const nanosecond = plainTime.nanosecond;   // 0
            

              
                Copy
              
            
          

Hinzufügen und Subtrahieren von Zeit:

            const laterTime = plainTime.add({ minutes: 15 });
console.log(laterTime.toString()); // Output: 14:45:00

const earlierTime = plainTime.subtract({ hours: 1 });
console.log(earlierTime.toString()); // Output: 13:30:00
            

              
                Copy
              
            
          

Vergleichen von Zeiten:

            const anotherTime = Temporal.PlainTime.from({ hour: 15, minute: 0, second: 0 });

if (plainTime.equals(anotherTime)) {
  console.log('Times are equal');
} else if (plainTime.lessThan(anotherTime)) {
  console.log('plainTime is earlier than anotherTime');
} else {
  console.log('plainTime is later than anotherTime');
}
// Output: plainTime is earlier than anotherTime
            

              
                Copy
              
            
          

Arbeiten mit PlainDateTime

Die Klasse Temporal.PlainDateTime repräsentiert ein Datum und eine Uhrzeit ohne Zeitzoneninformationen. Sie kombiniert die Funktionalität von PlainDate und PlainTime.

Erstellen eines PlainDateTime:

            const plainDateTime = Temporal.PlainDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0 });
console.log(plainDateTime.toString()); // Output: 2024-10-26T14:30:00
            

              
                Copy
              
            
          

Sie können auch ein PlainDateTime aus einem String im ISO 8601-Format erstellen:

            const plainDateTimeFromString = Temporal.PlainDateTime.from('2024-12-25T09:00:00');
console.log(plainDateTimeFromString.toString()); // Output: 2024-12-25T09:00:00
            

              
                Copy
              
            
          

Zugriff auf Datums- und Zeitkomponenten:

            const year = plainDateTime.year;   // 2024
const month = plainDateTime.month; // 10
const day = plainDateTime.day;     // 26
const hour = plainDateTime.hour;   // 14
const minute = plainDateTime.minute; // 30
const second = plainDateTime.second; // 0
            

              
                Copy
              
            
          

Hinzufügen und Subtrahieren von Daten und Zeiten:

            const nextDayAndTime = plainDateTime.add({ days: 1, hours: 2 });
console.log(nextDayAndTime.toString()); // Output: 2024-10-27T16:30:00

const previousWeekAndTime = plainDateTime.subtract({ weeks: 1, minutes: 30 });
console.log(previousWeekAndTime.toString()); // Output: 2024-10-19T14:00:00
            

              
                Copy
              
            
          

Konvertieren zu PlainDate und PlainTime:

            const plainDateFromDateTime = plainDateTime.toPlainDate();
console.log(plainDateFromDateTime.toString()); // Output: 2024-10-26

const plainTimeFromDateTime = plainDateTime.toPlainTime();
console.log(plainTimeFromDateTime.toString()); // Output: 14:30:00
            

              
                Copy
              
            
          

Arbeiten mit ZonedDateTime

Die Klasse Temporal.ZonedDateTime repräsentiert ein Datum und eine Uhrzeit mit einer bestimmten Zeitzone. Dies ist entscheidend für Anwendungen, die Daten und Zeiten an verschiedenen Orten weltweit handhaben müssen. Im Gegensatz zum veralteten Date-Objekt bietet Temporal eine integrierte Zeitzonenunterstützung.

Erstellen eines ZonedDateTime:

            const zonedDateTime = Temporal.ZonedDateTime.from({ year: 2024, month: 10, day: 26, hour: 14, minute: 30, second: 0, timeZone: 'America/Los_Angeles' });
console.log(zonedDateTime.toString()); // Output: 2024-10-26T14:30:00-07:00[America/Los_Angeles]
            

              
                Copy
              
            
          

Sie können auch ein ZonedDateTime aus einem Instant und einer Zeitzone erstellen:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example timestamp
const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('Europe/London');
console.log(zonedDateTimeFromInstant.toString()); // Output will vary based on the actual instant but will reflect the date/time in Europe/London
            

              
                Copy
              
            
          

Zugriff auf Datums- und Zeitkomponenten:

            const year = zonedDateTime.year;   // 2024
const month = zonedDateTime.month; // 10
const day = zonedDateTime.day;     // 26
const hour = zonedDateTime.hour;   // 14
const minute = zonedDateTime.minute; // 30
const second = zonedDateTime.second; // 0
const timeZone = zonedDateTime.timeZone; // Temporal.TimeZone object
            

              
                Copy
              
            
          

Konvertieren zwischen Zeitzonen:

            const newYorkDateTime = zonedDateTime.withTimeZone('America/New_York');
console.log(newYorkDateTime.toString()); // Output: 2024-10-26T17:30:00-04:00[America/New_York]
            

              
                Copy
              
            
          

Handhabung der Sommerzeit (DST):

Temporal handhabt DST-Übergänge automatisch. Beim Hinzufügen oder Subtrahieren von Zeit wird die Sommerzeit berücksichtigt, um genaue Ergebnisse zu gewährleisten. Betrachten Sie beispielsweise ein Meeting, das über den DST-Übergang in Deutschland geplant ist:

            const meetingStart = Temporal.ZonedDateTime.from({ year: 2024, month: 3, day: 31, hour: 2, minute: 30, timeZone: 'Europe/Berlin' });
const meetingEnd = meetingStart.add({ hours: 1 }); // Adding 1 hour
console.log(meetingEnd.toString()); // Output: 2024-03-31T03:30:00+02:00[Europe/Berlin]. Notice the offset changes due to DST
            

              
                Copy
              
            
          

Arbeiten mit Instant

Die Klasse Temporal.Instant repräsentiert einen bestimmten Zeitpunkt, gemessen in Nanosekunden seit der Unix-Epoche. Sie ist nützlich zum Speichern und Vergleichen exakter Zeitpunkte.

Erstellen eines Instant:

            const instant = Temporal.Instant.fromEpochSeconds(1666785000); // Example Unix timestamp in seconds
console.log(instant.toString()); // Output will be an ISO string representation of that instant
            

              
                Copy
              
            
          

Konvertieren zu ZonedDateTime:

            const zonedDateTimeFromInstant = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTimeFromInstant.toString()); // Output: Date and time in America/Los_Angeles corresponding to the instant
            

              
                Copy
              
            
          

Vergleichen von Instants:

            const anotherInstant = Temporal.Instant.fromEpochSeconds(1666790000);

if (instant.equals(anotherInstant)) {
  console.log('Instants are equal');
} else if (instant.lessThan(anotherInstant)) {
  console.log('instant is earlier than anotherInstant');
} else {
  console.log('instant is later than anotherInstant');
}
// Output: instant is earlier than anotherInstant
            

              
                Copy
              
            
          

Arbeiten mit Duration

Die Klasse Temporal.Duration repräsentiert eine Zeitdauer, wie Stunden, Minuten oder Sekunden. Sie ist nützlich, um die Differenz zwischen zwei Daten oder Zeiten zu berechnen.

Erstellen einer Duration:

            const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });
console.log(duration.toString()); // Output: PT2H30M
            

              
                Copy
              
            
          

Berechnen der Differenz zwischen Daten/Zeiten:

            const startDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 1, hour: 0, minute: 0, second: 0 });
const endDate = Temporal.PlainDateTime.from({ year: 2024, month: 1, day: 3, hour: 12, minute: 30, second: 0 });
const difference = endDate.since(startDate);
console.log(difference.toString()); // Output: P2DT12H30M

// Accessing the components of the duration
console.log(difference.days);    // 2
console.log(difference.hours);   // 12
console.log(difference.minutes); // 30
            

              
                Copy
              
            
          

Hinzufügen einer Dauer zu Daten/Zeiten:

            const newDate = startDate.add(duration);
console.log(newDate.toString()); // Output: 2024-01-03T02:30:00
            

              
                Copy
              
            
          

Arbeiten mit Kalendern

Die Temporal API unterstützt verschiedene Kalendersysteme jenseits des Gregorianischen Kalenders. Obwohl dies noch nicht in allen Polyfills und Engines vollständig implementiert ist, ist es die Absicht, Anwendungen zu ermöglichen, Daten in kalenderspezifischen Systemen verschiedener Kulturen zu handhaben. Zum Beispiel, um den japanischen Kalender zu verwenden (hypothetisch, da die Implementierung noch in Entwicklung ist):

            // This is a conceptual example as calendar support is still under development
// const japaneseDate = Temporal.PlainDate.from({ year: 2024, month: 10, day: 26, calendar: 'japanese' });
// console.log(japaneseDate.toString()); // Expected: Output formatted according to the Japanese calendar

            

              
                Copy
              
            
          

Hinweis: Die Kalenderunterstützung ist eine sich entwickelnde Funktion der Temporal API, und die volle Funktionalität ist noch nicht allgemein verfügbar.

Praktische Beispiele und Anwendungsfälle

Die Temporal API bietet eine breite Palette von Möglichkeiten zur Handhabung von Daten und Zeiten in JavaScript. Hier sind einige praktische Beispiele und Anwendungsfälle:

• Terminplanung: Erstellen Sie eine Terminplanungsanwendung, die es Benutzern ermöglicht, Termine in ihrer lokalen Zeitzone zu buchen. Temporal.ZonedDateTime erleichtert die Konvertierung zwischen Zeitzonen und die Handhabung von DST-Übergängen. Für eine Klinik in Berlin, die Termine weltweit plant:

            const appointmentTimeBerlin = Temporal.ZonedDateTime.from({ year: 2024, month: 11, day: 5, hour: 10, minute: 0, timeZone: 'Europe/Berlin' });
const appointmentTimeLA = appointmentTimeBerlin.withTimeZone('America/Los_Angeles');
console.log(`Appointment Time in Berlin: ${appointmentTimeBerlin.toString()}`);
console.log(`Appointment Time in Los Angeles: ${appointmentTimeLA.toString()}`);
            

              
                Copy
              
            
          

• Alter berechnen: Bestimmen Sie das Alter eines Benutzers basierend auf seinem Geburtsdatum. PlainDate ermöglicht es Ihnen, das Geburtsdatum ohne Zeitzoneninformationen darzustellen.

            const birthDate = Temporal.PlainDate.from({ year: 1990, month: 5, day: 15 });
const today = Temporal.Now.plainDateISO();
const age = today.year - birthDate.year - (today.month < birthDate.month || (today.month === birthDate.month && today.day < birthDate.day) ? 1 : 0);
console.log(`Age: ${age}`);
            

              
                Copy
              
            
          

• Anzeigen von Daten und Zeiten in verschiedenen Formaten: Formatieren Sie Daten und Zeiten gemäß der Gebietsschema des Benutzers. Während Internationalisierungs-(Intl)-Funktionen separat sind, können Temporal-Objekte einfach mit toLocaleString() oder ähnlichen Methoden formatiert werden, wenn sie mit Intl API-Funktionen kombiniert werden.

            const zonedDateTimeNow = Temporal.Now.zonedDateTimeISO('en-GB');
console.log(zonedDateTimeNow.toLocaleString('en-GB'));
console.log(zonedDateTimeNow.toLocaleString('de-DE'));
            

              
                Copy
              
            
          

• Verfolgen von Ereignisdauern: Berechnen Sie die Dauer eines Ereignisses und zeigen Sie sie in einem menschenlesbaren Format an. Duration ermöglicht es Ihnen, die Zeitdifferenz zwischen zwei Daten oder Zeiten darzustellen.

            const eventStart = Temporal.Instant.fromEpochSeconds(1700000000); // Example start timestamp
const eventEnd = Temporal.Instant.fromEpochSeconds(1700005000);   // Example end timestamp
const durationOfEvent = eventEnd.since(eventStart);
console.log(`Event duration: ${durationOfEvent.minutes} minutes`);
            

              
                Copy
              
            
          

Best Practices für die Verwendung der Temporal API

Hier sind einige bewährte Methoden, die Sie bei der Verwendung der Temporal API beachten sollten:

• Unveränderlichkeit nutzen: Machen Sie sich die Unveränderlichkeit von Temporal-Objekten zu eigen. Vermeiden Sie es, Objekte direkt zu ändern. Erstellen Sie stattdessen neue Objekte mit Methoden wie add, subtract und with.
• Zeitzonen sorgfältig behandeln: Achten Sie bei der Arbeit mit Daten und Zeiten auf Zeitzonen. Verwenden Sie ZonedDateTime, wenn Sie Daten und Zeiten in einer bestimmten Zeitzone darstellen müssen.
• Klare Variablennamen verwenden: Verwenden Sie beschreibende Variablennamen, die den Typ des verwendeten Temporal-Objekts klar angeben (z. B. plainDate, zonedDateTime, duration).
• Polyfills berücksichtigen: Da Temporal noch relativ neu ist, stellen Sie sicher, dass ausreichende Unterstützung durch die Verwendung einer Polyfill-Bibliothek bei Bedarf gewährleistet ist.
• Eingabe validieren: Validieren Sie immer Benutzereingaben, um sicherzustellen, dass Daten und Zeiten im richtigen Format vorliegen.

Migration vom veralteten Date-Objekt

Die Migration vom veralteten Date-Objekt kann ein schrittweiser Prozess sein. Berücksichtigen Sie diese Strategien:

• Inkrementelle Einführung: Beginnen Sie mit der Verwendung von Temporal in neuem Code, während Sie Date in bestehenden Teilen Ihrer Anwendung beibehalten.
• Wrapper-Funktionen: Erstellen Sie Wrapper-Funktionen, die zwischen Date- und Temporal-Objekten konvertieren, um die Interoperabilität während der Migration zu erleichtern.
• Gründliche Tests: Testen Sie die Migration ausgiebig, um sicherzustellen, dass alle Datums- und Zeitberechnungen genau sind.

Temporal API vs. Moment.js

Moment.js war eine beliebte Bibliothek für die Datums- und Zeitmanipulation in JavaScript, wird aber mittlerweile als veraltetes Projekt betrachtet und befindet sich im Wartungsmodus. Die Temporal API bietet eine modernere und standardisierte Lösung, die viele der Mängel von Moment.js behebt. Moment.js ist veränderlich (mutable) und verfügt nicht über native Zeitzonenunterstützung. Die Temporal API ist unveränderlich (immutable) und verfügt über native Zeitzonenunterstützung.

Fazit

Die JavaScript Temporal API stellt eine wesentliche Verbesserung gegenüber dem veralteten Date-Objekt dar. Ihre Unveränderlichkeit, klare API, Zeitzonenunterstützung und Kalenderunterstützung machen sie zu einem leistungsstarken Werkzeug für die Handhabung von Daten und Zeiten in modernen JavaScript-Anwendungen. Während die Akzeptanz noch wächst, können Sie durch die Verwendung eines Polyfills noch heute die Vorteile nutzen. Wenn die API breiter unterstützt wird, wird sie voraussichtlich der Standardweg für die Arbeit mit Daten und Zeiten in JavaScript werden.

Nutzen Sie die Temporal API und erschließen Sie sich eine effizientere und zuverlässigere Methode zur Verwaltung von Daten und Zeiten in Ihren Projekten, um sicherzustellen, dass Ihre Anwendung globale Zeitzonen und Berechnungen präzise handhabt.