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 September 2017.
Die toLocaleDateString()
-Methode von Date
-Instanzen gibt eine sprachsensitiv formatierte Darstellung des Datumsanteils in der lokalen Zeitzone als Zeichenkette 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 mit Lokalisierungszeichenketten durchgeführt werden, was potenziell ineffizient sein kann. 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 entscheidet, einen Teil der Datenbank zwischenzuspeichern. Dadurch können zukünftige format
-Aufrufe Lokalisierungszeichenketten in einem stärker eingeschränkten Kontext suchen.
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 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 Konstruktors Intl.DateTimeFormat()
. In Implementierungen ohne Intl.DateTimeFormat
-Unterstützung werden beide Parameter ignoriert. In diesem Fall ist die verwendete Locale und die Form der zurückgegebenen Zeichenkette vollständig implementationsabhängig.
locales
Optional-
Eine Zeichenkette mit einem BCP 47-Sprach-Tag oder ein Array solcher Zeichenketten. Entspricht dem
locales
-Parameter desIntl.DateTimeFormat()
-Konstruktors.In Implementierungen ohne
Intl.DateTimeFormat
-Unterstützung wird dieser Parameter ignoriert, und normalerweise wird die Locale des Hosts verwendet. options
Optional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
options
-Parameter desIntl.DateTimeFormat()
-Konstruktors. DietimeStyle
-Option mussundefined
sein, andernfalls wird einTypeError
ausgelöst. Wennweekday
,year
,month
undday
alleundefined
sind, werdenyear
,month
undday
auf"numeric"
gesetzt.In Implementierungen ohne
Intl.DateTimeFormat
-Unterstützung wird dieser Parameter ignoriert.
Details zu diesen Parametern und deren Verwendung finden Sie im Abschnitt zum Intl.DateTimeFormat()
-Konstruktor.
Rückgabewert
Eine Zeichenkette, die den Datumsanteil des angegebenen Datums entsprechend sprachspezifischer 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 die von toLocaleDateString()
zurückgegebene Formatierung konsistent. Der Output kann jedoch je nach Implementierung, sogar innerhalb derselben Locale, variieren — diese Variationen sind beabsichtigt und durch die Spezifikation erlaubt. Außerdem kann der Output nicht unbedingt das sein, was Sie erwarten. Zum Beispiel könnte die Zeichenkette geschützte Leerzeichen enthalten oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleDateString()
nicht mit hartkodierten Konstanten vergleichen.
Beispiele
Verwendung von toLocaleDateString()
Die einfache Nutzung dieser Methode ohne Angabe einer locale
gibt eine formatierte Zeichenkette in der Standard-Locale und mit Standardoptionen 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
Überprüfung der Unterstützung für die Parameter locales und options
Die Parameter locales
und options
werden möglicherweise nicht in allen Implementierungen unterstützt, weil die Unterstützung für die Internationalisierungs-API optional ist und einige Systeme möglicherweise nicht die erforderlichen Daten bereitstellen. In Implementierungen ohne Unterstützung für die Internationalisierung verwendet toLocaleDateString()
immer die Locale des Systems, was möglicherweise nicht Ihren Anforderungen entspricht. Da jede Implementierung, die die Parameter locales
und options
unterstützt, auch die Intl
-API unterstützen muss, können Sie deren Existenz überprüfen, um die Unterstützung zu kontrollieren:
function toLocaleDateStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.DateTimeFormat === "function"
);
}
Verwendung von locales
Dieses Beispiel zeigt einige der Variationen in lokalisierten Datumsformaten. Um sicherzustellen, dass das Format der Sprache verwendet wird, die in der Benutzeroberfläche Ihrer Anwendung genutzt wird, sollten Sie diese Sprache (und gegebenenfalls alternative Sprachen) mit dem Argument locales
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 Ergebnisse, die von toLocaleDateString()
bereitgestellt werden, können mit dem Parameter options
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® 2025 Language Specification # sec-date.prototype.tolocaledatestring |
ECMAScript® 2025 Internationalization API Specification # sup-date.prototype.tolocaledatestring |
Browser-Kompatibilität
Report problems with this compatibility data on GitHubdesktop | mobile | server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
toLocaleDateString | ||||||||||||||
IANA time zone names in timeZone option | ||||||||||||||
locales parameter | ||||||||||||||
options parameter |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- Has more compatibility info.