Temporal.Duration

Duration Objekte können unter Verwendung des ISO 8601-Dauerformats (mit einigen Erweiterungen, die von ECMAScript spezifiziert sind) serialisiert und geparst werden. Der String hat folgendes Format (Leerzeichen sind nur zur Lesbarkeit vorhanden und sollten im eigentlichen String nicht enthalten sein):

±P nY nM nW nD T nH nM nS

± Optional

Ein optionales Plus- oder Minuszeichen (+ oder -), welches positive oder negative Dauer darstellt. Standard ist positiv.

P

Ein wörtlicher Buchstabe P oder p, der für "Period" steht.

nY, nM, nW, nD, nH, nM, nS

Eine Zahl gefolgt von einem wörtlichen Buchstaben, der die Anzahl der Jahre (Y), Monate (M), Wochen (W), Tage (D), Stunden (H), Minuten (M) oder Sekunden (S) darstellt. Alle außer der letzten vorhandenen Komponente müssen Ganzzahlen sein. Die letzte Komponente, wenn es eine Zeitkomponente (Stunden, Minuten oder Sekunden) ist, kann einen Bruchteil von 1 bis 9 Ziffern haben, vorneweg mit einem Punkt oder Komma, wie PT0.0021S oder PT1.1H. Jegliche null Komponenten können weggelassen werden, aber es sollte mindestens eine Komponente vorhanden sein (selbst wenn sie den Wert null hat, in diesem Fall ist die Dauer null).

T

Ein wörtlicher Buchstabe T oder t, der den Datumsteil vom Zeitteil trennt, der nur dann vorhanden sein sollte, wenn mindestens eine Komponente nach ihm folgt.

Hier sind einige Beispiele:

Bei der Serialisierung respektiert die Ausgabe die gespeicherten Komponenten soweit wie möglich und bewahrt unausgeglichene Komponenten. Allerdings werden Untersekunden-Komponenten als eine einzige gebrochene Sekunde serialisiert, sodass deren genaue Werte, falls unausgeglichen, verloren gehen könnten. Das Pluszeichen wird für positive Dauern weggelassen. Die Null-Dauer wird immer als PT0S serialisiert.

Eine Kalenderdauer ist eine, die eine der Kalendereinheiten enthält: Wochen, Monate und Jahre. Eine Nicht-Kalender-Dauer ist portabel und kann ohne Kalendersysteminformationen in der Datums-/Zeitrechnung verwendet werden, da sie eindeutig eine feste Zeitdauer repräsentiert. Eine Kalenderdauer ist jedoch nicht portabel, da die Anzahl der Tage in einem Monat oder Jahr vom Kalendersystem und vom Referenzzeitpunkt abhängt. Daher führt der Versuch, mathematische Operationen auf Kalenderdauern auszuführen, zu einem Fehler, da Dauern selbst keine Kalenderinformationen nachverfolgen. Beispielsweise, wenn wir im Mai des gregorianischen Kalenders sind, dann ist "1 Monat" gleich "31 Tage", aber wenn wir im April sind, dann wird "1 Monat" zu "30 Tage". Um Kalenderdauern hinzuzufügen oder zu subtrahieren, müssen Sie sie stattdessen zu Daten hinzufügen:

const dur1 = Temporal.Duration.from({ years: 1 });
const dur2 = Temporal.Duration.from({ months: 1 });

dur1.add(dur2); // RangeError: can't compare durations when "relativeTo" is undefined

const startingPoint = Temporal.PlainDate.from("2021-01-01"); // ISO 8601 calendar
startingPoint.add(dur1).add(dur2).since(startingPoint); // "P396D"

Andere Operationen, einschließlich round(), total(), und compare(), benötigen eine relativeTo-Option, um die notwendigen Kalender- und Referenzzeitinformationen bereitzustellen. Diese Option kann ein Temporal.PlainDate, Temporal.PlainDateTime, Temporal.ZonedDateTime sein, oder anderweitig ein Objekt oder String, das mit Temporal.ZonedDateTime.from() (wenn die timeZone-Option bereitgestellt wird oder der String eine Zeitzonenanmerkung enthält) oder Temporal.PlainDateTime.from() konvertierbar ist.

Beachten Sie, dass die Umwandlung von days nach hours technisch auch mehrdeutig ist, da die Länge eines Tages aufgrund von Verschiebungsänderungen, wie der Sommerzeit, variieren kann. Sie können ein zoniertes relativeTo bereitstellen, um diese Änderungen zu berücksichtigen; andernfalls werden 24-Stunden-Tage angenommen.

Es gibt viele Möglichkeiten, dieselbe Dauer darzustellen: zum Beispiel sind "1 Minute und 30 Sekunden" und "90 Sekunden" gleichwertig. Je nach Kontext kann jedoch eine Darstellung angemessener sein als die andere. Daher bewahrt das Duration-Objekt im Allgemeinen die Eingabewerte so weit wie möglich, sodass es beim Formatieren so angezeigt wird, wie Sie es erwarten.

Jede Komponente einer Dauer hat ihren optimalen Bereich; Stunden sollten von 0 bis 23, Minuten von 0 bis 59 sein, und so weiter. Wenn eine Komponente ihren optimalen Bereich überschreitet, kann der Überschuss in die nächste größere Komponente "übertragen" werden. Um zu übertragen, müssen wir die Frage beantworten "Wie viele X sind in einem Y?", was eine komplizierte Frage für Kalendereinheiten ist; in diesem Fall wird ein Kalender benötigt. Beachten Sie auch, dass standardmäßig days direkt in months übertragen werden; die Wochen-Einheit wird nur übertragen, wenn explizit angefordert. Wenn wir so viel wie möglich übertragen, wird das Endresultat, bei dem alle Komponenten in ihrem optimalen Bereich liegen, als "ausgeglichene" Dauer bezeichnet. Unaustarierte Dauern treten normalerweise in der "stark belasteten" Form auf, bei der die größte Einheit unaustariert ist (z. B. "27 Stunden und 30 Minuten"); andere Formen, wie "23 Stunden und 270 Minuten", sind selten zu sehen.

Die round() Methode balanciert die Dauer immer in der "stark belasteten" Form aus, bis zur largestUnit-Option. Mit einer manuellen largestUnit-Option, die groß genug ist, können Sie die Dauer vollständig austarieren. Ähnlich balancieren die add() und subtract() Methoden die Ergebnisdauer zur größten Einheit der Eingabedauern.

Beachten Sie, dass es aufgrund des ISO 8601-Dauerformats nicht möglich ist, unaustarierte Untersekundenkomponenten während der Serialisierung mit dem Standardformat beizubehalten, da diese als eine einzige gebrochene Zahl dargestellt werden. Zum Beispiel wird "1000 Millisekunden" als "PT1S" serialisiert und dann als "1 Sekunde" deserialisiert. Wenn Sie die Größenordnungen der Untersekundenkomponenten beibehalten müssen, müssen Sie diese manuell als JSON-Objekt serialisieren (da standardmäßig die toJSON() Methode die Dauer im ISO 8601-Format serialisiert).

Da eine Dauer ein Unterschied zwischen zwei Zeitpunkten ist, kann sie positiv, negativ oder null sein. Wenn beispielsweise Ereigniszeiten in relativer Zeit angezeigt werden, können negative Dauern Ereignisse in der Vergangenheit darstellen und positive Dauern für die Zukunft. In unserer Darstellung mit einer Kombination von Zeitkomponenten wird das Zeichen innerhalb jeder Komponente gespeichert: Eine negative Dauer hat immer alle Komponenten negativ (oder null), und eine positive Dauer hat immer alle Komponenten positiv (oder null). Eine Dauer mit Komponenten gemischter Vorzeichen zu konstruieren ist ungültig und wird vom Konstruktor oder der with() Methode abgelehnt. Die add() und subtract() Methoden balancieren die Ergebnisdauer aus, um gemischte Vorzeichen zu vermeiden.

Temporal.Duration() Experimentell

Erstellt ein neues Temporal.Duration Objekt, indem die zugrundeliegenden Daten direkt bereitgestellt werden.

Temporal.Duration.compare() Experimentell

Gibt eine Zahl (-1, 0 oder 1) zurück, die angibt, ob die erste Dauer kürzer, gleich oder länger als die zweite ist.

Temporal.Duration.from() Experimentell

Erstellt ein neues Temporal.Duration Objekt aus einem anderen Temporal.Duration Objekt, einem Objekt mit Dauereigenschaften oder einem ISO 8601-String.

Diese Eigenschaften sind auf Temporal.Duration.prototype definiert und werden von allen Temporal.Duration Instanzen geteilt.

Temporal.Duration.prototype.blank Experimentell

Gibt einen Boolean-Wert zurück, der true ist, wenn diese Dauer eine Null-Dauer darstellt, und ansonsten false. Equivalent zu duration.sign === 0.

Temporal.Duration.prototype.constructor

Die Konstrukturfunktion, die das Instanzobjekt erstellt hat. Für Temporal.Duration Instanzen ist der initiale Wert der Temporal.Duration() Konstruktor.

Temporal.Duration.prototype.days Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Tage in der Dauer darstellt.

Temporal.Duration.prototype.hours Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Stunden in der Dauer darstellt.

Temporal.Duration.prototype.microseconds Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Mikrosekunden in der Dauer darstellt.

Temporal.Duration.prototype.milliseconds Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Millisekunden in der Dauer darstellt.

Temporal.Duration.prototype.minutes Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Minuten in der Dauer darstellt.

Temporal.Duration.prototype.months Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Monate in der Dauer darstellt.

Temporal.Duration.prototype.nanoseconds Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Nanosekunden in der Dauer darstellt.

Temporal.Duration.prototype.seconds Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Sekunden in der Dauer darstellt.

Temporal.Duration.prototype.sign Experimentell

Gibt 1 zurück, wenn diese Dauer positiv ist, -1, wenn negativ, und 0, wenn sie null ist.

Temporal.Duration.prototype.weeks Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Wochen in der Dauer darstellt.

Temporal.Duration.prototype.years Experimentell

Gibt eine Ganzzahl zurück, die die Anzahl der Jahre in der Dauer darstellt.

Temporal.Duration.prototype[Symbol.toStringTag]

Der anfängliche Wert der [Symbol.toStringTag] Eigenschaft ist der String "Temporal.Duration". Diese Eigenschaft wird in Object.prototype.toString() verwendet.

Temporal.Duration.prototype.abs() Experimentell

Gibt ein neues Temporal.Duration Objekt mit dem absoluten Wert dieser Dauer zurück (alle Felder behalten die gleiche Größe, aber das Vorzeichen wird positiv).

Temporal.Duration.prototype.add() Experimentell

Gibt ein neues Temporal.Duration Objekt mit der Summe dieser Dauer und einer gegebenen Dauer (in einer Form konvertierbar durch Temporal.Duration.from()) zurück. Das Ergebnis ist ausgeglichen.

Temporal.Duration.prototype.negated() Experimentell

Gibt ein neues Temporal.Duration Objekt mit dem negativen Wert dieser Dauer zurück (alle Felder behalten die gleiche Größe, aber das Vorzeichen wird umgekehrt).

Temporal.Duration.prototype.round() Experimentell

Gibt ein neues Temporal.Duration Objekt mit der Dauer, gerundet auf die gegebene kleinste Einheit und/oder ausgeglichen auf die gegebene größte Einheit zurück.

Temporal.Duration.prototype.subtract() Experimentell

Gibt ein neues Temporal.Duration Objekt mit dem Unterschied zwischen dieser Dauer und einer gegebenen Dauer (in einer Form konvertierbar durch Temporal.Duration.from()) zurück. Equivalent zum Hinzufügen des negativen Wertes der anderen Dauer.

Temporal.Duration.prototype.toJSON() Experimentell

Gibt einen String zurück, der diese Dauer im gleichen ISO 8601-Format wie beim Aufrufen von toString() darstellt. Soll von JSON.stringify() implizit aufgerufen werden.

Temporal.Duration.prototype.toLocaleString() Experimentell

Gibt einen String mit einer sprachsensitiven Darstellung dieser Dauer zurück. In Implementierungen mit Unterstützung für die Intl.DurationFormat API delegiert diese Methode an Intl.DurationFormat.

Temporal.Duration.prototype.toString() Experimentell

Gibt einen String zurück, der diese Dauer im ISO 8601-Format darstellt.

Temporal.Duration.prototype.total() Experimentell

Gibt eine Zahl zurück, die die Gesamtdauer in der gegebenen Einheit darstellt.

Temporal.Duration.prototype.valueOf() Experimentell

Wirft einen TypeError, der verhindert, dass Temporal.Duration Instanzen implizit in primitive Typen 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 Dauer mit einigen Feldern, die durch neue Werte ersetzt wurden, darstellt.

• Temporal