HTML: Markup language
CSS: Styling language
JavaScript: Scripting language
Web APIs: Programming interfaces
All web technology
Learn web development
Discover our tools
Get to know MDN better
Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten. Erfahre mehr über dieses Experiment.
View in English Always switch to English
Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.
Das Temporal-Objekt ermöglicht die Verwaltung von Datum und Uhrzeit in verschiedenen Szenarien, darunter eingebaute Zeitzonen- und Kalenderdarstellung, Wanduhrenzeiteinheiten, Arithmetik, Formatierung und mehr. Es wurde als vollständiger Ersatz für das Date-Objekt entworfen.
Temporal
Date
Im Gegensatz zu den meisten globalen Objekten ist Temporal kein Konstruktor. Sie können es nicht mit dem new-Operator verwenden oder das Temporal-Objekt als Funktion aufrufen. Alle Eigenschaften und Methoden von Temporal sind statisch (genau wie das Math-Objekt).
new
Math
Temporal hat eine komplexe und leistungsstarke API. Es bietet über seine verschiedenen Klassen mehr als 200 Hilfsmethoden an und kann so sehr komplex wirken. Wir geben Ihnen einen Überblick darüber, wie diese APIs miteinander in Beziehung stehen.
JavaScript wird seit seinen ersten Tagen mit dem Date-Objekt für die Handhabung von Datum und Zeit ausgeliefert. Die Date-API basiert jedoch auf der schlecht gestalteten java.util.Date-Klasse aus Java, die Anfang der 2010er Jahre ersetzt wurde; aber aufgrund von JavaScripts Ziel der Abwärtskompatibilität bleibt Date in der Sprache erhalten.
java.util.Date
Die wichtigste Lektion gleich zu Beginn der Einführung ist, dass Datumshandhabung komplex ist. Die meisten Probleme von Date sind durch das Hinzufügen weiterer Methoden behebbar, aber ein grundlegender Designfehler bleibt bestehen: Es bietet so viele Methoden auf demselben Objekt, dass Entwickler oft verwirrt sind, was sie verwenden sollen, was zu unerwarteten Problemen führt. Eine gut gestaltete API sollte nicht nur mehr können, sondern auf jeder Abstraktionsebene auch weniger tun, weil die Vermeidung von Fehlanwendungen ebenso wichtig ist wie das Ermöglichen von Anwendungsfällen.
Date-Objekte haben eine Doppelfunktion:
Zeitzonen sind die Ursache für eine erhebliche Anzahl datumsbezogener Fehler. Bei der Interaktion mit einem Date über das Modell der "Komponentenkombination" kann die Zeit nur in zwei Zeitzonen sein: UTC und lokal (Gerät), und es gibt keine Möglichkeit, eine beliebige Zeitzone anzugeben. Außerdem fehlt das Konzept von "keine Zeitzone": Dies wird als Kalenderdatum (für Daten) oder Wanduhrzeit (für Zeiten) bezeichnet, was eine Zeit ist, die man "von einem Kalender oder einer Uhr abliest". Wenn Sie beispielsweise einen täglichen Wecker stellen, möchten Sie ihn auf "8:00 Uhr" stellen, unabhängig davon, ob Sommerzeit ist oder nicht, ob Sie in eine andere Zeitzone gereist sind usw.
Ein weiteres Merkmal, das bei Date fehlt, ist ein Kalendersystem. Die meisten Leute kennen den gregorianischen Kalender, in dem es zwei Epochen gibt, BC und AD; es gibt 12 Monate; jeder Monat hat eine unterschiedliche Anzahl von Tagen; es gibt ein Schaltjahr alle 4 Jahre; und so weiter. Einige dieser Konzepte gelten jedoch möglicherweise nicht, wenn Sie mit einem anderen Kalendersystem arbeiten, wie dem hebräischen Kalender, dem chinesischen Kalender, dem japanischen Kalender usw. Mit Date können Sie nur mit dem Modell des gregorianischen Kalenders arbeiten.
Es gibt viele andere unerwünschte Vermächtnisse von Date, wie zum Beispiel, dass alle Setzmethoden veränderlich sind (was oft unerwünschte Nebeneffekte verursacht), das Datums-Zeit-String-Format nicht konsistent geparst werden kann usw. Am Ende ist der beste Lösungsansatz, eine neue API von Grund auf zu entwickeln, was Temporal ist.
Temporal ist ein Namensraum, ähnlich wie Intl. Es enthält verschiedene Klassen und Namensräume, von denen jeder einen bestimmten Aspekt der Verwaltung von Datum und Uhrzeit behandelt. Die Klassen lassen sich wie folgt gruppieren:
Intl
Temporal.Duration
Temporal.Instant
Temporal.ZonedDateTime
Temporal.PlainDateTime
ZonedDateTime
PlainDateTime
Temporal.PlainDate
Temporal.PlainYearMonth
Temporal.PlainMonthDay
Temporal.PlainTime
Weiterhin gibt es einen weiteren Hilfsnamensraum, Temporal.Now, der Methoden zum Abrufen der aktuellen Zeit in verschiedenen Formaten bereitstellt.
Temporal.Now
Es gibt viele Klassen im Temporal-Namensraum, aber sie teilen sich viele ähnliche Methoden. Die folgende Tabelle listet alle Methoden jeder Klasse auf (außer Konvertierungsmethoden):
Instant
PlainDate
PlainTime
PlainYearMonth
PlainMonthDay
Instant()
Instant.from()
Instant.fromEpochMilliseconds()
Instant.fromEpochNanoseconds()
ZonedDateTime()
ZonedDateTime.from()
PlainDateTime()
PlainDateTime.from()
PlainDate()
PlainDate.from()
PlainTime()
PlainTime.from()
PlainYearMonth()
PlainYearMonth.from()
PlainMonthDay()
PlainMonthDay.from()
with()
withCalendar()
withTimeZone()
withPlainTime()
add()
subtract()
since()
until()
round()
equals()
Instant.compare()
ZonedDateTime.compare()
PlainDateTime.compare()
PlainDate.compare()
PlainTime.compare()
PlainYearMonth.compare()
toJSON()
toLocaleString()
toString()
valueOf()
Die folgende Tabelle fasst zusammen, welche Eigenschaften in jeder Klasse verfügbar sind und vermittelt Ihnen eine Vorstellung davon, welche Informationen jede Klasse darstellen kann.
calendarId
era
eraYear
year
inLeapYear
monthsInYear
daysInYear
month
monthCode
daysInMonth
weekOfYear
yearOfWeek
daysInWeek
day
dayOfWeek
dayOfYear
hour
minute
second
millisecond
microsecond
nanosecond
timeZoneId
offset
offsetNanoseconds
hoursInDay
getTimeZoneTransition()
startOfDay()
epochMilliseconds
epochNanoseconds
Die folgende Tabelle fasst alle Konvertierungsmethoden zusammen, die auf jeder Klasse existieren.
toInstant()
toZonedDateTimeISO()
toZonedDateTime()
PlainDate#toZonedDateTime()
toPlainDateTime()
PlainDate#toPlainDateTime()
toPlainDate()
toPlainTime()
toPlainYearMonth()
toPlainMonthDay()
Mit diesen Tabellen sollten Sie ein grundlegendes Verständnis davon haben, wie Sie die Temporal-API navigieren können.
Ein Kalender ist eine Möglichkeit, Tage zu organisieren, typischerweise in Perioden von Wochen, Monaten, Jahren und Epochen. Die meisten Teile der Welt verwenden den gregorianischen Kalender, aber es gibt viele andere Kalender, die insbesondere in religiösen und kulturellen Kontexten verwendet werden. Standardmäßig verwenden alle kalenderbewussten Temporal-Objekte das ISO 8601-Kalendersystem, das auf dem gregorianischen Kalender basiert und zusätzliche Regeln zur Wochennummerierung definiert. Intl.supportedValuesOf() listet die meisten Kalender auf, die wahrscheinlich von Browsern unterstützt werden. Hier geben wir einen kurzen Überblick darüber, wie Kalendersysteme gebildet werden, um Ihnen zu helfen, zu verstehen, welche Faktoren zwischen Kalendern variieren können.
Intl.supportedValuesOf()
Es gibt drei prominente periodische Ereignisse auf der Erde: Ihre Rotation um die Sonne (365,242 Tage für eine Umdrehung), die Rotation des Mondes um die Erde (29,53 Tage von Neumond zu Neumond) und ihre Rotation um ihre Achse (24 Stunden von Sonnenaufgang zu Sonnenaufgang). Jede Kultur hat dieselbe Definition eines "Tages", das sind 24 Stunden. Gelegentliche Änderungen wie Sommerzeit gehören nicht zum Kalender, sondern sind Teil der Zeitzonen-Informationen.
In Temporal wird jedes Datum unter einem Kalendersystem eindeutig durch drei Komponenten identifiziert: year, month und day. Während yearzumeist eine positive ganze Zahl ist, kann es auch null oder negativ sein und monoton mit der Zeit zunehmen. Das Jahr 1 (oder 0, falls es existiert) wird als Kalenderepoche bezeichnet und ist für jeden Kalender willkürlich. month ist eine positive ganze Zahl, die bei jedem Schritt um 1 erhöht wird, beginnend bei 1 und endend bei date.monthsInYear, und dann zurück auf 1 gesetzt wird, wenn das Jahr fortschreitet. day ist ebenfalls eine positive ganze Zahl, beginnt jedoch möglicherweise nicht bei 1 oder wird nicht jedes Mal um 1 erhöht, da politische Änderungen dazu führen können, dass Tage übersprungen oder wiederholt werden. Im Allgemeinen erhöht sich day jedoch monoton und wird zurückgesetzt, wenn der Monat fortschreitet.
1
0
date.monthsInYear
Zusätzlich zu year kann ein Jahr auch eindeutig durch die Kombination von era und eraYear für Kalender identifiziert werden, die Epochen verwenden. Der gregorianische Kalender verwendet beispielsweise die Epoche "CE" (Common Era) und "BCE" (Before Common Era), und das Jahr -1 entspricht { era: "bce", eraYear: 2 } (beachten Sie, dass das Jahr 0 immer für alle Kalender existiert; im gregorianischen Kalender entspricht es 1 v.Chr. aufgrund der astronomischen Jahrzählung). era ist eine kleingeschriebene Zeichenkette, und eraYear ist eine beliebige ganze Zahl, die null oder negativ sein oder sogar mit der Zeit abnehmen kann (normalerweise für die älteste Epoche).
-1
{ era: "bce", eraYear: 2 }
[!HINWEIS] Verwenden Sie immer era und eraYear als Paar; verwenden Sie nicht eine Eigenschaft, ohne die andere zu verwenden. Vermeiden Sie zudem Konflikte, indem Sie year und era/eraYear nicht kombinieren, wenn Sie ein Jahr angeben. Wählen Sie eine Jahresdarstellung und verwenden Sie sie konsequent. Seien Sie vorsichtig bei den folgenden falschen Annahmen über Jahre: Gehen Sie nicht davon aus, dass era und eraYear immer vorhanden sind; sie können undefined sein. Gehen Sie nicht davon aus, dass era eine benutzerfreundliche Zeichenkette ist; verwenden Sie toLocaleString(), um Ihr Datum zu formatieren. Gehen Sie nicht davon aus, dass zwei year-Werte aus verschiedenen Kalendern vergleichbar sind; verwenden Sie stattdessen die statische Methode compare(). Gehen Sie nicht davon aus, dass Jahre 365/366 Tage und 12 Monate haben; verwenden Sie stattdessen daysInYear und monthsInYear. Gehen Sie nicht davon aus, dass Schaltjahre (inLeapYear ist true) einen zusätzlichen Tag haben; sie können einen zusätzlichen Monat haben.
[!HINWEIS] Verwenden Sie immer era und eraYear als Paar; verwenden Sie nicht eine Eigenschaft, ohne die andere zu verwenden. Vermeiden Sie zudem Konflikte, indem Sie year und era/eraYear nicht kombinieren, wenn Sie ein Jahr angeben. Wählen Sie eine Jahresdarstellung und verwenden Sie sie konsequent.
Seien Sie vorsichtig bei den folgenden falschen Annahmen über Jahre:
undefined
compare()
true
Zusätzlich zu month kann ein Monat in einem Jahr auch eindeutig durch den monthCode identifiziert werden. monthCode entspricht normalerweise dem Namen des Monats, month jedoch nicht. Zum Beispiel sind bei lunisolaren Kalendern zwei Monate mit demselben monthCode, wobei einer zu einem Schaltjahr gehört und der andere nicht, unterschiedliche month-Werte, wenn sie nach dem Schaltmonat folgen, aufgrund der Einfügung eines zusätzlichen Monats.
[!HINWEIS] Um Konflikte zu vermeiden, kombinieren Sie month und monthCode nicht, wenn Sie einen Monat angeben. Wählen Sie eine Monatsdarstellung und verwenden Sie sie konsequent. month ist nützlicher, wenn Sie die Reihenfolge der Monate im Jahr benötigen (z.B. beim Durchlaufen der Monate), während monthCode nützlicher ist, wenn Sie den Namen des Monats benötigen (z.B. beim Speichern von Geburtstagen). Seien Sie vorsichtig bei den folgenden falschen Annahmen über Monate: Gehen Sie nicht davon aus, dass monthCode und month immer korrespondieren. Gehen Sie nicht von der Anzahl der Tage in einem Monat aus; verwenden Sie stattdessen daysInMonth. Gehen Sie nicht davon aus, dass monthCode eine benutzerfreundliche Zeichenkette ist; verwenden Sie toLocaleString(), um Ihr Datum zu formatieren. Speichern Sie im Allgemeinen den Namen der Monate nicht in einem Array oder Objekt. Auch wenn monthCode normalerweise dem Monatsnamen innerhalb eines Kalenders entspricht, empfehlen wir, stets den Monatsnamen zu berechnen, zum Beispiel mit date.toLocaleString("de-DE", { calendar: date.calendarId, month: "long" }).
[!HINWEIS] Um Konflikte zu vermeiden, kombinieren Sie month und monthCode nicht, wenn Sie einen Monat angeben. Wählen Sie eine Monatsdarstellung und verwenden Sie sie konsequent. month ist nützlicher, wenn Sie die Reihenfolge der Monate im Jahr benötigen (z.B. beim Durchlaufen der Monate), während monthCode nützlicher ist, wenn Sie den Namen des Monats benötigen (z.B. beim Speichern von Geburtstagen).
Seien Sie vorsichtig bei den folgenden falschen Annahmen über Monate:
date.toLocaleString("de-DE", { calendar: date.calendarId, month: "long" })
Zusätzlich zu day (was ein monatsbasiertes Indiz ist) kann ein Tag in einem Jahr auch eindeutig durch dayOfYear identifiziert werden. dayOfYear ist eine positive Ganzzahl, die sich bei jedem Schritt um 1 erhöht, beginnend bei 1 und endend bei date.daysInYear.
date.daysInYear
Das Konzept einer "Woche" ist mit keinem astronomischen Ereignis verbunden, sondern ein kulturelles Konstrukt. Während die häufigste Länge 7 Tage beträgt, können Wochen auch 4, 5, 6, 8 oder mehr Tage haben — oder sogar gar keine feste Anzahl von Tagen. Um die spezifische Anzahl von Tagen der Woche eines Datums zu erhalten, verwenden Sie daysInWeek des Datums. Temporal identifiziert Wochen durch die Kombination von weekOfYear und yearOfWeek. weekOfYear ist eine positive Ganzzahl, die sich bei jedem Schritt um 1 erhöht, beginnend bei 1 und dann zu 1 zurücksetzt, wenn das Jahr fortschreitet. yearOfWeek ist im Allgemeinen dasselbe wie year, kann aber zu Beginn oder Ende jedes Jahres anders sein, weil eine Woche zwei Jahre überqueren kann, und yearOfWeek eines der beiden Jahre basierend auf den Regeln des Kalenders auswählt.
7
[!HINWEIS] Verwenden Sie immer weekOfYear und yearOfWeek als Paar; verwenden Sie nicht weekOfYear und year. Seien Sie vorsichtig bei den folgenden falschen Annahmen über Wochen: Gehen Sie nicht davon aus, dass weekOfYear und yearOfWeek immer vorhanden sind; sie können undefined sein. Gehen Sie nicht davon aus, dass Wochen immer 7 Tage haben; verwenden Sie daysInWeek. Beachten Sie, dass die aktuelle Temporal-API keine Jahr-Woche-Daten unterstützt, sodass Sie keine Daten mit diesen Eigenschaften konstruieren oder Daten in Jahr-Woche-Darstellungen serialisieren können. Sie sind nur informative Eigenschaften.
[!HINWEIS] Verwenden Sie immer weekOfYear und yearOfWeek als Paar; verwenden Sie nicht weekOfYear und year.
Seien Sie vorsichtig bei den folgenden falschen Annahmen über Wochen:
Alle Temporal-Klassen können unter Verwendung des Formats gemäß RFC 9557 serialisiert und deserialisiert werden, das auf ISO 8601 / RFC 3339 basiert. Das Format in seiner vollständigen Form ist wie folgt (Leerzeichen dienen nur der Lesbarkeit und sollten im tatsächlichen String nicht vorhanden sein):
YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm [time_zone_id] [u-ca=calendar_id]
Verschiedene Klassen haben unterschiedliche Anforderungen an die Anwesenheit jeder Komponente. In der Dokumentation jeder Klasse finden Sie einen Abschnitt mit dem Titel "RFC 9557 Format", der das von dieser Klasse erkannte Format spezifiziert.
Das ist sehr ähnlich zum Datums-Zeit-String-Format, das von Date verwendet wird, welches ebenfalls auf ISO 8601 basiert. Die Hauptneuerung ist die Möglichkeit, Mikro- und Nanosekundenkomponenten anzugeben sowie die Zeitzone und das Kalendersystem zu spezifizieren.
Alle Temporal-Objekte, die ein bestimmtes Kalendariumdatum darstellen, legen eine ähnliche Grenze für den Bereich der darstellbaren Daten fest, die ±108 Tage (einschließlich) ab der Unix-Epoche oder den Bereich der Momente von -271821-04-20T00:00:00 bis +275760-09-13T00:00:00 umfasst. Dies ist derselbe Bereich wie gültige Daten. Genauer gesagt:
-271821-04-20T00:00:00
+275760-09-13T00:00:00
-271821-04-19T00:00:00
+275760-09-14T00:00:00
-271821-04-19
+275760-09-13
-271821-04
+275760-09
-271821-03
Die Temporal-Objekte werden sich weigern, eine Instanz zu konstruieren, die ein Datum/Zeitp hätte, das über diesem Limit liegt. Dies schließt ein:
from()
Stellt einen Unterschied zwischen zwei Zeitpunkten dar, der in der Datums-/Uhrzeitarithmetik verwendet werden kann. Es wird grundlegend als Kombination von Jahren, Monaten, Wochen, Tagen, Stunden, Minuten, Sekunden, Millisekunden, Mikrosekunden und Nanosekunden-Werten dargestellt.
Stellt einen einzigartigen Punkt in der Zeit mit Nanosekundenpräzision dar. Es wird grundlegend als die Anzahl der Nanosekunden seit der Unix-Epoche (Mitternacht zu Beginn des 1. Januar 1970, UTC) dargestellt, ohne jegliche Zeitzone oder Kalendersystem.
Bietet Methoden zum Abrufen der aktuellen Zeit in verschiedenen Formaten.
Stellt ein Kalenderdatum dar (ein Datum ohne Zeit oder Zeitzone); zum Beispiel ein Ereignis in einem Kalender, das den ganzen Tag unabhängig von der Zeitzone geschieht, in der es stattfindet. Es wird grundlegend als ISO 8601-Kalenderdatum mit Jahr-, Monat- und Tagefeldern und einem zugehörigen Kalendersystem dargestellt.
Stellt ein Datum (Kalenderdatum) und eine Uhrzeit (Wanduhrzeit) ohne Zeitzone dar. Es wird grundlegend als Kombination aus einem Datum (mit einem zugehörigen Kalendersystem) und einer Zeit dargestellt.
Stellt den Monat und Tag eines Kalenderdatums dar, ohne Jahr oder Zeitzone; zum Beispiel ein Ereignis auf einem Kalender, das jedes Jahr wiederkehrt und den ganzen Tag über geschieht. Es wird grundlegend als ISO 8601-Kalenderdatum mit Jahr-, Monat- und Tagefeldern und einem zugehörigen Kalendersystem dargestellt. Das Jahr wird verwendet, um den Monat-Tag in nicht-ISO-Kalendersystemen zu klären.
Stellt eine Zeit ohne Datum oder Zeitzone dar; zum Beispiel ein wiederkehrendes Ereignis, das jeden Tag zur gleichen Zeit stattfindet. Es wird grundlegend als Kombination von Stunde, Minute, Sekunde, Millisekunde, Mikrosekunde und Nanosekunde dargestellt.
Stellt das Jahr und den Monat eines Kalenderdatums dar, ohne Tag oder Zeitzone; zum Beispiel ein Ereignis in einem Kalender, das den ganzen Monat über stattfindet. Es wird grundlegend als ISO 8601-Kalenderdatum mit Jahr-, Monat- und Tagefeldern und einem zugehörigen Kalendersystem dargestellt. Der Tag wird verwendet, um das Jahr-Monat in nicht-ISO-Kalendersystemen zu klären.
Stellt ein Datum und eine Uhrzeit mit einer Zeitzone dar. Es wird grundlegend als Kombination eines Zeitpunkts, einer Zeitzone und eines Kalendersystems dargestellt.
Temporal[Symbol.toStringTag]
Der Anfangswert der [Symbol.toStringTag]-Eigenschaft ist der String "Temporal". Diese Eigenschaft wird in Object.prototype.toString() verwendet.
[Symbol.toStringTag]
"Temporal"
Object.prototype.toString()
JavaScript aktivieren, um diese Browser-Kompatibilitätstabelle anzuzeigen.
Intl.DateTimeFormat
Intl.RelativeTimeFormat
Intl.DurationFormat