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 einen stringbasierten, sprachsensitiven Darstellung dieses Jahr-Monats zurück. In Implementierungen mit Unterstützung der 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 ist. Wenn die Methode viele Male 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 zwischenspeichert, sodass zukünftige format Aufrufe Lokalisierungszeichenfolgen in einem enger gefassten Kontext 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 zu spezifizieren, deren Formatkonventionen 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 die exakt gleiche Zeichenfolge wie toString() zurück und ignorieren beide Parameter.

locales Optional

Ein Zeichenfolgen mit einem BCP 47 Sprach-Tag oder ein Array solcher Zeichenfolgen. 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 des Jahr-Monats Kalenders bereitgestellt werden. Hinsichtlich der Datums- und Uhrzeitkomponenten Optionen und der stilistischen Abkürzungen (dateStyle und timeStyle) sollten die Optionen eine der folgenden Formen haben:

  • Keine davon angeben: year und month werden standardmäßig auf "numeric" gesetzt.
  • Nur dateStyle angeben: es erweitert sich zu Formaten für era, year und month.
  • Einige Datums- und Uhrzeitkomponenten Optionen angeben, wobei mindestens eine davon year oder month ist. Nur die angegebenen Datumskomponenten werden in die Ausgabe aufgenommen.

Siehe den Intl.DateTimeFormat() Konstruktor für Details zu diesen Parametern und wie man sie verwendet.

Rückgabewert

Eine Zeichenfolge, die das angegebene Jahr und den 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: Meistens ist die von toLocaleString() zurückgegebene Formatierung konsistent. Die Ausgabe kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Locale — Abweichungen sind gewollt und durch die Spezifikationen erlaubt. Es könnte auch nicht das sein, was Sie erwarten. Zum Beispiel könnte die Zeichenfolge geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit fest kodierten 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()

Grundlegende Verwendung dieser Methode ohne eine locale anzugeben, gibt eine formatierte Zeichenfolge in der Standard-Locale und mit 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, selbst wenn sein Kalender iso8601 ist, muss 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 aufgenommen 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 proposal
# sec-temporal.plainyearmonth.prototype.tolocalestring

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch