Temporal.Duration
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.
Das Temporal.Duration
-Objekt repräsentiert eine Differenz zwischen zwei Zeitpunkten, die für Datums-/Zeitberechnungen verwendet werden kann. Es wird grundsätzlich als Kombination aus Jahren, Monaten, Wochen, Tagen, Stunden, Minuten, Sekunden, Millisekunden, Mikrosekunden und Nanosekunden dargestellt.
Beschreibung
ISO 8601-Dauerformat
Duration
-Objekte können mithilfe des ISO 8601-Dauerformats serialisiert und geparst werden (mit einigen ECMAScript-Spezifikationen). Die Zeichenkette hat folgendes Format (Leerzeichen dienen nur der Lesbarkeit und sollten in der tatsächlichen Zeichenkette nicht vorhanden sein):
±P nY nM nW nD T nH nM nS
±
Optional-
Ein optionales Vorzeichen (
+
oder-
), das eine positive oder negative Dauer darstellt. Standardmäßig positiv. P
-
Ein Pflicht-Zeichen
P
oderp
, das für "Periode" steht. nY
,nM
,nW
,nD
,nH
,nM
,nS
-
Eine Zahl, gefolgt von einem Pflicht-Zeichen, das die Anzahl an Jahren (
Y
), Monaten (M
), Wochen (W
), Tagen (D
), Stunden (H
), Minuten (M
) oder Sekunden (S
) darstellt. Alle vorhandenen Komponenten außer der letzten müssen ganze Zahlen sein. Die letzte Komponente – falls es sich um eine Zeitkomponente (Stunden, Minuten oder Sekunden) handelt – kann einen Bruchteil von 1 bis 9 Stellen enthalten, eingeleitet durch einen Punkt oder ein Komma, wiePT0.0021S
oderPT1.1H
. Null-Komponenten können weggelassen werden, aber mindestens eine Komponente muss vorhanden sein (auch wenn der Wert null ist, in dem Fall ist die Dauer null). T
-
Ein Pflicht-Zeichen
T
odert
, das den Datums- vom Zeitteil abtrennt; es muss vorhanden sein, wenn und nur wenn mindestens eine Komponente danach existiert.
Beispiele:
ISO 8601 | Bedeutung |
---|---|
P1Y1M1DT1H1M1.1S |
1 Jahr, 1 Monat, 1 Tag, 1 Stunde, 1 Minute, 1 Sekunde und 100 Millisekunden |
P40D |
40 Tage |
P1Y1D |
1 Jahr und 1 Tag |
P3DT4H59M |
3 Tage, 4 Stunden und 59 Minuten |
PT2H30M |
2 Stunden und 30 Minuten |
P1M |
1 Monat |
PT1M |
1 Minute |
PT0.0021S |
2,1 Millisekunden (2 Millisekunden und 100 Mikrosekunden) |
PT0S |
Null (kanonische Darstellung) |
P0D |
Null |
Hinweis:
Laut dem ISO 8601-1-Standard dürfen Wochen nicht zusammen mit anderen Einheiten auftreten, und Zeitspannen können nur positiv sein. Als Erweiterungen zum Standard erlaubt ISO 8601-2, welches von Temporal genutzt wird, ein Vorzeichen am Anfang der Zeichenkette und die Kombination von Wochen mit anderen Einheiten. Daher sollten Sie beachten, dass andere Programme möglicherweise Zeichenketten wie P3W1D
, +P1M
oder -P1M
nicht akzeptieren, wenn Ihre Dauer so serialisiert wurde.
Beim Serialisieren respektiert die Ausgabe die gespeicherten Komponenten so weit wie möglich und bewahrt unausgeglichene Komponenten. Subsekunden-Komponenten werden jedoch als einzelne Bruchteile von Sekunden serialisiert, wodurch ihre genauen Werte, falls unausgeglichen, verloren gehen können. Das Pluszeichen wird bei positiven Dauern weggelassen. Die Null-Dauer wird immer als PT0S
serialisiert.
Kalendermäßige Zeitspannen
Eine kalendermäßige Zeitspanne enthält eine der Kalender-Einheiten: Wochen, Monate und Jahre. Eine nicht-kalendermäßige Zeitspanne ist portabel und kann bei Datums-/Zeitberechnungen ohne Kalenderinformationen verwendet werden, da sie eine feste Zeitmenge eindeutig repräsentiert. Eine kalendermäßige Zeitspanne ist jedoch nicht portabel, da die Anzahl der Tage in einem Monat oder Jahr vom Kalendersystem und dem Referenzzeitpunkt abhängt. Daher führt der Versuch, eine kalendermäßige Zeitspanne zu einer Berechnung hinzuzufügen, zu einem Fehler, da Zeitspannen keinen Kalender enthalten. Zum Beispiel bedeutet "1 Monat" im Mai des Gregorianischen Kalenders "31 Tage", aber im April bedeutet es "30 Tage". Um kalendermäßige Zeitspannen zu addieren oder zu subtrahieren, müssen Sie diese zu einem Datum hinzufügen:
const dur1 = Temporal.Duration.from({ years: 1 });
const dur2 = Temporal.Duration.from({ months: 1 });
dur1.add(dur2); // RangeError: for calendar duration arithmetic, use date arithmetic relative to a starting point
const startingPoint = Temporal.PlainDate.from("2021-01-01"); // ISO 8601 calendar
startingPoint.add(dur1).add(dur2).since(startingPoint); // "P396D"
Andere Operationen, round()
, total()
und compare()
, nehmen die Option relativeTo
, um die notwendigen Kalender- und Referenzzeitinformationen bereitzustellen. Diese Option kann eine Temporal.PlainDate
, Temporal.PlainDateTime
, Temporal.ZonedDateTime
oder ein anderes Objekt bzw. eine Zeichenkette sein, die konvertierbar ist mit Temporal.ZonedDateTime.from()
(wenn die Option timeZone
angegeben ist oder die Zeichenkette eine Zeitzonenanmerkung enthält), oder Temporal.PlainDate.from()
.
Beachten Sie, dass die Umrechnung von days
in hours
technisch ebenfalls mehrdeutig ist, da sich die Länge eines Tages durch Zeitversatzänderungen wie Sommerzeit variieren kann. Sie können einen Zonened relativeTo
-Wert angeben, um diese Änderungen zu berücksichtigen; andernfalls werden standardmäßig 24-Stunden-Tage angenommen.
Ausgleich von Zeitspannen
Es gibt viele Möglichkeiten, dieselbe Zeitspanne darzustellen: Beispielsweise sind "1 Minute und 30 Sekunden" und "90 Sekunden" gleichwertig. Je nach Kontext kann jedoch eine Darstellung geeigneter sein als die andere. Daher bewahrt das Duration
-Objekt im Allgemeinen die Eingabewerte so weit wie möglich, sodass das Format bei der Ausgabe Ihren Erwartungen entspricht.
Jede Komponente einer Zeitspanne hat ihre optimale Reichweite; Stunden sollten von 0 bis 23 reichen, Minuten von 0 bis 59 und so weiter. Wenn eine Komponente ihren optimalen Bereich überschreitet, wird der Überschuss möglicherweise in die nächsthöhere Komponente "übertragen". Um zu übertragen, müssen wir die Frage "Wie viele X sind in einem Y?" beantworten, was für Kalender-Einheiten komplex ist, daher wird in diesem Fall ein Kalender benötigt. Beachten Sie auch, dass days
standardmäßig direkt in months
übertragen werden; die Wocheneinheit wird nur dann einbezogen, wenn dies explizit angefordert wird. Wenn wir so viel wie möglich übertragen, wird das endgültige Ergebnis, bei dem alle Komponenten innerhalb ihres optimalen Bereichs liegen, als "ausgeglichene" Dauer bezeichnet. Unausschöpfte Zeitspannen treten in der Regel in einer "kopflastigen" Form auf, bei der die größte Einheit unausgeglichen ist (z. B. "27 Stunden und 30 Minuten"); andere Formen, wie "23 Stunden und 270 Minuten", sind selten zu sehen.
Die Methode round()
gleicht die Zeitspanne immer in die "kopflastige" Form aus, bis zur largestUnit
-Option. Mit einer manuellen largestUnit
-Option, die groß genug ist, können Sie die Dauer vollständig ausgleichen. Ebenso gleichen die Methoden add()
und subtract()
die Ergebnisdauer an die größte Einheit der Eingabedauern an.
Beachten Sie, dass das ISO 8601-Dauerformat Subsekunden-Komponenten als einzelne Bruchzahlen darstellt, es daher nicht möglich ist, unausgeglichene Subsekunden-Komponenten während der Serialisierung im Standardformat zu bewahren. Zum Beispiel wird "1000 Millisekunden" als "PT1S"
serialisiert und dann als "1 Sekunde" deserialisiert. Wenn Sie die Größe der Subsekunden-Komponenten bewahren möchten, müssen Sie dies manuell als JSON-Objekt serialisieren (da die Methode toJSON()
die Dauer standardmäßig im ISO 8601-Format serialisiert).
Vorzeichen der Zeitspannen
Da eine Zeitspanne eine Differenz zwischen zwei Zeitpunkten darstellt, kann sie positiv, negativ oder null sein. Wenn Sie beispielsweise Ereigniszeiten relativ anzeigen, können negative Zeitspannen Ereignisse in der Vergangenheit darstellen, während positive Zeitspannen für die Zukunft stehen. In unserer Darstellung mit einer Kombination aus Zeitkomponenten wird das Vorzeichen in jeder Komponente gespeichert: Eine negative Zeitspanne hat immer alle Komponenten negativ (oder null), und eine positive Zeitspanne hat immer alle Komponenten positiv (oder null). Das Erstellen einer Zeitspanne mit Komponenten von gemischten Vorzeichen ist ungültig und wird vom Konstruktor oder der Methode with()
abgelehnt. Die Methoden add()
und subtract()
gleichen die Ergebnisdauer aus, um gemischte Vorzeichen zu vermeiden.
Konstruktor
Temporal.Duration()
Experimentell-
Erstellt ein neues
Temporal.Duration
-Objekt, indem die zugrunde liegenden Daten direkt übergeben werden.
Statische Methoden
Temporal.Duration.compare()
Experimentell-
Gibt eine Zahl (-1, 0 oder 1) zurück, die angibt, ob die erste Zeitspanne kürzer, gleich oder länger als die zweite ist.
Temporal.Duration.from()
Experimentell-
Erstellt ein neues
Temporal.Duration
-Objekt aus einem anderenTemporal.Duration
-Objekt, einem Objekt mit Zeitspanneigenschaften oder einem ISO 8601-String.
Instanzeigenschaften
Diese Eigenschaften sind auf Temporal.Duration.prototype
definiert und werden von allen Temporal.Duration
-Instanzen gemeinsam genutzt.
Temporal.Duration.prototype.blank
Experimentell-
Gibt einen Wert
true
zurück, wenn diese Dauer eine Null-Dauer darstellt, undfalse
, wenn nicht. Entsprichtduration.sign === 0
. Temporal.Duration.prototype.constructor
-
Die Konstruktorfunktion, die das Instanz-Objekt erstellt hat. Für
Temporal.Duration
-Instanzen ist der Anfangswert derTemporal.Duration()
-Konstruktor. Temporal.Duration.prototype.days
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Tage in der Zeitspanne darstellt.
Temporal.Duration.prototype.hours
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Stunden in der Zeitspanne darstellt.
Temporal.Duration.prototype.microseconds
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Mikrosekunden in der Zeitspanne darstellt.
Temporal.Duration.prototype.milliseconds
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Millisekunden in der Zeitspanne darstellt.
Temporal.Duration.prototype.minutes
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Minuten in der Zeitspanne darstellt.
Temporal.Duration.prototype.months
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Monate in der Zeitspanne darstellt.
Temporal.Duration.prototype.nanoseconds
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Nanosekunden in der Zeitspanne darstellt.
Temporal.Duration.prototype.seconds
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Sekunden in der Zeitspanne darstellt.
Temporal.Duration.prototype.sign
Experimentell-
Gibt
1
zurück, wenn diese Zeitspanne positiv ist,-1
, wenn sie negativ ist, und0
, wenn sie null ist. Temporal.Duration.prototype.weeks
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Wochen in der Zeitspanne darstellt.
Temporal.Duration.prototype.years
Experimentell-
Gibt eine Ganzzahl zurück, die die Anzahl der Jahre in der Zeitspanne darstellt.
Temporal.Duration.prototype[Symbol.toStringTag]
-
Der Anfangswert der
[Symbol.toStringTag]
-Eigenschaft ist die Zeichenkette"Temporal.Duration"
. Diese Eigenschaft wird inObject.prototype.toString()
verwendet.
Instanzmethoden
Temporal.Duration.prototype.abs()
Experimentell-
Gibt ein neues
Temporal.Duration
-Objekt mit dem Absolutwert dieser Zeitspanne zurück (alle Felder behalten dieselbe Größe, aber das Vorzeichen wird positiv). Temporal.Duration.prototype.add()
Experimentell-
Gibt ein neues
Temporal.Duration
-Objekt zurück, das die Summe aus dieser Zeitspanne und einer gegebenen Zeitspanne darstellt (in einer Form, die mitTemporal.Duration.from()
konvertierbar ist). Das Ergebnis ist ausgeglichen. Temporal.Duration.prototype.negated()
Experimentell-
Gibt ein neues
Temporal.Duration
-Objekt mit dem negierten Wert dieser Zeitspanne zurück (alle Felder behalten dieselbe Größe, aber das Vorzeichen wird umgekehrt). Temporal.Duration.prototype.round()
Experimentell-
Gibt ein neues
Temporal.Duration
-Objekt zurück, das auf die angegebene kleinste Einheit gerundet und/oder ausgeglichen auf die angegebene größte Einheit wird. Temporal.Duration.prototype.subtract()
Experimentell-
Gibt ein neues
Temporal.Duration
-Objekt zurück, das die Differenz zwischen dieser Zeitspanne und einer gegebenen Zeitspanne darstellt (in einer Form, die mitTemporal.Duration.from()
konvertierbar ist). Entspricht dem Addieren des negierten Wertes der anderen Zeitspanne. Temporal.Duration.prototype.toJSON()
Experimentell-
Gibt eine Zeichenkette zurück, die diese Zeitspanne im gleichen ISO 8601-Format wie ein Aufruf von
toString()
darstellt. Soll implizit vonJSON.stringify()
aufgerufen werden. Temporal.Duration.prototype.toLocaleString()
Experimentell-
Gibt eine zeichenkettendarstellung dieser Zeitspanne zurück, die sprachabhängig ist. In Implementierungen mit Unterstützung für die
Intl.DurationFormat
-API delegiert diese Methode anIntl.DurationFormat
. Temporal.Duration.prototype.toString()
Experimentell-
Gibt eine Zeichenkette zurück, die diese Zeitspanne im ISO 8601-Format darstellt.
Temporal.Duration.prototype.total()
Experimentell-
Gibt eine Zahl zurück, die die gesamte Zeitspanne in der angegebenen Einheit darstellt.
Temporal.Duration.prototype.valueOf()
Experimentell-
Wirft einen
TypeError
, um zu verhindern, dassTemporal.Duration
-Instanzen implizit in primitive Werte umgewandelt werden, wenn sie in arithmetischen oder Vergleichsoperationen verwendet werden. Temporal.Duration.prototype.with()
Experimentell-
Gibt ein neues
Temporal.Duration
-Objekt zurück, das diese Zeitspanne mit einigen durch neue Werte ersetzten Feldern darstellt.
Spezifikationen
Specification |
---|
Temporal proposal # sec-temporal-duration-objects |
Browser-Kompatibilität
Loading BCD table