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 gegebene Dauer verschoben, darstellt (in einer Form, die durch Temporal.Duration.from() konvertierbar ist).

Syntax

add(duration)

Parameter

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

Rückgabewert

Ein neues Temporal.Instant Objekt, das die Addition der duration zu diesem Zeitpunkt darstellt. Ist duration positiv, liegt der zurückgegebene Zeitpunkt später als dieser Zeitpunkt; ist duration negativ, liegt der zurückgegebene Zeitpunkt früher.

Ausnahmen

RangeError

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

duration ist eine Kalenderdauer (sie hat einen nicht-Null-Wert bei years, months oder weeks), oder hat einen nicht-Null-Wert bei 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 ab dem Unix-Epoch umfasst.

Beschreibung

Im Wesentlichen erhält die add() Methode zuerst die Anzahl der Nanosekunden, die durch duration dargestellt werden, addiert diese zu den epochNanoseconds dieses Zeitpunktes, und erstellt dann aus dem Ergebnis ein neues Temporal.Instant Objekt. Deshalb muss die Dauer eindeutig eine feste Zeitspanne darstellen.

Wenn Sie eine Kalenderdauer hinzufügen möchten, muss die Addition im Kontext eines Kalenders und einer Zeitzone durchgeführt werden, um die variablen Längen von Monaten, Jahren und Tagen (wegen Sommerzeit) zu berücksichtigen. In diesem Fall wandeln Sie den Zeitpunkt in ein Temporal.ZonedDateTime Objekt um, fügen die Dauer hinzu, und konvertieren 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