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

Signatur

TypedArray.prototype.toLocaleString(locales, options)

Beschreibung

toLocaleString() wandelt jedes Element eines typisierten Arrays (z. B. Uint8Array, Float64Array, BigInt64Array) mit dessen eigener toLocaleString()-Methode in einen String um. Bei Zahlen ist das Number.prototype.toLocaleString(), bei BigInt-Arrays BigInt.prototype.toLocaleString(). Die Teilstrings werden anschließend zu einem einzigen String verbunden.

Die Argumente locales und options werden unverändert an die Formatierung jedes Elements weitergereicht. Damit lassen sich Tausendertrennzeichen, Dezimalzeichen, Währungen, Prozentangaben oder Einheiten gemäß Intl.NumberFormat steuern.

Der Algorithmus entspricht dem von Array.prototype.toLocaleString(). Das Trennzeichen zwischen den Elementen hängt nicht von der Locale ab und ist in allen gängigen Engines ein Komma ,. Für Anzeigezwecke in deutschsprachigen Oberflächen ist das oft ungeeignet, weil das Komma dort auch als Dezimalzeichen dient.

Die Methode eignet sich für schnelle Debug-Ausgaben oder einfache Anzeigen. Für gut lesbare Listen ist es meist besser, die Elemente mit Intl.NumberFormat einzeln zu formatieren und mit Intl.ListFormat oder einem eigenen Trennzeichen zu verbinden.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| undefined	Standard-Locale der Laufzeitumgebung	BCP-47-Sprachcode (z. B. `'de-DE'`) oder eine Liste davon. Wird an `Number.prototype.toLocaleString()` bzw. `BigInt.prototype.toLocaleString()` weitergereicht.
$options	Intl.NumberFormatOptions \| undefined	{}	Formatierungsoptionen wie bei `Intl.NumberFormat`, z. B. `style`, `currency`, `unit`, `minimumFractionDigits`, `maximumFractionDigits`.

Rückgabewert

Typ

string

Beschreibung

Ein String mit den nach Locale formatierten Elementen, getrennt durch Kommas. Bei einem leeren typisierten Array wird "" zurückgegeben.

Beispiele

Grundlegende Formatierung in verschiedenen Locales

const werte = new Uint32Array([1234, 5678, 90000]);

console.log(werte.toLocaleString('en-US'));
console.log(werte.toLocaleString('de-DE'));
// Zum Vergleich: toString() formatiert nicht
console.log(werte.toString());

1,234,5,678,90,000 1.234,5.678,90.000 1234,5678,90000

Währungsformat für Messwerte aus einem Float64Array

const preise = new Float64Array([1234.5, 99.99, 0.5]);

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

1.234,50 €,99,99 €,0,50 €

BigInt64Array formatieren

const zaehler = new BigInt64Array([1234567890123n, -42n]);

console.log(zaehler.toLocaleString('de-DE'));

1.234.567.890.123,-42

Lesbare Liste mit eigenem Trennzeichen (empfohlen für UIs)

const temperaturen = new Float32Array([21.5, 19.25, 23]);

const fmt = new Intl.NumberFormat('de-DE', {
  style: 'unit',
  unit: 'celsius',
  maximumFractionDigits: 1,
});

// Elemente einzeln formatieren und mit Intl.ListFormat verbinden
const teile = Array.from(temperaturen, (t) => fmt.format(t));
const liste = new Intl.ListFormat('de-DE', { type: 'conjunction' }).format(teile);
console.log(liste);

21,5 °C, 19,3 °C und 23 °C

// Wichtig · Fallstricke

Trennzeichen immer Komma: Die Elemente werden unabhängig von der Locale mit , verbunden. Mit 'de-DE' ergibt sich deshalb z. B. "1,5,2,5" für [1.5, 2.5], was sich nicht eindeutig lesen lässt. Für Anzeigen die Elemente lieber einzeln formatieren (siehe letztes Beispiel).
Rundung: Ohne Optionen formatiert Intl.NumberFormat mit höchstens 3 Nachkommastellen. new Float64Array([1.23456]).toLocaleString('en-US') liefert "1.235". Das kaschiert auch Ungenauigkeiten von Float32Array, bei denen toString() z. B. 0.10000000149011612 anzeigen würde.
Uneinheitliche Ausgaben: Ohne locales hängt das Ergebnis von der Umgebung ab (Browser-Sprache, Node.js-ICU-Build). Für reproduzierbare Ausgaben, z. B. in Tests, immer eine Locale angeben. Die Leerzeichen vor Währungssymbolen und Einheiten sind oft geschützte Leerzeichen (U+00A0).
Performance: Bei großen Arrays wird für jedes Element eine eigene Formatierung aufgerufen. Das ist langsam. Besser ist es, eine Intl.NumberFormat-Instanz einmal zu erzeugen und wiederzuverwenden.
Auf einem typisierten Array mit abgetrenntem (detached) ArrayBuffer wird ein TypeError ausgelöst. Die Methode wird in allen modernen Browsern und in Node.js unterstützt.

Siehe auch

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