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

Signatur

Temporal.Duration.prototype.add(other)

Beschreibung

add() addiert zwei Zeitdauern und liefert das Ergebnis als neues Temporal.Duration-Objekt. Wie alle Temporal-Objekte ist Duration unveränderlich: Die Ausgangsdauer wird nicht verändert. Damit eignet sich die Methode z. B. zum Aufsummieren von Arbeitszeiten, Videolängen, Timer-Intervallen oder Messwerten.

Das Argument darf eine Temporal.Duration, ein Objekt mit Dauer-Feldern ({ hours: 1, minutes: 30 }) oder ein ISO-8601-Dauer-String ("PT1H30M") sein. Intern werden beide Dauern in Nanosekunden umgerechnet, addiert und anschließend bis zur größten Einheit neu aufgeteilt, die in einer der beiden Eingaben vorkommt. PT1H30M plus PT45M ergibt also PT2H15M, PT90M plus PT45M aber PT135M. Negative Anteile sind erlaubt, sodass auch ein negatives Ergebnis entstehen kann.

Wichtig: Kalendereinheiten (years, months, weeks) haben keine feste Länge. Kommen sie in einer der beiden Dauern vor (mit einem Wert ungleich 0), wirft add() einen RangeError. days zählen dagegen immer als genau 24 Stunden. Wenn du Kalenderdauern addieren willst, wende sie nacheinander auf ein konkretes Datum an, z. B. mit Temporal.PlainDate.prototype.add() oder Temporal.ZonedDateTime.prototype.add().

Parameter

Name	Typ	Default	Beschreibung
$other Pflicht	Temporal.Duration \| object \| string		Die Dauer, die addiert werden soll. Wird wie bei `Temporal.Duration.from()` umgewandelt: `Duration`-Instanz, Objekt mit Feldern wie `hours` und `minutes` oder ISO-8601-String wie `"PT15M"`.

Rückgabewert

Typ

Temporal.Duration

Beschreibung

Eine neue Temporal.Duration mit der Summe beider Dauern, neu aufgeteilt bis zur größten Einheit, die in einer der beiden Eingaben vorkommt.

Beispiele

Zwei Zeitdauern addieren

const meeting = Temporal.Duration.from({ hours: 1, minutes: 30 });
const overtime = Temporal.Duration.from('PT45M');

const total = meeting.add(overtime);
console.log(total.toString());
console.log(meeting.toString()); // Original bleibt unverändert

PT2H15M PT1H30M

Arbeitszeiten einer Woche aufsummieren

const sessions = ['PT7H45M', 'PT8H10M', { hours: 6, minutes: 50 }, 'PT8H'];

const week = sessions.reduce(
  (sum, s) => sum.add(s),
  Temporal.Duration.from({ hours: 0 })
);

console.log(week.toString());
console.log(week.total('hours'));

PT30H45M 30.75

Aufteilung hängt von der größten Einheit ab

const a = Temporal.Duration.from({ minutes: 90 });
console.log(a.add({ minutes: 45 }).toString());

// Mit Stunden in einer Eingabe wird bis zu Stunden aufgeteilt
console.log(a.add({ hours: 0, minutes: 45 }).toString());
console.log(Temporal.Duration.from({ hours: 0 }).add({ minutes: 135 }).toString());

// Tage zählen als 24 Stunden, negative Werte sind erlaubt
console.log(Temporal.Duration.from({ days: 1 }).add({ hours: 25 }).toString());
console.log(Temporal.Duration.from('PT1H').add({ minutes: -90 }).toString());

PT135M PT135M PT2H15M P2DT1H -PT30M

Kalendereinheiten: RangeError vermeiden

const oneMonth = Temporal.Duration.from({ months: 1 });

try {
  oneMonth.add({ days: 10 });
} catch (err) {
  console.log(err.name);
}

// Stattdessen nacheinander auf ein konkretes Datum anwenden
const start = Temporal.PlainDate.from('2024-01-31');
const end = start.add(oneMonth).add({ days: 10 });
console.log(end.toString());
console.log(start.until(end, { largestUnit: 'months' }).toString());

RangeError 2024-03-10 P1M10D

// Wichtig · Fallstricke

Kalendereinheiten: Enthält eine der beiden Dauern years, months oder weeks ungleich 0, wird ein RangeError geworfen. Ältere Entwürfe und Polyfills kannten eine Option relativeTo für add(). Sie wurde aus der Spezifikation entfernt. Addiere solche Dauern stattdessen über PlainDate, PlainDateTime oder ZonedDateTime.
Tage gelten immer als 24 Stunden. Zeitumstellungen werden dabei nicht berücksichtigt. Wenn es auf echte Kalendertage in einer Zeitzone ankommt, rechne mit Temporal.ZonedDateTime.
Aufteilung: Das Ergebnis wird nur bis zur größten Einheit der Eingaben aufgeteilt. Für eine gezielte Darstellung nutze anschließend round({ largestUnit: 'hours' }) oder total().
Unveränderlichkeit: add() verändert das Objekt nicht. Das Ergebnis muss zugewiesen werden (d = d.add(x)).
Ungültige Eingaben, etwa gemischte Vorzeichen innerhalb einer Dauer ({ hours: 1, minutes: -5 }) oder ein fehlerhafter ISO-String, führen zu einem RangeError bzw. TypeError.
Kompatibilität: Temporal ist noch neu und wird nicht von allen Browsern unterstützt. Safari und ältere Browser benötigen einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill. In Node.js ist Temporal erst in neueren Versionen verfügbar.

Siehe auch

Temporal.Duration.prototype.subtract() Temporal.Duration.from() Temporal.Duration.prototype.round() Temporal.Duration.prototype.total() Temporal.Duration.prototype.negated() Temporal.PlainDate.prototype.add() Temporal.ZonedDateTime.prototype.add() Temporal.Duration