Date.prototype.toLocaleDateString() — Methode · JavaScript-Referenz

Signatur

toLocaleDateString() / toLocaleDateString(locales) / toLocaleDateString(locales, options)

Beschreibung

Die Methode toLocaleDateString() 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 viele Male 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 einen Teil der Datenbank zwischenspeichern kann, sodass zukünftige format-Aufrufe Lokalisierungsstrings in einem enger begrenzten Kontext suchen können.

Die Parameter locales und options passen das Verhalten der Funktion an und ermöglichen es Anwendungen, die Sprache anzugeben, deren Formatierungskonventionen verwendet werden sollen.

In Implementierungen, die die Intl.DateTimeFormat-API unterstützen, entsprechen diese Parameter exakt 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 implementierungsabhängig sind.

Weitere Details zu diesen Parametern und ihrer Verwendung finden Sie beim Intl.DateTimeFormat()-Konstruktor.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[]	—	Ein String mit einem BCP-47-Sprach-Tag oder ein Array solcher Strings. Entspricht dem `locales`-Parameter des `Intl.DateTimeFormat()`-Konstruktors. In Implementierungen ohne `Intl.DateTimeFormat`-Unterstützung wird dieser Parameter ignoriert und in der Regel die Locale des Hosts verwendet.
$options	Object	—	Ein Objekt, das das Ausgabeformat anpasst. Entspricht dem `options`-Parameter des `Intl.DateTimeFormat()`-Konstruktors. Die Option `timeStyle` muss `undefined` sein, andernfalls wird ein `TypeError` geworfen. Wenn `weekday`, `year`, `month` und `day` alle `undefined` sind, werden `year`, `month` und `day` auf `"numeric"` gesetzt. In Implementierungen ohne `Intl.DateTimeFormat`-Unterstützung wird dieser Parameter ignoriert.

Rückgabewert

Typ

string

Beschreibung

Ein String, der den Datumsanteil des angegebenen Datums nach 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.

Beispiele

Verwendung von toLocaleDateString()

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 auf Unterstützung der Parameter locales und options

function toLocaleDateStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.DateTimeFormat === "function"
  );
}

Verwendung von locales

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

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"

// Wichtig · Fallstricke

In den meisten Fällen ist die von toLocaleDateString() zurückgegebene Formatierung konsistent. Die Ausgabe kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Locale — Abweichungen sind beabsichtigt und von der Spezifikation erlaubt. Sie entspricht möglicherweise auch nicht Ihren Erwartungen. Zum Beispiel kann der String geschützte Leerzeichen (non-breaking spaces) enthalten oder von bidirektionalen Steuerzeichen umgeben sein. Sie sollten die Ergebnisse von toLocaleDateString() nicht mit fest kodierten Konstanten vergleichen.

Siehe auch

Intl.DateTimeFormat Date.prototype.toLocaleString() Date.prototype.toLocaleTimeString() Date.prototype.toString() Date.prototype.toDateString()