Temporal.ZonedDateTime.prototype.add()

Syntax

add(duration)
add(duration, options)

Parameter

duration

Ein String, ein Objekt oder eine Temporal.Duration Instanz, die eine Dauer repräsentiert, die zu diesem Datum-Uhrzeit hinzugefügt werden soll. Es wird unter Verwendung des gleichen Algorithmus wie Temporal.Duration.from() in ein Temporal.Duration Objekt konvertiert.

options Optional

Ein Objekt, das die folgende Eigenschaft enthält:

overflow Optional

Ein String, der das Verhalten angibt, wenn eine Datumskomponente außerhalb des gültigen Bereichs liegt. Mögliche Werte sind:

"constrain" (Standard)

Die Datumskomponente wird eingeschränkt auf den gültigen Bereich.

"reject"

Ein RangeError wird ausgelöst, wenn die Datumskomponente außerhalb des gültigen Bereichs liegt.

Rückgabewert

Ein neues Temporal.ZonedDateTime Objekt, das das durch die ursprüngliche ZonedDateTime und die Dauer spezifizierte Datum-Uhrzeit darstellt.

Ausnahmen

RangeError

Wird ausgelöst, wenn das Ergebnis nicht im darstellbaren Bereich liegt, was ±10⁸ Tage oder etwa ±273.972,6 Jahre ab der Unix-Epoche entspricht.

Beschreibung

Wie Kalenderdauern hinzugefügt werden, erfahren Sie in Temporal.PlainDate.prototype.add().

Addition und Subtraktion werden gemäß den in RFC 5545 (iCalendar) definierten Regeln durchgeführt:

• Fügen Sie den Datumsanteil eines Zeitraums mit Kalenderarithmetik hinzu oder ziehen Sie ihn ab; mit anderen Worten: Fügen Sie den Datumsanteil zu seinem PlainDateTime mit Temporal.PlainDateTime.prototype.add() hinzu und interpretieren Sie dann das Ergebnis in derselben Zeitzone. Das Ergebnis passt sich automatisch der Sommerzeitregelung entsprechend dieser Instanz des timeZone Feldes an. Zum Beispiel ist 2024-11-03T01:00:00-04:00[America/New_York] plus ein Tag 2024-11-04T01:00:00-05:00[America/New_York], als hätte der Tag 25 Stunden.
  • Wenn die Datum-Uhrzeit mehrdeutig oder aufgrund einer Zeitzonen-Offset-Übergang ungültig ist, wird sie mit dem Verhalten disambiguation: "compatible" aufgelöst: der spätere der beiden möglichen Zeitpunkte wird bei Zeitüberschreitungen verwendet, und der frühere der beiden möglichen Zeitpunkte wird bei Zeitwiederholungen verwendet. Zum Beispiel ist 2024-03-09T02:05:00-05:00[America/New_York] plus ein Tag angeblich 2024-03-10T02:05:00-05:00[America/New_York], aber diese Zeit existiert nicht, also wird die eine Stunde später angezeigte Uhrzeit 2024-03-10T03:05:00-04:00[America/New_York] zurückgegeben. Ebenso ergeben sowohl 2024-11-02T01:00:00-04:00[America/New_York] plus ein Tag als auch 2024-11-04T01:00:00-05:00[America/New_York] minus ein Tag 2024-11-03T01:00:00-04:00[America/New_York], den früheren der beiden möglichen Zeitpunkte.
  • Wenn die Komponenten der resultierenden Datum-Uhrzeit außerhalb der Grenzen liegen, werden sie mit der overflow Option aufgelöst. Zum Beispiel ist 2024-08-31 plus ein Monat 2024-09-31, was nicht existiert, daher wird es standardmäßig auf 2024-09-30 eingeschränkt.
• Fügen Sie den Zeitanteil eines Zeitraums mit realer Zeit hinzu oder ziehen Sie ihn ab; mit anderen Worten: Fügen Sie den Zeitanteil zu seinem Instant mit Temporal.Instant.prototype.add() hinzu, und interpretieren Sie dann das Ergebnis in derselben Zeitzone. Zum Beispiel ist 2024-11-03T01:00:00-04:00[America/New_York] plus eine Stunde 2024-11-03T01:00:00-05:00[America/New_York].

Diese Regeln machen die Arithmetik mit Temporal.ZonedDateTime "sicher vor Sommerzeit (DST)", was bedeutet, dass die Ergebnisse den Erwartungen sowohl der realen Benutzer als auch der Implementierer anderer standardkonformer Kalenderanwendungen am nächsten kommen. Diese Erwartungen umfassen:

• Das Hinzufügen oder Subtrahieren von Tagen sollte die Uhrzeit auch bei DST-Übergängen konstant halten. Zum Beispiel, wenn Sie einen Termin am Samstag um 13:00 Uhr haben und ihn um einen Tag verschieben möchten, erwarten Sie, dass der verschobene Termin weiterhin um 13:00 Uhr liegt, selbst wenn es über Nacht einen DST-Übergang gab.
• Das Hinzufügen oder Subtrahieren des Zeitanteils eines Zeitraums sollte DST-Übergänge ignorieren. Zum Beispiel wird ein Freund, den Sie gebeten haben, in 2 Stunden zu treffen, verärgert sein, wenn Sie 1 Stunde oder 3 Stunden später erscheinen. Es sollte eine konsistente und relativ überraschungsfreie Reihenfolge der Operationen geben.
• Wenn Ergebnisse bei oder nahe einem DST-Übergang liegen, sollten Mehrdeutigkeiten automatisch (ohne Absturz) und deterministisch behandelt werden.

Das Hinzufügen einer Dauer entspricht dem 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 Kalendermengen interagieren, siehe Temporal.PlainDate.prototype.add().

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Temporal.ZonedDateTime
• Temporal.Duration
• Temporal.ZonedDateTime.prototype.subtract()