Signatur
Beschreibung
Temporal.Duration ist Teil der Temporal-API (TC39 Stage 3) und beschreibt eine Zeitspanne, die aus bis zu acht Komponenten bestehen kann: years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds und nanoseconds. Im Gegensatz zu Date-basierten Differenzen ist eine Duration kalender- und zeitzonenbewusst und kann exakt addiert oder subtrahiert werden.
Instanzen werden entweder über den Konstruktor new Temporal.Duration(), über Temporal.Duration.from() (aus einem ISO-8601-Dauerstring wie 'P1Y2M3DT4H' oder einem Plain-Object) oder als Rückgabewert von since()/until()-Methoden anderer Temporal-Typen erzeugt. Duration-Objekte sind unveränderlich (immutable).
Ein wichtiges Konzept ist der Sign (Vorzeichen): Alle Komponenten einer Duration müssen dasselbe Vorzeichen haben (entweder alle nicht-negativ oder alle nicht-positiv). Negative Dauern repräsentieren Zeitspannen in der Vergangenheit. Die Methode negated() dreht das Vorzeichen um, abs() gibt den Absolutwert zurück.
Weil Monate und Jahre keine feste Länge haben, können viele Operationen (wie total() in Sekunden) erst dann sinnvoll berechnet werden, wenn ein Referenzdatum (Relativistik-Datum) angegeben wird. Ohne dieses Referenzdatum wirft die API in solchen Fällen einen RangeError.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $years | number | 0 | Anzahl der Jahre der Zeitspanne. |
| $months | number | 0 | Anzahl der Monate der Zeitspanne. |
| $weeks | number | 0 | Anzahl der Wochen der Zeitspanne. |
| $days | number | 0 | Anzahl der Tage der Zeitspanne. |
| $hours | number | 0 | Anzahl der Stunden der Zeitspanne. |
| $minutes | number | 0 | Anzahl der Minuten der Zeitspanne. |
| $seconds | number | 0 | Anzahl der Sekunden der Zeitspanne. |
| $milliseconds | number | 0 | Anzahl der Millisekunden der Zeitspanne. |
| $microseconds | number | 0 | Anzahl der Mikrosekunden der Zeitspanne. |
| $nanoseconds | number | 0 | Anzahl der Nanosekunden der Zeitspanne. |
Rückgabewert
Temporal.Duration-Instanz mit den angegebenen Zeitkomponenten.Beispiele
Duration erstellen und zu einem Datum addieren
// Polyfill nötig: npm install @js-temporal/polyfill
import { Temporal } from '@js-temporal/polyfill';
// Eine Dauer von 1 Jahr, 2 Monaten und 3 Tagen
const duration = new Temporal.Duration(1, 2, 0, 3);
console.log(duration.years); // 1
console.log(duration.months); // 2
console.log(duration.days); // 3
console.log(duration.toString()); // 'P1Y2M3D'
// Dauer zu einem PlainDate addieren
const start = Temporal.PlainDate.from('2023-01-15');
const end = start.add(duration);
console.log(end.toString()); // '2024-03-18'Differenz zweier Zeitpunkte als Duration berechnen und total() verwenden
import { Temporal } from '@js-temporal/polyfill';
const geburtstag = Temporal.PlainDate.from('1990-06-15');
const heute = Temporal.PlainDate.from('2024-03-20');
// Differenz berechnen (Ergebnis ist eine Duration)
const alter = geburtstag.until(heute, { largestUnit: 'year' });
console.log(alter.toString()); // z. B. 'P33Y9M5D'
console.log(`${alter.years} Jahre, ${alter.months} Monate, ${alter.days} Tage`);
// Gesamtdauer in Tagen (Referenzdatum nötig, da Monate/Jahre variable Länge haben)
const gesamtTage = alter.total({ unit: 'days', relativeTo: geburtstag });
console.log(Math.floor(gesamtTage)); // z. B. 12327
// Duration aus ISO-8601-String
const urlaub = Temporal.Duration.from('P2W3DT4H30M');
console.log(urlaub.weeks); // 2
console.log(urlaub.days); // 3
console.log(urlaub.hours); // 4
console.log(urlaub.minutes); // 30
// Negieren und Absolutwert
const negativ = urlaub.negated();
console.log(negativ.weeks); // -2
const positiv = negativ.abs();
console.log(positiv.weeks); // 2// Wichtig · Fallstricke
Verfügbarkeit: Temporal.Duration ist noch kein Baseline-Standard. Die Spezifikation befindet sich im TC39 Stage-3-Prozess. Für den produktiven Einsatz wird der Polyfill @js-temporal/polyfill empfohlen. Ab Chrome 138 / Firefox 139 ist Temporal nativ verfügbar (Status prüfen).
Gemischte Vorzeichen verboten: Alle numerischen Komponenten müssen dasselbe Vorzeichen tragen. new Temporal.Duration(1, -2) wirft einen RangeError.
total() und kalenderabhängige Einheiten: Wird total() mit 'years', 'months' oder 'weeks' als Zieleinheit aufgerufen, muss relativeTo (ein PlainDate oder ZonedDateTime) angegeben werden – sonst RangeError.
Rundung mit round(): Die Methode round() erlaubt es, eine Duration in eine bestimmte kleinste Einheit zu runden und dabei z. B. Übertrag von Minuten in Stunden zu normalisieren (balancing). Auch hier ist für kalenderabhängige Einheiten relativeTo erforderlich.