BigInt.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 September 2017.
Die Methode toLocaleString()
von BigInt
-Werten gibt eine Zeichenkette mit einer sprachsensitiven Darstellung dieses BigInts zurück. In Implementierungen mit Unterstützung der Intl.NumberFormat
API delegiert diese Methode an Intl.NumberFormat
.
Jedes Mal, wenn toLocaleString
aufgerufen wird, muss eine Suche in einer großen Datenbank von Lokalisierungszeichenketten durchgeführt werden, was potenziell ineffizient ist. Wenn die Methode mit denselben Argumenten häufig aufgerufen wird, ist es besser, ein Intl.NumberFormat
-Objekt zu erstellen und dessen format()
-Methode zu verwenden, da ein NumberFormat
-Objekt die übergebenen Argumente speichert und möglicherweise einen Teil der Datenbank zwischenspeichert. Dadurch kann bei zukünftigen format
-Aufrufen in einem eingeschränkteren Kontext nach Lokalisierungszeichenketten gesucht werden.
Probieren Sie es aus
const bigint = 123456789123456789n;
// German uses period for thousands
console.log(bigint.toLocaleString("de-DE"));
// Expected output: "123.456.789.123.456.789"
// Request a currency format
console.log(
bigint.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// Expected output: "123.456.789.123.456.789,00 €"
Syntax
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
Parameter
Die Parameter locales
und options
passen das Verhalten der Funktion an und ermöglichen es Anwendungen, die Sprache zu spezifizieren, deren Formatierungsstandards verwendet werden sollen.
In Implementierungen, die die Intl.NumberFormat
API unterstützen, entsprechen diese Parameter genau den Parametern des Konstruktors Intl.NumberFormat()
. Implementierungen ohne Unterstützung für Intl.NumberFormat
ignorieren beide Parameter, was dazu führt, dass die verwendete Sprache und die Form der zurückgegebenen Zeichenkette vollständig von der Implementierung abhängen.
locales
Optional-
Ein String mit einem BCP 47-Sprachcode oder ein Array solcher Strings. Entspricht dem
locales
-Parameter desIntl.NumberFormat()
-Konstruktors.In Implementierungen ohne Unterstützung von
Intl.NumberFormat
wird dieser Parameter ignoriert und normalerweise die Locale des Hosts verwendet. options
Optional-
Ein Objekt zur Anpassung des Ausgabeformats. Entspricht dem
options
-Parameter desIntl.NumberFormat()
-Konstruktors.In Implementierungen ohne Unterstützung von
Intl.NumberFormat
wird dieser Parameter ignoriert.
Details zu diesen Parametern und deren Verwendung finden Sie im Konstruktor Intl.NumberFormat()
.
Rückgabewert
Eine Zeichenkette, die das gegebene BigInt gemäß sprachspezifischer Konventionen darstellt.
In Implementierungen mit Intl.NumberFormat
ist dies gleichbedeutend mit new Intl.NumberFormat(locales, options).format(number)
.
Hinweis:
Meistens ist die Formatierung, die von toLocaleString()
zurückgegeben wird, konsistent. Der Output kann jedoch zwischen Implementierungen variieren, selbst innerhalb derselben Locale – diese Variationen sind gewollt und von der Spezifikation erlaubt. Die Ausgabe entspricht möglicherweise auch nicht Ihren Erwartungen. Zum Beispiel kann die Zeichenkette geschützte Leerzeichen verwenden oder von Steuerzeichen für bidirektionalen Text umgeben sein. Sie sollten die Ergebnisse von toLocaleString()
nicht mit fest codierten Zeichenketten vergleichen.
Beispiele
Verwendung von toLocaleString()
Die grundlegende Verwendung dieser Methode ohne Angabe einer locale
gibt eine formatierte Zeichenkette in der Standard-Locale und mit den Standardoptionen zurück.
const bigint = 3500n;
console.log(bigint.toLocaleString());
// "3,500" if in U.S. English locale
Überprüfung der Unterstützung für die Parameter locales und options
Die Parameter locales
und options
werden möglicherweise nicht in allen Implementierungen unterstützt, da die Unterstützung der Internationalisierungs-API optional ist und einige Systeme nicht über die notwendigen Daten verfügen. In Implementierungen ohne Unterstützung der Internationalisierung verwendet toLocaleString()
stets die System-Locale, was möglicherweise nicht Ihren Anforderungen entspricht. Da jede Implementierung, die die Parameter locales
und options
unterstützt, auch die Intl
API unterstützen muss, können Sie deren Existenz überprüfen, um die Unterstützung sicherzustellen:
function toLocaleStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.NumberFormat === "function"
);
}
Verwendung von locales
Dieses Beispiel zeigt einige der Variationen in lokalisierten Zahlenformaten. Um sicherzustellen, dass das Format der Sprache entspricht, die in der Benutzeroberfläche Ihrer Anwendung verwendet wird, sollten Sie diese Sprache (und möglicherweise einige alternative Sprachen) mithilfe des Arguments locales
angeben:
const bigint = 123456789123456789n;
// German uses period for thousands
console.log(bigint.toLocaleString("de-DE"));
// 123.456.789.123.456.789
// Arabic in most Arabic speaking countries uses Eastern Arabic digits
console.log(bigint.toLocaleString("ar-EG"));
// ١٢٣٬٤٥٦٬٧٨٩٬١٢٣٬٤٥٦٬٧٨٩
// India uses thousands/lakh/crore separators
console.log(bigint.toLocaleString("en-IN"));
// 1,23,45,67,89,12,34,56,789
// the nu extension key requests a numbering system, e.g. Chinese decimal
console.log(bigint.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// 一二三,四五六,七八九,一二三,四五六,七八九
// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(bigint.toLocaleString(["ban", "id"]));
// 123.456.789.123.456.789
Verwendung von options
Die Ergebnisse, die von toLocaleString()
bereitgestellt werden, können mithilfe des Parameters options
angepasst werden:
const bigint = 123456789123456789n;
// request a currency format
console.log(
bigint.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// 123.456.789.123.456.789,00 €
// the Japanese yen doesn't use a minor unit
console.log(
bigint.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// ¥123,456,789,123,456,789
// limit to three significant digits
console.log(bigint.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// 1,23,00,00,00,00,00,00,000
Spezifikationen
Specification |
---|
ECMAScript® 2025 Internationalization API Specification # sup-bigint.prototype.tolocalestring |
Browser-Kompatibilität
Report problems with this compatibility data on GitHubdesktop | mobile | server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
toLocaleString | ||||||||||||||
locales parameter | ||||||||||||||
options parameter |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Has more compatibility info.