Array.prototype.toLocaleString()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Die toLocaleString() Methode von Array Instanzen gibt einen String zurück, der die Elemente des Arrays repräsentiert. Die Elemente werden durch ihre toLocaleString-Methoden in Strings umgewandelt, und diese Strings werden durch einen lokalisierungsabhängigen String (wie ein Komma ",") getrennt.

Probieren Sie es aus

const array = [1, "a", new Date("21 Dec 1997 14:12:00 UTC")];
const localeString = array.toLocaleString("en", { timeZone: "UTC" });

console.log(localeString);
// Expected output: "1,a,12/21/1997, 2:12:00 PM",
// This assumes "en" locale and UTC timezone - your results may vary

Syntax

toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)

Parameter

locales Optional: Ein String mit einem BCP 47-Sprach-Tag oder ein Array solcher Strings. Für die allgemeine Form und Interpretation des locales-Arguments, siehe die Parameterbeschreibung auf der Intl-Hauptseite.
options Optional: Ein Objekt mit Konfigurationseigenschaften. Was hier übergeben werden kann, hängt davon ab, welche Elemente konvertiert werden. Zum Beispiel für Zahlen, siehe Number.prototype.toLocaleString().

Rückgabewert

Ein String, der die Elemente des Arrays repräsentiert.

Beschreibung

Die Array.prototype.toLocaleString Methode durchläuft ihren Inhalt, ruft die toLocaleString Methode jedes Elements mit den angegebenen locales und options Parametern auf und verkettet sie mit einem implementationsdefinierten Trennzeichen (wie einem Komma ",").

Hinweis: Die locales oder options Argumente kontrollieren nicht den verwendeten Trennzeichen zwischen Array-Elementen; sie werden einfach an die toLocaleString() Methode jedes Elements weitergegeben. Das tatsächliche Trennzeichen (normalerweise ein Komma) hängt ausschließlich von der aktuellen Locale der Host-Umgebung ab. Wenn Sie eine lokalisierte Listenformatierung erwarten, sollten Sie stattdessen Intl.ListFormat verwenden.

Wenn ein Element undefined, null ist, wird es in einen leeren String anstelle des Strings "null" oder "undefined" umgewandelt.

Beim Verwenden auf spärlichen Arrays durchläuft die toLocaleString() Methode leere Slots, als ob sie den Wert undefined hätten.

Die toLocaleString() Methode ist generisch. Sie erwartet nur, dass der this Wert eine length Eigenschaft und integer-beschriftete Eigenschaften besitzt.

Beispiele

Verwendung von locales und options

Die Elemente des Arrays werden durch ihre toLocaleString-Methoden in Strings umgewandelt. Zum Beispiel ruft dieses Snippet implizit die Number.prototype.toLocaleString() Methode auf, um die Währung für die Strings und Zahlen im prices Array anzuzeigen:

const prices = ["￥7", 500, 8123, 12];
prices.toLocaleString("ja-JP", { style: "currency", currency: "JPY" });

// "￥7,￥500,￥8,123,￥12"

Listentrennzeichen

Das Listentrennzeichen wird nicht durch den locales Parameter beeinflusst. Um es zu konfigurieren, verwenden Sie stattdessen Intl.ListFormat.

const nums = [8888, 9999];
console.log(nums.toLocaleString("zh")); // "8,888,9,999"

const formatter = new Intl.ListFormat("zh", {
  type: "conjunction",
  style: "narrow",
});
console.log(formatter.format(nums.map((x) => x.toLocaleString("zh"))));
// "8,888、9,999"

Verwendung von toLocaleString() auf spärlichen Arrays

toLocaleString() behandelt leere Slots wie undefined und erzeugt ein zusätzliches Trennzeichen:

console.log([1, , 3].toLocaleString()); // '1,,3'

Aufrufen von toLocaleString() auf Nicht-Array-Objekten

Die toLocaleString() Methode liest die length Eigenschaft von this und greift dann auf jede Eigenschaft zu, deren Schlüssel eine nicht-negative ganze Zahl kleiner als length ist.

const arrayLike = {
  length: 3,
  0: 1,
  1: 2,
  2: 3,
  3: 4, // ignored by toLocaleString() since length is 3
};
console.log(Array.prototype.toLocaleString.call(arrayLike));
// 1,2,3

Spezifikationen

Specification
ECMAScript® 2026 Language Specification # sec-array.prototype.tolocalestring
ECMAScript® 2026 Internationalization API Specification # sup-array.prototype.tolocalestring