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 toLocaleDateString()
Methode von Date
Instanzen gibt einen String mit einer sprachsensitiven Darstellung des Datumsanteils dieses Datums in der lokalen Zeitzone zurück. In Implementierungen mit Unterstützung der Intl.DateTimeFormat
API delegiert diese Methode an Intl.DateTimeFormat
.
Jedes Mal, wenn toLocaleDateString
aufgerufen wird, muss eine Suche in einer großen Datenbank von Lokalisierungsstrings durchgeführt werden, was potenziell ineffizient ist. Wenn die Methode mit den gleichen Argumenten häufig 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 Teil der Datenbank zwischenzuspeichern, sodass zukünftige format
Aufrufe nach Lokalisierungsstrings in einem enger begrenzten Kontext 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 locales
und options
Parameter passen das Verhalten der Funktion an und ermöglichen Anwendungen, die Sprache anzugeben, 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 werden aufgefordert, beide Parameter zu ignorieren, wodurch die verwendete Locale und die Form des zurückgegebenen Strings vollständig von der Implementierung abhängen.
locales
Optional-
Ein String mit einem BCP 47 Sprach-Tag, oder ein Array solcher Strings. Entspricht dem
locales
Parameter desIntl.DateTimeFormat()
Konstruktors.In Implementierungen ohne
Intl.DateTimeFormat
Unterstützung wird dieser Parameter ignoriert und normalerweise die Locale des Hosts verwendet. options
Optional-
Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem
options
Parameter desIntl.DateTimeFormat()
Konstruktors. DietimeStyle
Option muss undefiniert sein, sonst würde einTypeError
ausgelöst. Wennweekday
,year
,month
undday
alle undefiniert sind, werdenyear
,month
undday
auf"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 wie sie zu verwenden sind.
Rückgabewert
Ein String, der den Datumsanteil des gegebenen Datums gemäß sprachspezifischen Konventionen darstellt.
In Implementierungen mit Intl.DateTimeFormat
ist dies äquivalent zu new Intl.DateTimeFormat(locales, options).format(date)
, wobei options
wie oben beschrieben normalisiert wurde.
Hinweis:
Meistens ist die durch toLocaleDateString()
zurückgegebene Formatierung konsistent. Die Ausgabe kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Locale — Ausgabevariationen sind im Design vorgesehen und durch die Spezifikation erlaubt. Sie entspricht möglicherweise auch nicht Ihren Erwartungen. Zum Beispiel kann der String geschützte Leerzeichen verwenden oder durch bidirektionale Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleDateString()
nicht mit fest codierten Konstanten vergleichen.
Beispiele
>Verwendung von toLocaleDateString()
Die grundlegende Verwendung dieser Methode ohne Angabe einer locale
gibt einen formatierten String 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 von locales und options Parametern
Die locales
und options
Parameter werden möglicherweise nicht in allen Implementierungen unterstützt, da die Unterstützung der Internationalisierungs-API optional ist und einige Systeme möglicherweise nicht über die notwendigen Daten verfügen. Für Implementierungen ohne Internationalisierungsunterstützung verwendet toLocaleDateString()
immer die System-Locale, was möglicherweise nicht Ihren Wünschen entspricht. Da jede Implementierung, die die locales
und options
Parameter unterstützt, die Intl
API unterstützen muss, können Sie das Vorhandensein letzterer auf Unterstützung überprüfen:
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) mit dem locales
Argument 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 durch 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…