Temporal.ZonedDateTime.prototype.add()
Eingeschränkt verfügbar
Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.
Want more support for this feature? Tell us why.
Die add() Methode von Temporal.ZonedDateTime-Instanzen gibt ein neues Temporal.ZonedDateTime-Objekt zurück, das diesen Datum-Uhrzeit-Wert um eine gegebene Dauer nach vorne verschoben darstellt (in einer Form, die von Temporal.Duration.from() konvertierbar ist).
Syntax
add(duration)
add(duration, options)
Parameter
duration-
Ein String, ein Objekt oder eine
Temporal.Duration-Instanz, die eine hinzuzufügende Dauer zu diesem Datum-Uhrzeit-Wert darstellt. Es wird in einTemporal.Duration-Objekt umgewandelt, indem derselbe Algorithmus verwendet wird wie beiTemporal.Duration.from(). optionsOptional-
Ein Objekt mit der folgenden Eigenschaft:
overflowOptional-
Ein String, der das Verhalten spezifiziert, wenn eine Datumskomponente außerhalb des Bereichs liegt. Mögliche Werte sind:
"constrain"(Standard)-
Die Datumskomponente wird auf den gültigen Bereich begrenzt.
"reject"-
Ein
RangeErrorwird ausgelöst, wenn die Datumskomponente außerhalb des Bereichs liegt.
Rückgabewert
Ein neues Temporal.ZonedDateTime-Objekt, das das Datum-Uhrzeit, spezifiziert durch das ursprüngliche ZonedDateTime, plus der Dauer darstellt.
Ausnahmen
RangeError-
Wird ausgelöst, wenn das Ergebnis nicht im darstellbaren Bereich liegt, was ±108 Tage, oder etwa ±273.972,6 Jahre, ab der Unix-Epoche umfasst.
Beschreibung
Informationen darüber, wie Kalenderdauern hinzugefügt werden, siehe Temporal.PlainDate.prototype.add().
Addition und Subtraktion werden gemäß den in RFC 5545 (iCalendar) definierten Regeln durchgeführt:
- Der Datumsanteil einer Dauer wird durch Kalenderarithmetik addiert/subtrahiert; das bedeutet, der Datumsanteil wird zu seinem
PlainDateTimemitTemporal.PlainDateTime.prototype.add()addiert und das Ergebnis dann in derselben Zeitzone interpretiert. Das Ergebnis passt sich automatisch an die Sommerzeitregelungen destimeZone-Feldes dieser Instanz an. Beispielsweise ist2024-11-03T01:00:00-04:00[America/New_York]plus ein Tag2024-11-04T01:00:00-05:00[America/New_York], als ob der Tag 25 Stunden hätte.- Wenn das Datum-Uhrzeit mehrdeutig oder aufgrund einer Zeitzonen-Offset-Übergangs ungültig ist, wird es mit dem
disambiguation: "compatible"-Verhalten gelöst: Der spätere der beiden möglichen Zeitpunkte wird für übersprungene Zeitanpassungen verwendet und der frühere der beiden möglichen Zeitpunkte wird für wiederholte Zeitanpassungen verwendet. Zum Beispiel ist2024-03-09T02:05:00-05:00[America/New_York]plus ein Tag angeblich2024-03-10T02:05:00-05:00[America/New_York], aber diese Zeit existiert nicht, sodass die Wanduhrzeit eine Stunde später,2024-03-10T03:05:00-04:00[America/New_York], zurückgegeben wird. - Wenn der Offset mehrdeutig ist, wird es mit dem
offset: "prefer"-Verhalten gelöst: Der Offset wird verwendet, wenn er für die Zeitzone und die lokale Zeit gültig ist, und andernfalls neu berechnet. Zum Beispiel ist2024-11-02T01:00:00-04:00[America/New_York]plus ein Tag2024-11-03T01:00:00-04:00[America/New_York], während2024-11-04T01:00:00-05:00[America/New_York]minus ein Tag2024-11-03T01:00:00-05:00[America/New_York]ist. - Wenn die Komponenten des resultierenden Datum-Uhrzeit außerhalb der Grenzen liegen, werden sie mit der
overflow-Option gelöst. Zum Beispiel ist2024-08-31plus ein Monat2024-09-31, das nicht existiert, daher wird es standardmäßig auf2024-09-30begrenzt.
- Wenn das Datum-Uhrzeit mehrdeutig oder aufgrund einer Zeitzonen-Offset-Übergangs ungültig ist, wird es mit dem
- Der Zeitanteil einer Dauer wird unter Verwendung der realen Zeit addiert/subtrahiert; das bedeutet, der Zeitanteil wird zu seinem
InstantmitTemporal.Instant.prototype.add()addiert und dann in derselben Zeitzone interpretiert. Zum Beispiel ist2024-11-03T01:00:00-04:00[America/New_York]plus eine Stunde2024-11-03T01:00:00-05:00[America/New_York].
Diese Regeln machen Arithmetik mit Temporal.ZonedDateTime "DST-sicher", was bedeutet, dass die Ergebnisse den Erwartungen sowohl von realen Benutzern als auch von Implementierern anderer standardkonformer Kalenderanwendungen am nächsten kommen. Diese Erwartungen umfassen:
- Das Hinzufügen oder Subtrahieren von Tagen sollte die Uhrzeit über DST-Übergänge hinweg konsistent halten. Beispielsweise, wenn Sie einen Termin am Samstag um 13:00 Uhr haben und Sie fragen, ihn 1 Tag später zu verschieben, würden Sie erwarten, dass der neu geplante Termin immer noch um 13:00 Uhr stattfindet, auch wenn über Nacht ein DST-Übergang stattgefunden hat.
- Das Hinzufügen oder Subtrahieren des Zeitanteils einer Dauer sollte DST-Übergänge ignorieren. Beispielsweise wird ein Freund, den Sie gebeten haben, sich in 2 Stunden zu treffen, verärgert sein, wenn Sie 1 Stunde oder 3 Stunden später erscheinen. Es sollte eine konsistente und relativ wenig überraschende Reihenfolge von Operationen geben.
- Wenn Ergebnisse an oder in der Nähe eines DST-Übergangs liegen, sollten Mehrdeutigkeiten automatisch (ohne Absturz) und deterministisch gehandhabt werden.
Das Hinzufügen einer Dauer ist gleichbedeutend mit Subtrahieren ihrer Negation.
Beispiele
Hinzufügen einer Dauer
const start = Temporal.ZonedDateTime.from(
"2021-11-01T12:34:56-04:00[America/New_York]",
);
const end = start.add({
years: 1,
months: 2,
weeks: 3,
days: 4,
hours: 5,
minutes: 6,
seconds: 7,
milliseconds: 8,
});
console.log(end.toString()); // 2023-01-26T17:41:03.008-05:00[America/New_York]
Für weitere Beispiele, insbesondere wie verschiedene Kalender und die overflow-Option mit Kalenderdauern interagieren, siehe Temporal.PlainDate.prototype.add().
Spezifikationen
| Spezifikation |
|---|
| Temporal # sec-temporal.zoneddatetime.prototype.add |