Temporal.PlainYearMonth.prototype.toString() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainYearMonth.prototype.toString(options)

Beschreibung

toString() wandelt eine Temporal.PlainYearMonth-Instanz in einen Text im Format RFC 9557 um, der ISO 8601 erweitert. Im Standardfall mit ISO-Kalender entsteht die kompakte Form YYYY-MM, z. B. "2024-03". Genau dieses Format erwarten auch <input type="month">-Felder und viele REST-Schnittstellen.

Den erzeugten String liest Temporal.PlainYearMonth.from() ohne Verlust wieder ein. Deshalb eignet sich die Methode gut zum Speichern, Serialisieren (z. B. in localStorage oder URLs) und für den Austausch zwischen Systemen. Auch toJSON() und String-Umwandlungen in Template-Literalen liefern dasselbe Ergebnis.

Bei einem anderen Kalender als iso8601 (oder mit calendarName: "always" bzw. "critical") reicht die kurze Form nicht aus. Dann wird das ISO-Datum des internen Referenztags ausgegeben (YYYY-MM-DD), gefolgt von einer Annotation wie [u-ca=hebrew]. Nur so lässt sich der Monat eindeutig rekonstruieren.

Für lesbare, sprachabhängige Ausgaben an Nutzer ist toLocaleString() gedacht. toString() liefert immer ein maschinenlesbares Format.

Parameter

Name	Typ	Default	Beschreibung
$options	object	undefined	Optionales Objekt mit der Eigenschaft `calendarName`.
$options.calendarName	"auto" \| "always" \| "never" \| "critical"	"auto"	Legt fest, ob eine Kalender-Annotation angehängt wird. `"auto"`: nur bei einem anderen Kalender als ISO. `"always"`: immer, also auch `[u-ca=iso8601]`. `"never"`: nie. `"critical"`: immer, mit Kritisch-Kennzeichen `[!u-ca=…]`. Bei `"always"`/`"critical"` oder einem Nicht-ISO-Kalender wird zusätzlich der Referenztag ausgegeben.

Rückgabewert

Typ

string

Beschreibung

Ein String im RFC 9557-Format, z. B. "2021-08", "2021-08-01[u-ca=iso8601]" oder bei Jahren außerhalb von 0–9999 im erweiterten Format "+012345-01" bzw. "-000100-03".

Beispiele

Standardausgabe und Rundreise über from()

const ym = Temporal.PlainYearMonth.from({ year: 2021, month: 8 });
const text = ym.toString();
console.log(text);

// Verlustfrei wieder einlesen
const wieder = Temporal.PlainYearMonth.from(text);
console.log(wieder.equals(ym));

2021-08 true

Kalender-Annotation mit calendarName steuern

const ym = new Temporal.PlainYearMonth(2021, 8);

console.log(ym.toString({ calendarName: "auto" }));
console.log(ym.toString({ calendarName: "always" }));
console.log(ym.toString({ calendarName: "critical" }));
console.log(ym.toString({ calendarName: "never" }));

2021-08 2021-08-01[u-ca=iso8601] 2021-08-01[!u-ca=iso8601] 2021-08

Wert für ein <input type="month"> setzen

// Vorbelegung mit dem aktuellen Monat
const aktuellerMonat = Temporal.Now.plainDateISO().toPlainYearMonth();
const input = document.querySelector('input[type="month"]');
input.value = aktuellerMonat.toString(); // z. B. "2025-06"

// Nutzereingabe zurück in ein Temporal-Objekt
input.addEventListener("change", () => {
  const gewaehlt = Temporal.PlainYearMonth.from(input.value);
  console.log(`Gewählt: ${gewaehlt.toString()}, Tage im Monat: ${gewaehlt.daysInMonth}`);
});

Erweitertes Jahresformat und JSON-Serialisierung

const antik = new Temporal.PlainYearMonth(-100, 3);
console.log(antik.toString());

const abrechnung = { periode: new Temporal.PlainYearMonth(2024, 12) };
console.log(JSON.stringify(abrechnung));

-000100-03 {"periode":"2024-12"}

// Wichtig · Fallstricke

Browser-Unterstützung: Temporal ist neu. Firefox unterstützt es ab Version 139, Chrome/Edge ab 144. Safari und ältere Umgebungen brauchen ein Polyfill (z. B. @js-temporal/polyfill oder temporal-polyfill).
Nicht für Vergleiche verwenden: valueOf() wirft einen TypeError, daher funktionieren </> nicht direkt. Wer stattdessen Strings vergleicht, bekommt bei negativen oder erweiterten Jahren und bei Kalender-Annotationen falsche Ergebnisse. Besser: Temporal.PlainYearMonth.compare() oder equals().
Referenztag: Bei Nicht-ISO-Kalendern oder calendarName: \"always\" enthält die Ausgabe einen Tag (YYYY-MM-DD). Das ist der interne Referenztag und kein vom Nutzer gewählter Tag. Mit \"never\" geht bei Nicht-ISO-Kalendern die Kalenderinformation verloren.
Ein ungültiger Wert für calendarName löst einen RangeError aus.
Für Ausgaben an Nutzer toLocaleString() oder Intl.DateTimeFormat verwenden, nicht toString().

Siehe auch

Temporal.PlainYearMonth Temporal.PlainYearMonth.from() Temporal.PlainYearMonth.prototype.toJSON() Temporal.PlainYearMonth.prototype.toLocaleString() Temporal.PlainYearMonth.compare() Temporal.PlainDate.prototype.toString()