Temporal.PlainYearMonth.prototype.toLocaleString()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die toLocaleString()-Methode von Temporal.PlainYearMonth-Instanzen gibt eine sprachsensitive Darstellung dieses Jahr-Monats als Zeichenkette zurück. In Implementierungen mit Unterstützung für die Intl.DateTimeFormat API delegiert diese Methode an Intl.DateTimeFormat.

Jedes Mal, wenn toLocaleString aufgerufen wird, muss eine Suche in einer großen Datenbank von Lokalisierungszeichenfolgen durchgeführt werden, was potenziell ineffizient sein kann. Wenn die Methode häufig mit denselben Argumenten aufgerufen wird, ist es besser, ein Intl.DateTimeFormat-Objekt zu erstellen und dessen format()-Methode zu verwenden, da ein DateTimeFormat-Objekt sich die übergebenen Argumente merkt und möglicherweise einen Teil der Datenbank im Cache speichert, sodass zukünftige format-Aufrufe innerhalb eines eingeschränkteren Kontexts nach Lokalisierungszeichenfolgen suchen können.

Syntax

js
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Parameter

Die Parameter locales und options passen das Verhalten der Funktion an und ermöglichen es Anwendungen, die Sprache anzugeben, deren Formatierungskonventionen verwendet werden sollen.

In Implementierungen, die die Intl.DateTimeFormat API unterstützen, entsprechen diese Parameter genau den Parametern des Intl.DateTimeFormat()-Konstruktors. Implementierungen ohne Intl.DateTimeFormat-Unterstützung geben exakt dieselbe Zeichenkette wie toString() zurück und ignorieren beide Parameter.

locales Optional

Ein String mit einem BCP 47-Sprachcode oder ein Array solcher Strings. Entspricht dem locales-Parameter des Intl.DateTimeFormat()-Konstruktors.

options Optional

Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem options-Parameter des Intl.DateTimeFormat()-Konstruktors. Die calendar-Option muss mit demselben Wert wie der Kalender dieses Jahr-Monats angegeben werden. In Bezug auf die Datum-Uhrzeit-Komponentenoptionen und die Stilabkürzungen (dateStyle und timeStyle) sollten die Optionen eine dieser Formen folgen:

  • Keine von ihnen angeben: year und month werden standardmäßig auf "numeric" gesetzt.
  • Nur dateStyle angeben: es erweitert sich zu era, year und month-Formaten.
  • Einige Datum-Uhrzeit-Komponentenoptionen angeben, wobei mindestens eine davon year oder month ist. Nur die angegebenen Datumskomponenten werden in die Ausgabe einbezogen.

Siehe den Intl.DateTimeFormat()-Konstruktor für Details zu diesen Parametern und deren Verwendung.

Rückgabewert

Eine Zeichenkette, welche den angegebenen Jahr-Monat gemäß sprachspezifischen Konventionen darstellt.

In Implementierungen mit Intl.DateTimeFormat entspricht dies new Intl.DateTimeFormat(locales, options).format(yearMonth), wobei options wie oben beschrieben normalisiert wurde.

Hinweis: Die von toLocaleString() zurückgegebene Formatierung ist größtenteils konsistent. Allerdings kann die Ausgabe zwischen Implementierungen variieren, selbst innerhalb derselben Locale — Abweichungen sind beabsichtigt und durch die Spezifikation erlaubt. Möglicherweise entspricht sie auch nicht Ihren Erwartungen. Zum Beispiel könnte die Zeichenkette geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit fest codierten Konstanten vergleichen.

Ausnahmen

RangeError

Wird ausgelöst, wenn eine der Optionen ungültig ist.

TypeError

Wird ausgelöst, wenn eine der Optionen nicht den erwarteten Typ hat.

Beispiele

Verwendung von toLocaleString()

Die grundlegende Verwendung dieser Methode ohne Angabe einer locale gibt eine formatierte Zeichenkette in der Standard-Locale und mit den Standardoptionen zurück.

js
// Note that just specifying "2021-08" defaults to the ISO 8601 calendar,
// which throws an error if the locale's default calendar is not ISO 8601.
const ym = Temporal.PlainYearMonth.from("2021-08-01[u-ca=gregory]");

console.log(ym.toLocaleString()); // 8/2021 (assuming en-US locale and Gregorian calendar)

Wenn der Kalender des Jahr-Monats nicht mit dem Standardkalender der Locale übereinstimmt, muss selbst wenn er iso8601 ist, eine explizite calendar-Option mit demselben Wert angegeben werden.

js
const ym = Temporal.PlainYearMonth.from("2021-08");
ym.toLocaleString("en-US", { calendar: "iso8601" }); // 2021-08

Verwendung von toLocaleString() mit Optionen

Sie können anpassen, welche Teile des Jahr-Monats in die Ausgabe einbezogen werden, indem Sie den options-Parameter angeben.

js
const ym = Temporal.PlainYearMonth.from("2021-08-01[u-ca=gregory]");
ym.toLocaleString("en-US", { dateStyle: "full" }); // August 2021
ym.toLocaleString("en-US", { year: "2-digit" }); // 21
ym.toLocaleString("en-US", { month: "long" }); // August

Spezifikationen

Specification
Temporal
# sec-temporal.plainyearmonth.prototype.tolocalestring

Browser-Kompatibilität

Siehe auch