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

Signatur

Temporal.Duration.prototype.with(durationLike)

Beschreibung

with() erzeugt eine Kopie einer bestehenden Dauer und ersetzt dabei gezielt einzelne Felder. Temporal.Duration-Objekte sind unveränderlich: Das Original wird nie geändert, du bekommst immer ein neues Objekt zurück.

Das übergebene Objekt darf beliebige Felder aus years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds und nanoseconds enthalten. Fehlende Felder übernimmt die Methode aus der ursprünglichen Dauer. Das ist praktisch, wenn du zum Beispiel aus einer Benutzereingabe nur die Minuten korrigieren oder einen Anteil gezielt auf 0 setzen willst.

Wichtig: with() gleicht nicht aus (kein „Balancing“). Wer minutes: 90 setzt, erhält auch 90 Minuten und nicht 1 Stunde 30 Minuten. Zum Normalisieren verwendest du anschließend round() mit largestUnit. Anders als with() bei PlainDate und ähnlichen Typen nimmt diese Methode keine Optionen entgegen.

Parameter

Name	Typ	Default	Beschreibung
$durationLike Pflicht	object		Objekt mit mindestens einem der Felder `years`, `months`, `weeks`, `days`, `hours`, `minutes`, `seconds`, `milliseconds`, `microseconds`, `nanoseconds`. Die Werte müssen ganze Zahlen sein. Nicht angegebene Felder werden aus der ursprünglichen Dauer übernommen.

Rückgabewert

Typ

Temporal.Duration

Beschreibung

Eine neue Temporal.Duration mit den ersetzten Feldern. Das Original bleibt unverändert.

Beispiele

Einzelnes Feld ersetzen

const dauer = Temporal.Duration.from({ hours: 1, minutes: 30 });
const korrigiert = dauer.with({ minutes: 45 });

console.log(korrigiert.toString());
console.log(dauer.toString()); // Original bleibt unverändert

PT1H45M PT1H30M

Anteile auf null setzen (z. B. Sekunden verwerfen)

const laufzeit = Temporal.Duration.from({ hours: 2, minutes: 5, seconds: 42, milliseconds: 310 });

const ohneSekunden = laufzeit.with({ seconds: 0, milliseconds: 0 });
console.log(ohneSekunden.toString());

PT2H5M

Kein Ausgleich: mit round() normalisieren

const basis = Temporal.Duration.from({ hours: 2 });
const roh = basis.with({ minutes: 90 });
console.log(roh.toString());

const normalisiert = roh.round({ largestUnit: 'hours' });
console.log(normalisiert.toString());

PT2H90M PT3H30M

Fehlerfälle abfangen

const d = Temporal.Duration.from({ hours: 1 });

try {
  d.with({ minutes: -30 }); // gemischte Vorzeichen
} catch (e) {
  console.log(e.constructor.name);
}

try {
  d.with({ seconds: 1.5 }); // keine ganze Zahl
} catch (e) {
  console.log(e.constructor.name);
}

try {
  d.with({}); // kein bekanntes Feld
} catch (e) {
  console.log(e.constructor.name);
}

RangeError RangeError TypeError

// Wichtig · Fallstricke

Vorzeichen: Alle Felder der resultierenden Dauer müssen dasselbe Vorzeichen haben (oder 0 sein). Mischt man positive und negative Werte, wirft die Methode einen RangeError. Das Vorzeichen der ganzen Dauer drehst du mit negated() um.
Nur ganze Zahlen: Bruchwerte wie seconds: 1.5 führen zu einem RangeError. Nutze stattdessen milliseconds: 500.
Mindestens ein Feld: Enthält das Objekt kein bekanntes Feld (etwa {} oder Tippfehler wie { hour: 1 }), wird ein TypeError geworfen. Der Singular hour ist hier also nicht erlaubt.
Kein Balancing: Die Werte werden nicht in größere Einheiten umgerechnet. Zum Normalisieren dient round(), bei Kalendereinheiten mit relativeTo.
Kompatibilität: Temporal ist neu. Es wird ab Firefox 139 und Chrome/Edge 144 unterstützt, Safari unterstützt es noch nicht vollständig. Für den produktiven Einsatz empfiehlt sich ein Polyfill wie @js-temporal/polyfill.

Siehe auch

Temporal.Duration Temporal.Duration.from() Temporal.Duration.prototype.round() Temporal.Duration.prototype.negated() Temporal.Duration.prototype.add() Temporal.PlainDate.prototype.with()