</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.PlainDate.prototype.until()

Temporal.PlainDate.prototype.until()

Methode

Berechnet die Dauer vom aktuellen <code>Temporal.PlainDate</code> bis zu einem anderen Datum und gibt sie als <code>Temporal.Duration</code> zurück.

seit JavaScript ES2026 (Temporal) – Firefox 139+, Chrome 144+; son Kategorie: method-property

Signatur

Temporal.PlainDate.prototype.until(other, options)

Beschreibung

until() berechnet den Abstand zwischen zwei Kalenderdaten ohne Uhrzeit und ohne Zeitzone. Das Ergebnis ist ein Temporal.Duration-Objekt. Es ist positiv, wenn other nach dem aktuellen Datum liegt, und negativ, wenn es davor liegt. Die Methode ist das Gegenstück zu since(): a.until(b) entspricht b.since(a).

Ohne Optionen gibt die Methode nur Tage zurück, zum Beispiel P344D. Mit largestUnit legen Sie fest, bis zu welcher Einheit das Ergebnis in Jahre, Monate oder Wochen aufgeteilt wird. Das ist nützlich für Altersangaben, Vertragslaufzeiten oder Countdowns wie „noch 2 Monate und 5 Tage“. Mit smallestUnit, roundingIncrement und roundingMode lässt sich das Ergebnis zusätzlich runden.

Die Berechnung berücksichtigt den Kalender, also unterschiedlich lange Monate und Schaltjahre. Deshalb ist sie verlässlicher als das Rechnen mit Millisekunden-Differenzen über Date. Beide Daten müssen denselben Kalender verwenden.

Parameter

Name Typ Default Beschreibung
$other Pflicht Temporal.PlainDate | string | object Das Zieldatum. Ein String wie "2024-12-24" oder ein Objekt wie { year, month, day } wird wie bei Temporal.PlainDate.from() umgewandelt.
$options object {} Optionales Einstellungsobjekt mit folgenden Feldern:
  • largestUnit: "auto" (Standard, bedeutet "day"), "year", "month", "week" oder "day"
  • smallestUnit: kleinste Einheit im Ergebnis, Standard "day"
  • roundingIncrement: Rundungsschritt, Standard 1
  • roundingMode: z. B. "trunc" (Standard), "floor", "ceil", "halfExpand"

Rückgabewert

Typ
Temporal.Duration
Beschreibung
Eine neue Temporal.Duration vom aktuellen Datum bis other. Sie ist negativ, wenn other früher liegt. Zeitanteile (Stunden und kleiner) sind immer 0.

Beispiele

Tage bis Weihnachten (Standardverhalten)

const start = Temporal.PlainDate.from("2024-01-15");
const heiligabend = Temporal.PlainDate.from("2024-12-24");

const dauer = start.until(heiligabend);
console.log(dauer.toString());
console.log(dauer.days);

// Umgekehrte Richtung ergibt eine negative Dauer
console.log(heiligabend.until(start).toString());
P344D 344 -P344D

Alter in Jahren, Monaten und Tagen berechnen

const geburtstag = Temporal.PlainDate.from("1990-05-20");
const heute = Temporal.PlainDate.from("2025-03-10");
// In echtem Code: Temporal.Now.plainDateISO()

const alter = geburtstag.until(heute, { largestUnit: "year" });
console.log(alter.toString());
console.log(`${alter.years} Jahre, ${alter.months} Monate, ${alter.days} Tage`);
P34Y9M18D 34 Jahre, 9 Monate, 18 Tage

In Monate oder Wochen aufteilen und runden

const start = Temporal.PlainDate.from("2024-01-15");
const ende = Temporal.PlainDate.from("2024-12-24");

console.log(start.until(ende, { largestUnit: "month" }).toString());
console.log(start.until(ende, { largestUnit: "week" }).toString());

// Auf ganze Monate runden (kaufmännisch)
const gerundet = start.until(ende, {
  smallestUnit: "month",
  roundingMode: "halfExpand"
});
console.log(gerundet.toString());
P11M9D P49W1D P11M

Countdown mit String-Argument

const heute = Temporal.PlainDate.from("2025-06-01");
const rest = heute.until("2025-08-15", { largestUnit: "month" });

const text = rest.sign > 0
  ? `Noch ${rest.months} Monate und ${rest.days} Tage bis zum Urlaub`
  : "Der Urlaub hat schon begonnen!";
console.log(text);
Noch 2 Monate und 14 Tage bis zum Urlaub

// Wichtig · Fallstricke

  • Browser-Unterstützung: Temporal ist noch neu. Es gibt es ab Firefox 139 und Chrome/Edge 144. Safari und ältere Node.js-Versionen unterstützen es teilweise noch nicht. Dort brauchen Sie einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.
  • Standard ist nur Tage: Ohne largestUnit erhalten Sie nie Jahre oder Monate, sondern z. B. P344D. Für Altersangaben setzen Sie largestUnit: \"year\".
  • Keine Zeiteinheiten: Werte wie \"hour\" oder \"minute\" für largestUnit oder smallestUnit lösen einen RangeError aus. Für Uhrzeiten verwenden Sie Temporal.PlainDateTime oder Temporal.ZonedDateTime.
  • Kalender: Verwenden beide Daten unterschiedliche Kalender (z. B. iso8601 und hebrew), wird ein RangeError ausgelöst.
  • Standardmäßig wird abgeschnitten: Der Standard-roundingMode ist \"trunc\". Beim Runden mit smallestUnit fallen Reste also weg, solange Sie keinen anderen Modus angeben.
  • Monate sind unterschiedlich lang: Eine Dauer wie P1M hat je nach Startdatum eine andere Anzahl Tage. Wenn Sie solche Dauern vergleichen oder umrechnen (Duration.compare(), total()), müssen Sie relativeTo angeben.

Siehe auch

Temporal.PlainTime.prototype.until() Temporal.PlainDate.prototype.with() Temporal.PlainDateTime.prototype.until() Temporal.PlainDate.prototype.add() Temporal.PlainDate.prototype.equals()
← Vorheriger Eintrag Temporal.PlainDate.prototype.toZonedDateTime()