new Temporal.Duration() — Methode · JavaScript-Referenz

Signatur

new Temporal.Duration(years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds)

Beschreibung

Der Konstruktor Temporal.Duration() erstellt ein unveränderliches Objekt, das eine Zeitdauer beschreibt, etwa „2 Stunden und 30 Minuten“ oder „1 Jahr, 3 Monate“. Jede der zehn Einheiten wird als eigenes, optionales Argument in fester Reihenfolge übergeben – von years bis nanoseconds. Fehlende Argumente gelten als 0.

Die Werte werden nicht ausgeglichen: new Temporal.Duration(0, 0, 0, 0, 0, 90) bleibt „90 Minuten“ und wird nicht automatisch in „1 Stunde 30 Minuten“ umgerechnet. Zum Ausgleichen nutzt man duration.round({ largestUnit: "hour" }), zum Umrechnen in eine einzelne Einheit duration.total().

In der Praxis ist der Konstruktor eher selten – meist sind Temporal.Duration.from() mit einem Objekt wie { hours: 2, minutes: 30 } oder einem ISO-8601-String wie "PT2H30M" lesbarer, und Dauern entstehen oft durch until()/since() anderer Temporal-Objekte. Der Konstruktor lohnt sich, wenn man alle Einheiten ohnehin positionsweise vorliegen hat, z. B. aus einer Serialisierung.

Alle Werte müssen dasselbe Vorzeichen haben (oder 0 sein): Eine Dauer ist entweder insgesamt positiv oder insgesamt negativ.

Parameter

Name	Typ	Beschreibung
$years	number	Anzahl der Jahre. Ganze Zahl, Betrag kleiner als 2³².
$months	number	Anzahl der Monate. Ganze Zahl, Betrag kleiner als 2³².
$weeks	number	Anzahl der Wochen. Ganze Zahl, Betrag kleiner als 2³².
$days	number	Anzahl der Tage. Ganze Zahl.
$hours	number	Anzahl der Stunden. Ganze Zahl.
$minutes	number	Anzahl der Minuten. Ganze Zahl.
$seconds	number	Anzahl der Sekunden. Ganze Zahl.
$milliseconds	number	Anzahl der Millisekunden. Ganze Zahl.
$microseconds	number	Anzahl der Mikrosekunden. Ganze Zahl.
$nanoseconds	number	Anzahl der Nanosekunden. Ganze Zahl.

Rückgabewert

Typ

Temporal.Duration

Beschreibung

Ein neues, unveränderliches Temporal.Duration-Objekt mit genau den übergebenen (nicht ausgeglichenen) Einheiten.

Beispiele

Einfache Dauer erzeugen und ausgeben

// 1 Jahr, 2 Monate, 0 Wochen, 3 Tage, 4 Std., 5 Min., 6 Sek.
const dauer = new Temporal.Duration(1, 2, 0, 3, 4, 5, 6);

console.log(dauer.toString());
console.log(dauer.years, dauer.days, dauer.minutes);

// Nur Uhrzeit-Anteile: vordere Positionen mit 0 auffüllen
const kurz = new Temporal.Duration(0, 0, 0, 0, 0, 0, 1, 500);
console.log(kurz.toString());

P1Y2M3DT4H5M6S 1 3 5 PT1.5S

Nicht ausgeglichene Werte runden und umrechnen

const filmlaenge = new Temporal.Duration(0, 0, 0, 0, 0, 150);

console.log(filmlaenge.toString());                           // bleibt 150 Minuten
console.log(filmlaenge.round({ largestUnit: "hour" }).toString());
console.log(filmlaenge.total("hour"));

PT150M PT2H30M 2.5

Negative Dauer und Addition zu einem Zeitpunkt

const zurueck = new Temporal.Duration(0, 0, 0, 0, -2, -30);
console.log(zurueck.toString(), zurueck.sign);

const termin = Temporal.PlainDateTime.from("2025-03-10T12:00");
console.log(termin.add(zurueck).toString());

// Gleichwertig, aber lesbarer:
console.log(Temporal.Duration.from({ hours: -2, minutes: -30 }).equals?.name ?? "from() ok");

-PT2H30M -1 2025-03-10T09:30:00 from() ok

Fehlerfälle abfangen

const versuche = [
  () => new Temporal.Duration(0, 0, 0, 1, -1), // gemischte Vorzeichen
  () => new Temporal.Duration(0, 0, 0, 1.5),   // keine ganze Zahl
  () => Temporal.Duration(1)                   // ohne new
];

for (const v of versuche) {
  try {
    v();
  } catch (e) {
    console.log(e.constructor.name);
  }
}

RangeError RangeError TypeError

// Wichtig · Fallstricke

Nur mit new: Ein Aufruf ohne new wirft einen TypeError.
Gemischte Vorzeichen (z. B. +1 Tag, −1 Stunde) führen zu einem RangeError. Für „1 Tag minus 1 Stunde“ erst die Dauer bilden und dann mit subtract() arbeiten.
Nur ganze Zahlen: Nachkommawerte, NaN oder Infinity werfen einen RangeError. Bruchteile muss man in kleinere Einheiten umrechnen (1,5 s → 1 s + 500 ms).
Grenzen: Jahre, Monate und Wochen müssen betragsmäßig kleiner als 2³² sein; Tage bis Nanosekunden zusammen, in Sekunden umgerechnet, kleiner als 2⁵³.
Positionsargumente sind fehleranfällig: Wer nur Minuten meint, muss fünf Nullen voranstellen. Temporal.Duration.from({ minutes: 5 }) ist meist die bessere Wahl.
Kalendereinheiten (Jahre, Monate, Wochen) lassen sich bei round()/total() nur mit der Option relativeTo umrechnen, weil ihre Länge variiert.
Kompatibilität: Temporal ist neu (Firefox 139+, Chrome/Edge 144+). Safari und ältere Node.js-Versionen unterstützen es noch nicht – dort hilft ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

new Temporal.Instant() new Temporal.PlainTime() new Temporal.PlainDate() new GeneratorFunction() new Temporal.PlainDateTime() new AsyncFunction() new AsyncGeneratorFunction()