</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.PlainDateTime.prototype.add()

Temporal.PlainDateTime.prototype.add()

Methode

Gibt ein neues <code>Temporal.PlainDateTime</code> zurück, das um die angegebene Dauer in die Zukunft (bei negativer Dauer in die Vergangenheit) verschoben ist.

seit JavaScript ES2026 (Temporal) – Firefox 139+, Chrome 144+; Saf Kategorie: method-property

Signatur

Temporal.PlainDateTime.prototype.add(duration, options)

Beschreibung

add() rechnet eine Dauer auf einen Datum-Uhrzeit-Wert ohne Zeitzone auf. Die Dauer kann als Temporal.Duration, als einfaches Objekt wie { days: 3, hours: 2 } oder als ISO-8601-Dauer-Zeichenkette wie "P1DT2H" übergeben werden. Das ursprüngliche Objekt wird nicht verändert, denn alle Temporal-Objekte sind unveränderlich.

Die Rechnung läuft in zwei Schritten: Zuerst wird der Zeitanteil (Stunden bis Nanosekunden) addiert. Ein Überlauf über Mitternacht wird dabei als ganze Tage übertragen. Danach wird der Datumsanteil (Jahre, Monate, Wochen, Tage) mit dem Kalender des Objekts addiert, beginnend mit der größten Einheit. Deshalb ergibt z. B. 31. Januar + 1 Monat standardmäßig den letzten Tag im Februar.

Weil PlainDateTime keine Zeitzone kennt, spielen Sommerzeit-Umstellungen keine Rolle: Ein Tag hat hier immer genau 24 Stunden. Das eignet sich für Kalender- und Planungslogik, etwa Wiederholungstermine zur „Wanduhrzeit“. Wenn es um echte vergangene Zeit an einem bestimmten Ort geht, nimmt man besser Temporal.ZonedDateTime.

Parameter

Name Typ Default Beschreibung
$duration Pflicht Temporal.Duration | object | string Die Dauer, die addiert wird: eine Temporal.Duration, ein Objekt mit Eigenschaften wie years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds oder eine ISO-8601-Zeichenkette (z. B. "PT90M"). Die Umwandlung übernimmt Temporal.Duration.from().
$options object {} Optionales Einstellungsobjekt.
$options.overflow "constrain" | "reject" "constrain" Legt fest, was bei einem ungültigen Datum passiert (z. B. 31. Februar). "constrain" setzt den Tag auf den nächsten gültigen Wert, "reject" wirft einen RangeError.

Rückgabewert

Typ
Temporal.PlainDateTime
Beschreibung
Ein neues Temporal.PlainDateTime im selben Kalender, verschoben um duration.

Beispiele

Tage und Stunden addieren

const start = Temporal.PlainDateTime.from("2024-03-30T20:00");

// 10 Stunden gehen über Mitternacht hinaus
console.log(start.add({ hours: 10 }).toString());

// Objekt, ISO-Zeichenkette und Duration sind gleichwertig
console.log(start.add({ days: 1, hours: 2, minutes: 30 }).toString());
console.log(start.add("P1DT2H30M").toString());
console.log(start.add(Temporal.Duration.from({ weeks: 2 })).toString());

// Das Original bleibt unverändert
console.log(start.toString());
2024-03-31T06:00:00 2024-03-31T22:30:00 2024-03-31T22:30:00 2024-04-13T20:00:00 2024-03-30T20:00:00

Monatsende: overflow constrain vs. reject

const termin = Temporal.PlainDateTime.from("2024-01-31T09:00");

// Standard: auf den letzten gültigen Tag begrenzen
console.log(termin.add({ months: 1 }).toString());

try {
  termin.add({ months: 1 }, { overflow: "reject" });
} catch (err) {
  console.log(err.name);
}
2024-02-29T09:00:00 RangeError

Wiederkehrende Termine erzeugen

const ersterTermin = Temporal.PlainDateTime.from("2025-06-02T10:30");

// Die nächsten vier wöchentlichen Meetings
const termine = Array.from({ length: 4 }, (_, i) =>
  ersterTermin.add({ weeks: i }).toString()
);

console.log(termine);
["2025-06-02T10:30:00", "2025-06-09T10:30:00", "2025-06-16T10:30:00", "2025-06-23T10:30:00"]

Negative Dauer: in die Vergangenheit verschieben

const jetzt = Temporal.PlainDateTime.from("2025-01-01T00:15");

// Entspricht jetzt.subtract({ minutes: 30 })
console.log(jetzt.add({ minutes: -30 }).toString());
2024-12-31T23:45:00

// Wichtig · Fallstricke

  • Browserunterstützung: Temporal ist neu (Firefox 139+, Chrome/Edge 144+). Safari und ältere Node.js-Versionen haben es noch nicht. Als Ersatz dienen Polyfills wie @js-temporal/polyfill oder temporal-polyfill.
  • Keine Zeitzone: Sommerzeit-Umstellungen werden ignoriert. add({ hours: 24 }) und add({ days: 1 }) ergeben hier immer dasselbe. Bei ZonedDateTime gilt das nicht.
  • Addition ist nicht immer umkehrbar: dt.add({ months: 1 }).subtract({ months: 1 }) führt bei Monatsenden nicht unbedingt zum Ausgangswert zurück (31.01. → 29.02. → 29.01.).
  • Reihenfolge der Einheiten: Innerhalb einer Dauer wird zuerst der Zeitanteil addiert, danach der Datumsanteil von Jahren bis Tagen. Mehrere add()-Aufrufe hintereinander können deshalb ein anderes Ergebnis liefern als ein einziger Aufruf mit der zusammengefassten Dauer.
  • Gemischte Vorzeichen in einer Dauer (z. B. { days: 1, hours: -2 }) sind nicht erlaubt und werfen einen RangeError. Das gilt auch für Ergebnisse außerhalb des gültigen Bereichs (etwa ±275.760 Jahre).
  • Einfache Zahlen wie add(5) werden nicht akzeptiert und werfen einen TypeError. Die Einheit muss immer angegeben werden.

Siehe auch

Temporal.PlainDateTime.prototype.subtract() Temporal.PlainDateTime.prototype.with() Temporal.PlainDateTime.prototype.until() Temporal.PlainDateTime.prototype.since() Temporal.Duration Temporal.ZonedDateTime.prototype.add() Temporal.PlainDate.prototype.add()
← Vorheriger Eintrag Temporal.PlainDateTime.from()