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 sprachsensitiv formatierte Zeichenkette 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 umfangreiche Datenbank nach Lokalisierungszeichenfolgen durchsucht 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. Ein DateTimeFormat
Objekt merkt sich die übergebenen Argumente und kann entscheiden, einen Teil der Datenbank zwischenzuspeichern, sodass zukünftige format
Aufrufe innerhalb eines eingeschränkteren Kontexts nach Lokalisierungszeichenfolgen suchen können.
Syntax
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
Parameter
Die locales
und options
Parameter passen das Verhalten der Funktion an und ermöglichen es Anwendungen, die Sprache zu spezifizieren, 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 genau dieselbe Zeichenkette zurück wie toString()
, wobei beide Parameter ignoriert werden.
locales
Optional-
Ein String mit einem BCP 47 Sprach-Tag oder ein Array solcher Strings. Entspricht dem
locales
Parameter desIntl.DateTimeFormat()
Konstruktors. options
Optional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
options
Parameter desIntl.DateTimeFormat()
Konstruktors. Diecalendar
Option muss mit demselben Wert wie der Kalender dieses Jahr-Monats angegeben werden. Bezüglich der Datum-Zeit Komponenten-Optionen und der Stilabkürzungen (dateStyle
undtimeStyle
) sollten die Optionen eine der folgenden Formen haben:- Keine davon angeben:
year
undmonth
werden standardmäßig auf"numeric"
gesetzt. - Nur
dateStyle
angeben: es wird inera
,year
undmonth
Formate umgewandelt. - Einige Datum-Zeit Komponenten-Optionen angeben, wobei mindestens eine davon
year
odermonth
ist. Nur die angegebenen Datumsbestandteile werden in der Ausgabe enthalten sein.
- Keine davon angeben:
Siehe den Intl.DateTimeFormat()
Konstruktor für Details zu diesen Parametern und ihrer Verwendung.
Rückgabewert
Eine Zeichenkette, die 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:
Meistens ist das von toLocaleString()
zurückgegebene Format konsistent. Allerdings kann die Ausgabe zwischen Implementierungen, sogar innerhalb derselben Lokale, variieren — Ausgabevariationen sind von der Spezifikation vorgesehen und erlaubt. Es kann auch nicht das sein, was Sie erwarten. 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 vom erwarteten Typ ist.
Beispiele
Verwendung von toLocaleString()
Der einfache Einsatz dieser Methode ohne Angabe eines locale
gibt eine formatierte Zeichenkette in der Standardlokale und mit Standardoptionen zurück.
// 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 Lokale übereinstimmt, selbst wenn sein Kalender iso8601
ist, muss eine explizite calendar
Option mit demselben Wert angegeben werden.
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 der Ausgabe enthalten sind, indem Sie den options
Parameter angeben.
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 |