Temporal.ZonedDateTime.prototype.add()
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
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
| Specification |
|---|
| Temporal # sec-temporal.zoneddatetime.prototype.add |