Temporal.Instant.prototype.add()

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.

Die add()-Methode von Temporal.Instant-Instanzen gibt ein neues Temporal.Instant-Objekt zurück, das diesen Zeitpunkt um eine angegebene Dauer nach vorne verschoben darstellt (in einer Form, die durch Temporal.Duration.from() umwandelbar ist).

Syntax

add(duration)

Parameter

duration: Ein String, ein Objekt oder eine Temporal.Duration-Instanz, die eine Dauer darstellt, die zu diesem Zeitpunkt hinzugefügt werden soll. Es wird mit demselben Algorithmus wie Temporal.Duration.from() in ein Temporal.Duration-Objekt umgewandelt.

Rückgabewert

Ein neues Temporal.Instant-Objekt, das das Hinzufügen von duration zu diesem Zeitpunkt darstellt. Falls duration positiv ist, dann ist der zurückgegebene Zeitpunkt später als dieser Zeitpunkt; falls duration negativ ist, dann ist der zurückgegebene Zeitpunkt früher als dieser Zeitpunkt.

Ausnahmen

RangeError

Wird in einem der folgenden Fälle ausgelöst:

duration ist eine Kalenderdauer (sie hat einen nicht-nullwertigen years, months oder weeks) oder hat einen nicht-nullwertigen days, da Kalenderdauern ohne Kalender und Zeitreferenz mehrdeutig sind.
Das Ergebnis liegt nicht im darstellbaren Bereich, der ±10⁸ Tage oder etwa ±273.972,6 Jahre vom Unix-Epoch umfasst.

Beschreibung

Im Wesentlichen ermittelt die add()-Methode zuerst die Anzahl der Nanosekunden, die von duration dargestellt werden, addiert sie zu den epochNanoseconds dieses Zeitpunkts und erstellt dann ein neues Temporal.Instant-Objekt aus dem Ergebnis. Daher muss die Dauer eindeutig eine festgelegte Zeitmenge darstellen.

Wenn Sie eine Kalenderdauer hinzufügen möchten, muss die Addition im Kontext eines Kalenders und einer Zeitzone erfolgen, um die variablen Längen von Monaten, Jahren und Tagen (aufgrund der Sommerzeit) zu berücksichtigen. In diesem Fall konvertieren Sie den Zeitpunkt in ein Temporal.ZonedDateTime-Objekt, fügen Sie die Dauer hinzu und konvertieren Sie das Ergebnis dann zurück in einen Zeitpunkt.

Das Hinzufügen einer Dauer entspricht dem Subtrahieren ihrer Negation.

Beispiele

Hinzufügen einer Temporal.Duration

const instant = Temporal.Instant.fromEpochMilliseconds(0);
const duration = Temporal.Duration.from("PT1S");
const newInstant = instant.add(duration);
console.log(newInstant.epochMilliseconds); // 1000

Hinzufügen eines Objekts oder eines Strings

const instant = Temporal.Instant.fromEpochMilliseconds(0);
const newInstant = instant.add({ seconds: 1 });
console.log(newInstant.epochMilliseconds); // 1000

const newInstant2 = instant.add("PT1S");
console.log(newInstant2.epochMilliseconds); // 1000

Hinzufügen einer Kalenderdauer

const instant = Temporal.Instant.fromEpochMilliseconds(1730610000000);
const duration = Temporal.Duration.from({ days: 1 });

// This instant is 2024-11-03T01:00:00-04:00[America/New_York],
// which is a DST transition day in the US.
const instant2 = instant
  .toZonedDateTimeISO("America/New_York")
  .add(duration)
  .toInstant();
console.log(instant2.epochMilliseconds); // 1730700000000

// The same instant is not a DST transition day in Paris.
const instant3 = instant
  .toZonedDateTimeISO("Europe/Paris")
  .add(duration)
  .toInstant();
console.log(instant3.epochMilliseconds); // 1730696400000

Spezifikationen

Specification
Temporal # sec-temporal.instant.prototype.add