Temporal.Duration.prototype.years — Eigenschaft · JavaScript-Referenz

Signatur

get Temporal.Duration.prototype.years

Beschreibung

Die Zugriffs-Eigenschaft years liest das Jahresfeld einer Temporal.Duration. Der Wert ist immer eine ganze Zahl. Bei einer negativen Dauer ist er kleiner oder gleich 0, bei einer positiven größer oder gleich 0. Alle Felder einer Dauer haben dasselbe Vorzeichen, das Sie über sign abfragen können.

Wichtig: years gibt nur das zurück, was tatsächlich im Jahresfeld gespeichert ist. Eine Dauer wird nicht automatisch ausgeglichen. Temporal.Duration.from({ months: 30 }) hat also years === 0 und months === 30. Wie viele Jahre das sind, hängt vom Kalender und vom Startdatum ab. Um Monate in Jahre umzurechnen, rufen Sie round() mit largestUnit: "years" und einem relativeTo-Datum auf.

Die Eigenschaft hat nur einen Getter. Temporal.Duration-Objekte sind unveränderlich. Einen anderen Jahreswert bekommen Sie mit with({ years: … }), das ein neues Objekt erzeugt. Typische Einsätze sind Altersberechnungen, Laufzeiten von Verträgen und die Anzeige von Zeitspannen, die mit until() oder since() berechnet wurden.

Rückgabewert

Typ

number

Beschreibung

Ganze Zahl mit der Anzahl der Jahre im Jahresfeld der Dauer. Bei negativen Dauern ist der Wert negativ oder 0.

Beispiele

Jahre aus einer ISO-8601-Dauer lesen

const laufzeit = Temporal.Duration.from("P3Y6M");
console.log(laufzeit.years);  // 3
console.log(laufzeit.months); // 6

3 6

Alter berechnen mit until()

const geburt = Temporal.PlainDate.from("1990-05-15");
const heute = Temporal.PlainDate.from("2025-03-01");

// Ohne largestUnit liefert PlainDate.until() nur Tage!
const alter = geburt.until(heute, { largestUnit: "years" });
console.log(`Alter: ${alter.years} Jahre`);
console.log(alter.toString());

Alter: 34 Jahre P34Y9M14D

Kein automatischer Ausgleich: Monate in Jahre umrechnen

const d = Temporal.Duration.from({ months: 30 });
console.log(d.years); // 0 – die Monate werden nicht umgerechnet

const ausgeglichen = d.round({
  largestUnit: "years",
  relativeTo: Temporal.PlainDate.from("2024-01-01"),
});
console.log(ausgeglichen.years, ausgeglichen.months);

0 2 6

Negative Dauer und Ändern mit with()

const rueckblick = Temporal.Duration.from("-P2Y");
console.log(rueckblick.years);           // -2
console.log(rueckblick.negated().years); // 2

// Unveränderlich: with() erzeugt eine neue Dauer
const verlaengert = Temporal.Duration.from("P1Y").with({ years: 5 });
console.log(verlaengert.years);

-2 2 5

// Wichtig · Fallstricke

Kein automatischer Ausgleich: years rechnet Monate, Wochen oder Tage nicht in Jahre um. Dafür brauchen Sie round({ largestUnit: "years", relativeTo }). Ohne relativeTo wirft round() einen RangeError, weil Jahre und Monate unterschiedlich lang sind.
until()/since(): PlainDate und PlainDateTime verwenden standardmäßig largestUnit: "days", Instant und ZonedDateTime sogar "hours". years ist dann 0, solange Sie largestUnit nicht auf "years" setzen.
Nur lesbar: Eine Zuweisung wie d.years = 5 hat keine Wirkung (im Strict Mode gibt es einen TypeError). Verwenden Sie with().
Vorzeichen: Den Betrag bekommen Sie mit Math.abs(d.years) oder d.abs().years. Das Vorzeichen der ganzen Dauer liefert d.sign.
Kompatibilität: Temporal ist neu und noch nicht überall verfügbar (Firefox ab 139, Chrome ab 144; Safari fehlt noch). Für ältere Umgebungen gibt es Polyfills wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.Duration Temporal.Duration.prototype.months Temporal.Duration.prototype.days Temporal.Duration.prototype.sign Temporal.Duration.prototype.round() Temporal.Duration.prototype.with() Temporal.PlainDate.prototype.until()