Temporal.PlainTime.prototype.add() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainTime.prototype.add(duration)

Beschreibung

Die Methode add() rechnet eine Dauer auf eine Uhrzeit ohne Datum und ohne Zeitzone (Temporal.PlainTime). Das ursprüngliche Objekt bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich. Du erhältst immer eine neue Instanz zurück.

Als Dauer akzeptiert die Methode alles, was auch Temporal.Duration.from() verarbeitet: eine Temporal.Duration-Instanz, ein Objekt wie { hours: 1, minutes: 30 } oder einen ISO-8601-Dauerstring wie "PT1H30M". Negative Dauern ziehen Zeit ab. Das Ergebnis entspricht dann subtract() mit der umgekehrten Dauer.

Weil eine PlainTime nur eine Uhrzeit ohne Tag darstellt, wird das Ergebnis modulo 24 Stunden berechnet: 23:30 plus zwei Stunden ergibt 01:30. Eine Information über den Tageswechsel geht dabei verloren. Datumsanteile der Dauer (years, months, weeks, days) werden ignoriert. Brauchst du den Tageswechsel, rechne mit Temporal.PlainDateTime oder Temporal.ZonedDateTime.

Typische Einsatzfälle sind Öffnungszeiten, Schichtpläne, Wecker, Timer-Anzeigen oder Kalender-Slots, bei denen nur die Uhrzeit zählt.

Parameter

Name	Typ	Default	Beschreibung
$duration Pflicht	Temporal.Duration \| object \| string		Die Dauer, die addiert werden soll. Möglich sind eine `Temporal.Duration`, ein Objekt mit Feldern wie `hours`, `minutes`, `seconds`, `milliseconds`, `microseconds` und `nanoseconds` oder ein ISO-8601-String wie `"PT45M"`. Datumsfelder werden ignoriert.

Rückgabewert

Typ

Temporal.PlainTime

Beschreibung

Ein neues Temporal.PlainTime-Objekt mit der verschobenen Uhrzeit. Wenn nötig, beginnt die Zeit nach 24 Stunden wieder bei 00:00.

Beispiele

Einfache Addition mit einem Dauer-Objekt

const start = Temporal.PlainTime.from("10:30");
const ende = start.add({ hours: 2, minutes: 45 });

console.log(ende.toString());
console.log(start.toString()); // Original bleibt unverändert

13:15:00 10:30:00

Über Mitternacht hinaus (Umlauf nach 24 Stunden)

const schichtBeginn = Temporal.PlainTime.from("22:00");
const schichtEnde = schichtBeginn.add({ hours: 8 });

console.log(schichtEnde.toString());
// Datumsanteile werden ignoriert:
console.log(schichtBeginn.add({ days: 1 }).toString());

06:00:00 22:00:00

ISO-8601-Dauerstring und negative Dauer

const termin = Temporal.PlainTime.from("14:00");

// Terminende nach 1,5 Stunden
console.log(termin.add("PT1H30M").toString());

// Erinnerung 15 Minuten vorher (negative Dauer)
console.log(termin.add({ minutes: -15 }).toString());

15:30:00 13:45:00

Zeit-Slots für einen Terminplaner erzeugen

const slotDauer = Temporal.Duration.from({ minutes: 30 });
let slot = Temporal.PlainTime.from("09:00");
const feierabend = Temporal.PlainTime.from("11:00");
const slots = [];

while (Temporal.PlainTime.compare(slot, feierabend) < 0) {
  slots.push(slot.toString({ smallestUnit: "minute" }));
  slot = slot.add(slotDauer);
}

console.log(slots);

["09:00", "09:30", "10:00", "10:30"]

// Wichtig · Fallstricke

Tageswechsel geht verloren: Das Ergebnis läuft nach 24 Stunden still wieder bei 00:00 los. Ob Mitternacht überschritten wurde, erfährst du nicht. In einer Schleife kann das Endlosschleifen verursachen, wenn die Abbruchbedingung nur Uhrzeiten vergleicht. In solchen Fällen besser Temporal.PlainDateTime verwenden.
Datumsanteile werden ignoriert: { days: 1 } oder { months: 2 } ändern die Uhrzeit nicht. Es gibt dabei auch keinen Fehler.
Gemischte Vorzeichen: Eine Dauer wie { hours: 1, minutes: -30 } ist ungültig und löst einen RangeError aus. Ein ungültiger Dauerstring führt ebenfalls zu einem RangeError, ein falscher Argumenttyp zu einem TypeError.
Kein Options-Parameter: Anders als bei PlainDate.prototype.add() gibt es kein overflow-Argument, weil bei Uhrzeiten keine Monats- oder Tagesgrenzen auftreten.
Browser-Unterstützung: Temporal steht erst seit Kurzem in Browsern zur Verfügung (Firefox 139+, Chrome/Edge 144+). Safari und ältere Umgebungen brauchen einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainTime.prototype.subtract() Temporal.PlainTime.prototype.since() Temporal.PlainTime.prototype.until() Temporal.Duration.from() Temporal.PlainTime Temporal.PlainDateTime.prototype.add()