Signatur
Beschreibung
Die Methode subtract() zieht eine Dauer von einer Uhrzeit ohne Datum und ohne Zeitzone ab. Das ursprüngliche Objekt bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich. Zurückgegeben wird immer eine neue Temporal.PlainTime-Instanz.
Als Dauer ist alles erlaubt, was Temporal.Duration.from() annimmt: eine Temporal.Duration, ein Objekt wie { hours: 1, minutes: 30 } oder ein ISO-8601-Dauerstring wie "PT1H30M". t.subtract(d) liefert dasselbe Ergebnis wie t.add(d.negated()).
Weil PlainTime kein Datum kennt, rechnet die Methode zyklisch auf der 24-Stunden-Uhr: Zieht man von 01:00 drei Stunden ab, erhält man 22:00. Datumsanteile der Dauer (years, months, weeks, days) werden ignoriert. Es werden nur Stunden bis Nanosekunden verrechnet.
Typische Einsatzfälle: Weckzeiten, Öffnungszeiten, Schichtpläne oder „X Minuten vor Termin“-Erinnerungen, bei denen es nur auf die Uhrzeit ankommt. Wer über Tagesgrenzen hinweg rechnen und den Datumswechsel sehen muss, sollte Temporal.PlainDateTime oder Temporal.ZonedDateTime verwenden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $duration Pflicht | Temporal.Duration | object | string | Die abzuziehende Dauer: eine Temporal.Duration, ein Objekt mit Feldern wie hours, minutes, seconds, milliseconds, microseconds, nanoseconds oder ein ISO-8601-Dauerstring (z. B. "PT45M"). Negative Dauern verschieben die Zeit nach vorn. |
Rückgabewert
Temporal.PlainTime-Instanz mit der um duration früheren Uhrzeit, bei Bedarf über Mitternacht zurückgerechnet.Beispiele
Stunden und Minuten abziehen
const start = Temporal.PlainTime.from("10:30:00");
const frueher = start.subtract({ hours: 2, minutes: 15 });
console.log(frueher.toString());
console.log(start.toString()); // Original bleibt unverändertÜberlauf über Mitternacht
const nachtschicht = Temporal.PlainTime.from("01:00");
const beginn = nachtschicht.subtract({ hours: 3 });
console.log(beginn.toString()); // läuft auf den Vortag zurück, ohne DatumErinnerung vor einem Termin mit ISO-Dauerstring
const termin = Temporal.PlainTime.from("14:00");
const vorlauf = Temporal.Duration.from("PT1H30M");
const erinnerung = termin.subtract(vorlauf);
console.log(`Erinnerung um ${erinnerung.toString({ smallestUnit: "minute" })}`);Datumsanteile werden ignoriert, negative Dauer verschiebt nach vorn
const t = Temporal.PlainTime.from("10:30");
console.log(t.subtract({ days: 1, hours: 1 }).toString()); // days wird ignoriert
console.log(t.subtract({ hours: -1 }).toString()); // entspricht add({ hours: 1 })// Wichtig · Fallstricke
- Kein Datumswechsel sichtbar: Das Ergebnis läuft still über Mitternacht zurück. Ob dabei der Vortag erreicht wurde, erfährt man nicht. Dafür
Temporal.PlainDateTimeverwenden. - Datumseinheiten zählen nicht:
years,months,weeksunddayswerden ohne Fehler ignoriert. Das kann Logikfehler verdecken, zum Beispiel wenn aus Versehen{ days: 1 }statt{ hours: 24 }übergeben wird. Beides ändert die Uhrzeit nicht. - Unveränderlichkeit:
subtract()ändert das Objekt nicht. Das Ergebnis muss zugewiesen werden. - Ungültige Eingaben: Ein Objekt ohne gültiges Dauerfeld, ein fehlerhafter String oder gemischte Vorzeichen (z. B.
{ hours: 1, minutes: -5 }) lösen einenRangeErrorbzw.TypeErroraus. - Kompatibilität: Temporal ist neu. Nativ gibt es die API in Firefox ab 139 und in Chromium-Browsern ab 144. Safari und ältere Node.js-Versionen brauchen einen Polyfill wie
@js-temporal/polyfill. Vorher mittypeof Temporal !== \"undefined\"prüfen.