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 Instanzen von Temporal.PlainYearMonth
gibt eine Zeichenkette mit einer sprachsensitiven Darstellung dieses Jahres-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 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 in einem stärker eingeschränkten Kontext nach Lokalisierungszeichenfolgen suchen können.
Syntax
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
Parameter
Die Parameter locales
und options
passen das Verhalten der Funktion an und lassen Anwendungen die Sprache angeben, 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-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 dem gleichen Wert wie das Kalender des Jahres-Monats angegeben werden. Bezüglich der Datums- und Zeitkomponenten-Optionen und den Stilabkürzungen (dateStyle
undtimeStyle
) sollten die Optionen eine der folgenden Formen haben:- Keine davon angeben:
year
undmonth
werden auf"numeric"
standardmäßig gesetzt. - Nur
dateStyle
angeben: es erweitert sich zu den Formatenera
,year
undmonth
. - Einige Datums- und Zeitkomponenten-Optionen angeben, wobei mindestens eine davon
year
odermonth
ist. Nur die angegebenen Datumskomponenten werden in die Ausgabe einbezogen.
- Keine davon angeben:
Siehe den Intl.DateTimeFormat()
-Konstruktor für Details zu diesen Parametern und deren Verwendung.
Rückgabewert
Eine Zeichenkette, die den angegebenen Jahres-Monat nach sprachspezifischen Konventionen darstellt.
In Implementierungen mit Intl.DateTimeFormat
ist dies äquivalent zu new Intl.DateTimeFormat(locales, options).format(yearMonth)
, wobei options
wie oben beschrieben normalisiert wurde.
Hinweis:
Meistens ist die Formatierung, die von toLocaleString()
zurückgegeben wird, konsistent. Allerdings kann die Ausgabe zwischen Implementierungen variieren, selbst innerhalb desselben Gebietsschemas — Ausgabevariationen sind designbedingt und durch die Spezifikation erlaubt. Sie entspricht möglicherweise auch nicht Ihren Erwartungen. Zum Beispiel kann die Zeichenkette nicht trennbare Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString()
nicht mit hartcodierten 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()
Die grundlegende Nutzung dieser Methode ohne Angabe eines locale
gibt eine formatierte Zeichenkette in der Standardsprache und mit den 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 das Kalender des Jahres-Monats nicht mit dem Standardkalender des Gebietsschemas übereinstimmt, selbst wenn sein Kalender iso8601
ist, muss eine explizite calendar
-Option mit dem gleichen Wert bereitgestellt werden.
const ym = Temporal.PlainYearMonth.from("2021-08");
ym.toLocaleString("en-US", { calendar: "iso8601" }); // 2021-08
Nutzung von toLocaleString() mit Optionen
Sie können anpassen, welche Teile des Jahres-Monats in die Ausgabe einbezogen werden, 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> |
Browser-Kompatibilität
Loading…