Temporal.PlainDateTime.prototype.year — Eigenschaft · JavaScript-Referenz

Signatur

get Temporal.PlainDateTime.prototype.year

Beschreibung

Die Accessor-Eigenschaft year gibt das Jahr eines Temporal.PlainDateTime-Objekts als Ganzzahl zurück. Gezählt wird ab dem Beginn eines kalenderspezifischen Epochejahres. Im Standardkalender iso8601 ist das Jahr 0 identisch mit 1 v. Chr., das Jahr -1 mit 2 v. Chr. und so weiter. Anders als bei eraYear ist der Wert also auch ohne Angabe einer Ära eindeutig.

Die Eigenschaft ist schreibgeschützt, denn sie hat nur einen Getter. Temporal-Objekte sind unveränderlich. Wer ein anderes Jahr braucht, erzeugt mit with({ year }), add() oder subtract() ein neues Objekt.

Bei Kalendern mit Ären (z. B. gregory oder japanese) kann year von eraYear abweichen: year zählt über alle Ären hinweg durch, eraYear beginnt dagegen in jeder Ära neu. Nutzen Sie year für Berechnungen, Vergleiche und Sortierungen. era/eraYear eignen sich eher für die Anzeige in einem bestimmten Kulturkreis.

Rückgabewert

Typ

number

Beschreibung

Eine Ganzzahl, die positiv, null oder negativ sein kann. Sie gibt das Jahr relativ zum Epochejahr des Kalenders des Objekts an.

Beispiele

Jahr aus einem ISO-Datum mit Uhrzeit lesen

const termin = Temporal.PlainDateTime.from("2021-07-01T12:34:56");
console.log(termin.year);

// Jahre vor unserer Zeitrechnung: Jahr 0 = 1 v. Chr.
const antik = Temporal.PlainDateTime.from("-000044-03-15T12:00");
console.log(antik.year);

2021 -44

year im Vergleich zu eraYear in anderen Kalendern

const jp = Temporal.PlainDateTime.from("2021-07-01T12:34:56[u-ca=japanese]");
console.log(jp.year, jp.era, jp.eraYear);

const he = Temporal.PlainDateTime.from("2021-07-01T12:34:56[u-ca=hebrew]");
console.log(he.year);

2021 reiwa 3 5781

Jahr ändern: neues Objekt mit with() erzeugen

const schalttag = Temporal.PlainDateTime.from("2024-02-29T08:00");

// year ist schreibgeschützt, deshalb ein neues Objekt erzeugen
const naechstesJahr = schalttag.with({ year: schalttag.year + 1 });
console.log(naechstesJahr.toString());

// Mit overflow: "reject" gibt es stattdessen einen Fehler
try {
  schalttag.with({ year: 2025 }, { overflow: "reject" });
} catch (e) {
  console.log(e.constructor.name);
}

2025-02-28T08:00:00 RangeError

Log-Einträge nach Jahr gruppieren

const eintraege = [
  "2023-12-31T23:59",
  "2024-01-01T00:05",
  "2024-06-15T10:00"
].map((s) => Temporal.PlainDateTime.from(s));

const proJahr = Object.groupBy(eintraege, (dt) => dt.year);
for (const [jahr, liste] of Object.entries(proJahr)) {
  console.log(jahr, liste.length);
}

2023 1 2024 2

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie dt.year = 2030 hat keine Wirkung, im Strict Mode wirft sie einen TypeError. Verwenden Sie stattdessen with({ year }).
Kein Jahr 0 in der Ära-Zählung: Im ISO-Kalender entspricht year 0 dem Jahr 1 v. Chr. Für die Anzeige „v. Chr./n. Chr.“ nutzen Sie den Kalender gregory mit era/eraYear oder toLocaleString().
Kalenderabhängig: Bei Nicht-ISO-Kalendern (z. B. hebrew, islamic-civil) weicht der Wert deutlich vom ISO-Jahr ab. Für die Zuordnung zum ISO-Jahr nutzen Sie withCalendar(\"iso8601\").year.
Überlauf beim Jahreswechsel: Wird mit with({ year }) ein 29. Februar in ein Nicht-Schaltjahr verschoben, wird er standardmäßig auf den 28. Februar gesetzt (overflow: \"constrain\").
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar (Firefox 139+, Chrome 144+; Safari noch ohne Unterstützung). Für den produktiven Einsatz empfiehlt sich ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDateTime Temporal.PlainDateTime.prototype.eraYear Temporal.PlainDateTime.prototype.era Temporal.PlainDateTime.prototype.month Temporal.PlainDateTime.prototype.inLeapYear Temporal.PlainDateTime.prototype.with() Temporal.PlainDate.prototype.year