Date.prototype.toLocaleDateString()
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since Juli 2015.
Die Methode toLocaleDateString() von Date-Instanzen gibt eine zeichenfolgenbasierte, sprachenspezifische Darstellung des Datumsanteils dieses Datums in der lokalen Zeitzone 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 in einer großen Datenbank von Lokalisierungszeichenfolgen gesucht werden, was potenziell ineffizient ist. Wenn die Methode oft 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 entscheidet, einen Ausschnitt der Datenbank zu zwischenspeichern, sodass zukünftige format-Aufrufe innerhalb eines eingeschränkteren Kontextes nach Lokalisierungszeichenfolgen suchen können.
Probieren Sie es aus
const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
const options = {
weekday: "long",
year: "numeric",
month: "long",
day: "numeric",
};
console.log(event.toLocaleDateString("de-DE", options));
// Expected output (varies according to local timezone): Donnerstag, 20. Dezember 2012
console.log(event.toLocaleDateString("ar-EG", options));
// Expected output (varies according to local timezone): الخميس، ٢٠ ديسمبر، ٢٠١٢
console.log(event.toLocaleDateString(undefined, options));
// Expected output (varies according to local timezone and default locale): Thursday, December 20, 2012
Syntax
toLocaleDateString()
toLocaleDateString(locales)
toLocaleDateString(locales, options)
Parameter
Die Parameter locales und options passen das Verhalten der Funktion an und ermöglichen Anwendungen die Spezifikation der Sprache, deren Formatierungskonventionen verwendet werden sollen.
In Implementierungen, die die Intl.DateTimeFormat API unterstützen, entsprechen diese Parameter genau den Parametern des Konstruktors Intl.DateTimeFormat(). Implementierungen ohne Intl.DateTimeFormat-Unterstützung werden gebeten, beide Parameter zu ignorieren, was die verwendete Gebietsschema und die Form der zurückgegebenen Zeichenfolge vollständig implementierungsabhängig macht.
localesOptional-
Ein String mit einem BCP 47-Sprachkennzeichen oder ein Array solcher Strings. Entspricht dem
localesParameter des KonstruktorsIntl.DateTimeFormat().In Implementierungen ohne
Intl.DateTimeFormat-Unterstützung wird dieser Parameter ignoriert und normalerweise das Gebietsschema des Hosts verwendet. optionsOptional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
optionsParameter des KonstruktorsIntl.DateTimeFormat(). Die OptiontimeStylemuss undefiniert sein, sonst wird einTypeErrorausgelöst. Wennweekday,year,monthunddayalle undefiniert sind, werdenyear,monthunddayauf"numeric"gesetzt.In Implementierungen ohne
Intl.DateTimeFormat-Unterstützung wird dieser Parameter ignoriert.
Siehe den Intl.DateTimeFormat()-Konstruktor für Details zu diesen Parametern und deren Verwendung.
Rückgabewert
Eine Zeichenfolge, die den Datumsanteil des angegebenen Datums gemäß sprachspezifischen Konventionen darstellt.
In Implementierungen mit Intl.DateTimeFormat entspricht dies new Intl.DateTimeFormat(locales, options).format(date), wobei options wie oben beschrieben normalisiert wurde.
Hinweis:
Meistens ist das von toLocaleDateString() zurückgegebene Format konsistent. Allerdings kann die Ausgabe zwischen Implementierungen variieren, selbst innerhalb desselben Gebietsschemas — Abweichungen sind absichtlich und durch die Spezifikation 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 toLocaleDateString() nicht mit fest codierten Konstanten vergleichen.
Beispiele
Verwendung von toLocaleDateString()
Die grundsätzliche Nutzung dieser Methode ohne Spezifizierung eines locale gibt eine formatierte Zeichenfolge in der Standardsprache und mit den Standardeinstellungen zurück.
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));
// toLocaleDateString() without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(date.toLocaleDateString());
// "12/11/2012" if run in en-US locale with time zone America/Los_Angeles
Prüfen der Unterstützung für die Parameter locales und options
Die Parameter locales und options werden möglicherweise nicht in allen Implementierungen unterstützt, da die Unterstützung für die Internationalisierungs-API optional ist und einige Systeme eventuell nicht über die notwendigen Daten verfügen. In Implementierungen ohne Internationalisierungsunterstützung verwendet toLocaleDateString() immer das Systemgebietsschema, was eventuell nicht das ist, was Sie möchten. Da jede Implementierung, die die Parameter locales und options unterstützt, die Intl-API unterstützen muss, können Sie deren Existenz überprüfen, um Unterstützung sicherzustellen:
function toLocaleDateStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.DateTimeFormat === "function"
);
}
Verwendung von locales
Dieses Beispiel zeigt einige der Variationen in lokalisierten Datumsformaten. Um das Format der Sprache zu erhalten, die in der Benutzeroberfläche Ihrer Anwendung verwendet wird, stellen Sie sicher, dass Sie diese Sprache (und möglicherweise einige Ersatzsprachen) mithilfe des locales-Arguments angeben:
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// formats below assume the local time zone of the locale;
// America/Los_Angeles for the US
// US English uses month-day-year order
console.log(date.toLocaleDateString("en-US"));
// "12/20/2012"
// British English uses day-month-year order
console.log(date.toLocaleDateString("en-GB"));
// "20/12/2012"
// Korean uses year-month-day order
console.log(date.toLocaleDateString("ko-KR"));
// "2012. 12. 20."
// Event for Persian, It's hard to manually convert date to Solar Hijri
console.log(date.toLocaleDateString("fa-IR"));
// "۱۳۹۱/۹/۳۰"
// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(date.toLocaleDateString("ar-EG"));
// "٢٠/١٢/٢٠١٢"
// for Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
console.log(date.toLocaleDateString("ja-JP-u-ca-japanese"));
// "24/12/20"
// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(date.toLocaleDateString(["ban", "id"]));
// "20/12/2012"
Verwendung von options
Die von toLocaleDateString() bereitgestellten Ergebnisse können mit dem options-Parameter angepasst werden:
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// Request a weekday along with a long date
const options = {
weekday: "long",
year: "numeric",
month: "long",
day: "numeric",
};
console.log(date.toLocaleDateString("de-DE", options));
// "Donnerstag, 20. Dezember 2012"
// An application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleDateString("en-US", options));
// "Thursday, December 20, 2012, UTC"
Spezifikationen
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-date.prototype.tolocaledatestring |
| ECMAScript® 2026 Internationalization API Specification # sup-date.prototype.tolocaledatestring |
Browser-Kompatibilität
Loading…