Array.prototype.toLocaleString() — Methode · JavaScript-Referenz

Signatur

Array.prototype.toLocaleString(locales, options)

Beschreibung

toLocaleString() ruft für jedes Element des Arrays dessen eigene Methode toLocaleString(locales, options) auf und verbindet die Ergebnisse zu einem einzigen String. Zahlen erhalten dabei zum Beispiel Tausender- und Dezimaltrennzeichen, die zur Sprache passen, und Date-Objekte ein Datumsformat, das zur Region passt. Die Argumente locales und options werden unverändert an jedes Element weitergegeben.

Die Methode eignet sich für schnelle, lesbare Ausgaben, etwa in Logs, Tooltips oder einfachen Anzeigen von Zahlen- oder Datumslisten. Im Unterschied zu toString() bzw. join() wird nicht String(element) verwendet, sondern die sprachabhängige Formatierung des jeweiligen Elements.

Elemente mit dem Wert null oder undefined sowie Lücken in dünn besetzten Arrays erscheinen als leere Strings. Welches Trennzeichen zwischen den Elementen steht, legt die Implementierung fest. In allen gängigen Engines ist es ein Komma , ohne Leerzeichen, und zwar unabhängig von der gewählten Locale. Die Methode ist generisch: Sie funktioniert auch mit Array-ähnlichen Objekten, die eine Eigenschaft length und Eigenschaften mit Indizes als Schlüssel haben.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| undefined	undefined (Standard-Locale der Umgebung)	Ein BCP-47-Sprach-Tag wie `'de-DE'` oder eine Liste solcher Tags. Wird an die `toLocaleString()`-Methode jedes Elements weitergereicht.
$options	object \| undefined	undefined	Optionen für die Formatierung, z. B. `{ style: 'currency', currency: 'EUR' }` für Zahlen (siehe `Intl.NumberFormat`) oder `{ dateStyle: 'short' }` für Datumswerte (siehe `Intl.DateTimeFormat`). Das gleiche Objekt geht an jedes Element.

Rückgabewert

Typ

string

Beschreibung

Ein String mit den formatierten Elementen, getrennt durch das Listentrennzeichen der Implementierung (in der Praxis ,). Bei einem leeren Array ist das Ergebnis ein leerer String ''.

Beispiele

Preise als Währung formatieren

const preise = [7, 500, 8123.5, 12];

const ausgabe = preise.toLocaleString('de-DE', {
  style: 'currency',
  currency: 'EUR'
});

console.log(ausgabe);

7,00 €,500,00 €,8.123,50 €,12,00 €

Zahlen und Datum gemischt (mehrdeutige Kommas)

const werte = [1234.5, new Date(Date.UTC(2024, 0, 15))];

console.log(werte.toLocaleString('en-US', { timeZone: 'UTC' }));
console.log(werte.toLocaleString('de-DE', { timeZone: 'UTC' }));

1,234.5,1/15/2024, 12:00:00 AM 1.234,5,15.1.2024, 00:00:00

Lesbare Liste mit eigenem Trennzeichen erzeugen

const messwerte = [0.25, 1500, null, 3.14159];

// toLocaleString: festes Komma, null wird zum leeren String
console.log(messwerte.toLocaleString('de-DE'));

// Besser für die Anzeige: map + join mit eigenem Trennzeichen
const lesbar = messwerte
  .filter((n) => n != null)
  .map((n) => n.toLocaleString('de-DE', { maximumFractionDigits: 2 }))
  .join('; ');

console.log(lesbar);

0,25,1.500,,3,142 0,25; 1.500; 3,14

Generisch auf Array-ähnlichen Objekten

const arrayAehnlich = { length: 3, 0: 1000, 1: 2500.75, 2: undefined };

const text = Array.prototype.toLocaleString.call(arrayAehnlich, 'de-DE');
console.log(JSON.stringify(text));

"1.000,2.500,75,"

// Wichtig · Fallstricke

Mehrdeutiges Trennzeichen: Das Komma zwischen den Elementen passt sich nicht an die Locale an. In Sprachen, die das Komma als Dezimaltrennzeichen verwenden (z. B. de-DE), lässt sich die Ausgabe deshalb nicht eindeutig lesen und auch nicht zuverlässig wieder in ein Array zerlegen. Für die Anzeige besser map() mit join('; ') oder Intl.ListFormat verwenden.
null, undefined und Lücken werden zu leeren Strings, zum Beispiel ergibt [1, null, , 2].toLocaleString() den String "1,,,2".
Die Argumente locales und options gelten für alle Elemente. Bei gemischten Typen werden Optionen, die ein Typ nicht kennt, meist ignoriert. Ungültige Werte, etwa ein unbekannter Währungscode, lösen dagegen einen RangeError aus.
Ein Element ohne toLocaleString(), z. B. ein Objekt aus Object.create(null), führt zu einem TypeError.
Ältere Engines ohne volle ECMA-402-Unterstützung ignorieren locales/options unter Umständen. Alle aktuellen Browser und Node.js (mit vollständigem ICU, Standard seit Node 13) unterstützen sie.
Bei großen Arrays mit vielen Zahlen ist Intl.NumberFormat schneller: Eine einzige Instanz erstellen und mit arr.map(nf.format).join(', ') verwenden, damit nicht für jedes Element ein neuer Formatierer entsteht.

Siehe auch

Array.prototype.toString() Array.prototype.join() Number.prototype.toLocaleString() Date.prototype.toLocaleString() Intl.NumberFormat Intl.ListFormat