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

Signatur

Object.prototype.toLocaleString()

Beschreibung

Object.prototype.toLocaleString() ist eine allgemeine Einstiegsstelle für eine an Sprache und Region angepasste Textdarstellung eines Objekts. Die Basisimplementierung auf Object.prototype macht nichts Sprachspezifisches. Sie ruft nur this.toString() auf und gibt dessen Ergebnis zurück. Bei einem gewöhnlichen Objekt kommt deshalb meist "[object Object]" heraus.

Die Methode ist dafür gedacht, von eingebauten oder eigenen Klassen überschrieben zu werden. Mehrere eingebaute Objekte tun das bereits: Number.prototype.toLocaleString(), Date.prototype.toLocaleString(), BigInt.prototype.toLocaleString(), Array.prototype.toLocaleString() sowie die toLocaleString()-Methoden der TypedArrays. Diese Varianten nehmen die Argumente locales und options entgegen und formatieren den Wert passend dazu, zum Beispiel mit Tausendertrennzeichen oder als Datum im Landesformat.

Ein praktischer Nutzen ist, dass Array.prototype.toLocaleString() für jedes Element dessen toLocaleString() aufruft. Wer die Methode in einer eigenen Klasse überschreibt, bestimmt damit auch, wie Instanzen in Listen dargestellt werden, die nach Sprache und Region formatiert sind.

Parameter

Name	Typ	Default	Beschreibung
$(keine)	—		Die Basisimplementierung nimmt keine Parameter entgegen. Überschreibungen wie `Number.prototype.toLocaleString(locales, options)` erwarten dagegen meist `locales` (`string \| string[]`) und `options` (`object`).

Rückgabewert

Typ

string

Beschreibung

Der Rückgabewert von this.toString(). Bei einfachen Objekten ist das normalerweise "[object Object]".

Beispiele

Standardverhalten bei einfachen Objekten

const user = { name: 'Anna', alter: 32 };

console.log(user.toLocaleString());
console.log(user.toLocaleString() === user.toString());

[object Object] true

Überschriebene Varianten bei Number und Date

const betrag = 1234567.891;
console.log(betrag.toLocaleString('de-DE'));
console.log(betrag.toLocaleString('en-US'));

const datum = new Date(Date.UTC(2024, 0, 15, 12, 0));
console.log(datum.toLocaleString('de-DE', { timeZone: 'UTC' }));

1.234.567,891 1,234,567.891 15.1.2024, 12:00:00

Eigene Klasse mit sprachabhängiger Ausgabe

class Preis {
  constructor(wert, waehrung = 'EUR') {
    this.wert = wert;
    this.waehrung = waehrung;
  }

  toLocaleString(locales, options = {}) {
    return this.wert.toLocaleString(locales, {
      style: 'currency',
      currency: this.waehrung,
      ...options,
    });
  }
}

const preise = [new Preis(19.99), new Preis(1250)];

// Array.prototype.toLocaleString ruft toLocaleString jedes Elements auf
console.log(preise.toLocaleString('de-DE'));

19,99 €,1.250,00 €

toString beeinflusst die Basisimplementierung

const punkt = {
  x: 3,
  y: 4,
  toString() {
    return `Punkt(${this.x}, ${this.y})`;
  },
};

// toLocaleString delegiert an das eigene toString
console.log(punkt.toLocaleString());

Punkt(3, 4)

// Wichtig · Fallstricke

Die Basisimplementierung ignoriert alle Argumente. ({}).toLocaleString('de-DE') formatiert also nichts. Sprachabhängige Formatierung gibt es nur bei Überschreibungen.
Objekte ohne Prototyp, etwa aus Object.create(null), haben keine toLocaleString()-Methode. Ein direkter Aufruf wirft dann einen TypeError. Als Ausweg lässt sich Object.prototype.toLocaleString.call(obj) verwenden. Das scheitert aber ebenfalls, wenn obj kein toString besitzt.
Die genaue Ausgabe der überschriebenen Varianten hängt von der Laufzeitumgebung und ihren ICU- bzw. Intl-Daten ab. Leerzeichen können zum Beispiel geschützte Leerzeichen (U+00A0 oder U+202F) sein. Tests mit starren String-Vergleichen gehen deshalb schnell kaputt.
Wer Werte oft formatiert, fährt mit einer wiederverwendeten Intl.NumberFormat- oder Intl.DateTimeFormat-Instanz schneller als mit wiederholten toLocaleString()-Aufrufen samt Optionen.
Die Methode gibt es in allen Browsern und in Node.js.

Siehe auch

Object.prototype.toString() Number.prototype.toLocaleString() Date.prototype.toLocaleString() Array.prototype.toLocaleString() Intl.NumberFormat Intl.DateTimeFormat