Temporal.PlainDate.prototype.toLocaleString()
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
Die toLocaleString()-Methode von Temporal.PlainDate Instanzen gibt einen String mit einer sprachabhängigen Darstellung dieses Datums 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 dessen format() Methode zu verwenden, da ein DateTimeFormat-Objekt die übergebenen Argumente speichert und möglicherweise einen Teil der Datenbank zwischenspeichert, sodass zukünftige format-Aufrufe Lokalisierungsstrings in einem engeren Kontext durchsuchen 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 Unterstützung für Intl.DateTimeFormat geben denselben String zurück wie toString(), wobei beide Parameter ignoriert werden.
localesOptional-
Ein String mit einem BCP 47 Sprach-Tag oder ein Array solcher Strings. Entspricht dem
locales-Parameter desIntl.DateTimeFormat()-Konstruktors. optionsOptional-
Ein Objekt, das die Ausgabeform anpasst. Entspricht dem
options-Parameter desIntl.DateTimeFormat()-Konstruktors. Wenn der Kalender dieses Datums nicht"iso8601"ist, muss diecalendar-Option mit demselben Wert angegeben werden; andernfalls kann diecalendar-Option bei einem"iso8601"Datum einen beliebigen Wert haben. In Bezug auf die Datums- und Zeit-Komponentenoptionen und die Stil-Verknüpfungen (dateStyleundtimeStyle) sollten die Optionen eine dieser Formen annehmen:- Keine davon bereitstellen:
year,monthunddayverwenden standardmäßig"numeric". - Nur
dateStylebereitstellen: es erweitert sich zuweekday,era,year,monthunddayFormaten. - Einige Datums- und Zeit-Komponentenoptionen bereitstellen, wobei mindestens eine davon eine Datumsoption ist (
weekday,year,month,day). Nur die angegebenen Datums-Komponenten werden in die Ausgabe aufgenommen.
- Keine davon bereitstellen:
Siehe den Intl.DateTimeFormat()-Konstruktor für Details zu diesen Parametern und deren Verwendung.
Rückgabewert
Ein String, der das gegebene Datum gemäß sprachspezifischen Konventionen darstellt.
In Implementierungen mit Intl.DateTimeFormat ist dies gleichbedeutend mit new Intl.DateTimeFormat(locales, options).format(date), wobei options wie oben beschrieben normalisiert wurde.
Hinweis:
In den meisten Fällen ist die durch toLocaleString() zurückgegebene Formatierung konsistent. Das Ergebnis kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Lokalisierung — Variationen sind designbedingt und von der Spezifikation erlaubt. Es könnte auch nicht dem entsprechen, was Sie erwarten. Zum Beispiel könnte der String nicht trennbare 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 den erwarteten Typ hat.
Beispiele
Verwendung von toLocaleString()
Grundlegende Verwendung dieser Methode ohne Angabe einer locale gibt einen formatierten String in der Standardsprache und mit Standardoptionen zurück.
const date = Temporal.PlainDate.from("2021-08-01");
console.log(date.toLocaleString()); // 8/1/2021 (assuming en-US locale)
Wenn der Kalender des Datums nicht mit dem Standardkalender der Lokalisierung übereinstimmt und der Kalender des Datums nicht iso8601 ist, muss eine explizite calendar-Option mit demselben Wert angegeben werden.
const date = Temporal.PlainDate.from("2021-08-01[u-ca=japanese]");
// The ja-JP locale uses the Gregorian calendar by default
date.toLocaleString("ja-JP", { calendar: "japanese" }); // R3/8/1
Verwendung von toLocaleString() mit Optionen
Sie können anpassen, welche Teile des Datums in die Ausgabe aufgenommen werden, indem Sie den options-Parameter bereitstellen.
const date = Temporal.PlainDate.from("2021-08-01");
date.toLocaleString("en-US", { dateStyle: "full" }); // Sunday, August 1, 2021
date.toLocaleString("en-US", {
year: "numeric",
month: "long",
day: "numeric",
}); // August 1, 2021
date.toLocaleString("en-US", { year: "numeric", month: "long" }); // August 2021
Spezifikationen
| Specification |
|---|
| Temporal # sec-temporal.plaindate.prototype.tolocalestring |