Temporal.PlainYearMonth.prototype.toLocaleString()
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Die Methode toLocaleString() von Temporal.PlainYearMonth Instanzen gibt eine sprachsensitive Zeichenkette mit einer Darstellung des Jahres-Monats 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 Lokalisierungsstrings 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 seine Methode format() zu verwenden, da ein DateTimeFormat-Objekt sich die übergebenen Argumente merkt und möglicherweise einen Teil der Datenbank zwischenspeichert, sodass zukünftige format Aufrufe innerhalb eines eingeschränkten Kontexts nach Lokalisierungsstrings suchen können.
Syntax
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
Parameter
Die Parameter locales und options passen das Verhalten der Funktion an und erlauben 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 denselben String wie toString() zurück und ignorieren beide Parameter.
localesOptional-
Ein String mit einem BCP 47 Sprach-Tag, oder ein Array solcher Strings. Entspricht dem
localesParameter desIntl.DateTimeFormat()Konstruktors. optionsOptional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
optionsParameter desIntl.DateTimeFormat()Konstruktors. DiecalendarOption muss mit demselben Wert wie der Kalender von diesem Jahres-Monat angegeben werden. Bezüglich der Optionskomponenten für Datum und Uhrzeit und den Stilabkürzungen (dateStyleundtimeStyle) sollten die Optionen einer der folgenden Formen folgen:- Keine von ihnen bereitstellen:
yearundmonthhaben standardmäßig den Wert"numeric". - Nur
dateStylebereitstellen: es erweitert sich zuera,yearundmonthFormaten. - Einige Optionskomponenten für Datum und Uhrzeit bereitstellen, wobei mindestens eine von ihnen
yearodermonthist. Nur die angegebenen Datumsbestandteile werden in die Ausgabe eingeschlossen.
- Keine von ihnen bereitstellen:
Siehe den Intl.DateTimeFormat() Konstruktor für Details zu diesen Parametern und deren Verwendung.
Rückgabewert
Eine Zeichenkette, die das gegebene Jahr-Monat entsprechend 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 Formatierung von toLocaleString() konsistent. Allerdings kann sich die Ausgabe zwischen Implementierungen unterscheiden, sogar innerhalb desselben Gebietsschemas – Abweichungen in der Ausgabe sind beabsichtigt und durch die Spezifikation erlaubt. Sie könnte auch nicht Ihren Erwartungen entsprechen. Zum Beispiel könnte die Zeichenkette geschützte Leerzeichen verwenden oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleString() nicht mit festkodierten 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 Verwendung dieser Methode ohne Angabe eines locale gibt eine formatierte Zeichenkette im Standardgebietsschema 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 Jahres-Monats nicht mit dem Standardkalender des Gebietsschemas übereinstimmt, auch wenn sein Kalender iso8601 ist, muss eine explizite calendar Option mit demselben Wert bereitgestellt 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 Jahres-Monats in die Ausgabe aufgenommen werden, indem Sie den Parameter options bereitstellen.
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 |