Signatur
Beschreibung
add() verschiebt ein zeitzonenbezogenes Datum mit Uhrzeit um eine Dauer. Die Dauer kann ein Temporal.Duration-Objekt sein, ein Objekt wie { days: 1, hours: 2 } oder ein ISO-8601-Dauer-String wie "P1DT2H". Alles, was Temporal.Duration.from() annimmt, funktioniert hier auch. Das ursprüngliche Objekt bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich (immutable).
Wichtig ist, wie Datumsanteile und Zeitanteile verrechnet werden:
years,months,weeksunddayswerden im Kalender gerechnet, also auf der lokalen Uhrzeit. „+1 Tag“ bedeutet: gleiche Uhrzeit am nächsten Tag. Bei einer Sommerzeit-Umstellung sind das tatsächlich 23 oder 25 Stunden.hours,minutes,secondsund kleinere Einheiten werden als exakt verstrichene Zeit gerechnet. „+24 Stunden“ sind also immer genau 24 Stunden, und die lokale Uhrzeit kann sich dabei verschieben.
Zuerst wird der Datumsanteil addiert, danach der Zeitanteil. Fällt das Zwischenergebnis auf eine lokale Uhrzeit, die es wegen einer Zeitumstellung nicht gibt oder die doppelt vorkommt, wird sie wie bei disambiguation: "compatible" aufgelöst. Eine nicht existierende Uhrzeit wird also nach vorne verschoben. Das hat man meistens im Sinn, wenn man Termine, Erinnerungen oder Ablaufzeiten in einer echten Zeitzone plant.
Um in die Vergangenheit zu rechnen, übergibt man eine negative Dauer oder verwendet subtract().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $duration Pflicht | Temporal.Duration | object | string | Die zu addierende Dauer: ein Temporal.Duration, ein Objekt mit Feldern wie years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds oder ein ISO-8601-Dauer-String (z. B. "PT1H30M"). Alle Felder müssen dasselbe Vorzeichen haben. |
|
| $options | object | { overflow: "constrain" } | Optionales Objekt mit der Eigenschaft overflow. Sie legt fest, was passiert, wenn das Ergebnis nicht existiert, z. B. der 31. Februar: "constrain" (Standard) setzt auf den letzten gültigen Tag, "reject" wirft einen RangeError. |
Rückgabewert
Temporal.ZonedDateTime mit derselben Zeitzone und demselben Kalender, um duration verschoben.Beispiele
Kalendertag vs. 24 Stunden über die Sommerzeit-Umstellung
// In Berlin wird am 31.03.2024 um 02:00 auf 03:00 vorgestellt
const start = Temporal.ZonedDateTime.from('2024-03-30T12:00[Europe/Berlin]');
// +1 Tag: gleiche lokale Uhrzeit am Folgetag (tatsächlich nur 23 h)
console.log(start.add({ days: 1 }).toString());
// +24 Stunden: exakt verstrichene Zeit, die lokale Uhrzeit verschiebt sich
console.log(start.add({ hours: 24 }).toString());Monatsende und die Option overflow
const ende = Temporal.ZonedDateTime.from('2024-01-31T10:00[Europe/Berlin]');
// Standard "constrain": auf den letzten gültigen Tag setzen
console.log(ende.add({ months: 1 }).toString());
// "reject": ungültiges Datum führt zu einem Fehler
try {
ende.add({ months: 1 }, { overflow: 'reject' });
} catch (err) {
console.log(err.name);
}Ablaufzeit eines Tokens mit Dauer-String berechnen
const jetzt = Temporal.ZonedDateTime.from('2024-06-15T09:15:00[Europe/Berlin]');
// ISO-8601-Dauer: 1 Stunde 30 Minuten
const ablauf = jetzt.add('PT1H30M');
console.log(ablauf.toPlainTime().toString());
// Negative Dauer rechnet rückwärts (wie subtract)
console.log(jetzt.add({ days: -7 }).toPlainDate().toString());
// Original bleibt unverändert
console.log(jetzt.toString());Nicht existierende lokale Uhrzeit wird nach vorne verschoben
const abend = Temporal.ZonedDateTime.from('2024-03-30T02:30[Europe/Berlin]');
// 31.03.2024 02:30 gibt es in Berlin nicht, das Ergebnis wird 03:30
console.log(abend.add({ days: 1 }).toString());