Number.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 июль 2015 г..
Метод toLocaleString() значений Number возвращает строку с языкозависимым представлением этого числа. В реализациях с поддержкой Intl.NumberFormat API этот метод просто вызывает Intl.NumberFormat.
При каждом вызове toLocaleString происходит поиск по большой базе локализованных строк, что может быть неэффективным. Когда метод вызывается много раз с одинаковыми параметрами, лучше создать объект Intl.NumberFormat и использовать его метод format(), потому что объект NumberFormat запоминает переданные ему параметры и может кешировать данные, чтобы последующие вызовы format могли выполнять поиск с более определённым контекстом.
Интерактивный пример
function eArabic(x) {
return x.toLocaleString("ar-EG");
}
console.log(eArabic(123456.789));
// Expected output: "١٢٣٬٤٥٦٫٧٨٩"
console.log(eArabic("123456.789"));
// Expected output: "123456.789"
console.log(eArabic(NaN));
// Expected output: "ليس رقم"
Синтаксис
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
Параметры
Параметры locales и options изменяют поведение функции и позволяют приложениям определять язык, правила форматирования которого, следует использовать.
В реализациях, поддерживающих Intl.NumberFormat API, эти параметры соответствуют параметрам конструктора Intl.NumberFormat(). Реализации без поддержки Intl.NumberFormat должны игнорировать оба параметра, используя локаль и формат возвращаемой строки определяемые самой реализацией.
localesНеобязательный-
Строка с языковым тегом BCP 47 или массив таких строк. Соответствует параметру
localesконструктора `Intl.NumberFormat().В реализациях без поддержки
Intl.NumberFormatэтот параметр игнорируется и обычно используется локаль устройства. optionsНеобязательный-
Объект определяющий выходной формат. Соответствует параметру
optionsконструктораIntl.NumberFormat().В реализациях без поддержки
Intl.NumberFormatэтот параметр игнорируется.
Смотрите описание конструктора Intl.NumberFormat() для подробностей использования этих параметров.
Возвращаемое значение
Строка, представляющая указанное число в соответствии с языковыми требованиями.
В реализациях с поддержкой Intl.NumberFormat результат будет эквивалентным new Intl.NumberFormat(locales, options).format(number).
Примечание:
В большинстве случаев форматирование, возвращаемое toLocaleString(), единообразно. Однако результат может быть разным в зависимости от времени, языка и реализации — это допускается спецификацией. Не следует сравнивать результат toLocaleString() со статическими значениями.
Примеры
Использование toLocaleString()
При использовании без указания локали возвращается строка, отформатированная в соответствии с локалью и настройками по умолчанию.
var number = 3500;
console.log(number.toLocaleString()); // Отобразит '3,500' в локали U.S. English
Проверка поддержки параметров locales и options
Параметры locales и options могут поддерживаться не во всех реализациях. В реализациях без поддержки интернационализации toLocaleString() всегда использует системную локаль, что может оказаться не тем, что вам нужно. Поскольку любая реализация, поддерживающая параметры locales и options, должна поддерживать Intl API, проверить наличие последней можно таким способом:
function toLocaleStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.DateTimeFormat === "function"
);
}
Использование параметра locales
Этот пример показывает некоторые локализованные форматы чисел. Для получения формата языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, несколько запасных языков) используя параметр locales:
var number = 123456.789;
// В Германии в качестве разделителя целой и дробной части используется запятая, а в качестве разделителя разрядов точка
console.log(number.toLocaleString("de-DE"));
// 123.456,789
// В России в качестве разделителя целой и дробной части используется запятая, а в качестве разделителя разрядов пробел
console.log(number.toLocaleString("ru-RU"));
// 123 456,789
// В большинстве арабоязычных стран используют настоящие арабские цифры
console.log(number.toLocaleString("ar-EG"));
// ١٢٣٤٥٦٫٧٨٩
// В Индии используют разделители для тысяч/лакх/крор
console.log(number.toLocaleString("en-IN"));
// 1,23,456.789
// Ключ расширения nu запрашивает систему нумерации, например, китайскую десятичную
console.log(number.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// 一二三,四五六.七八九
// Если запрашиваемый язык может не поддерживаться, например
// балийский, откатываемся на запасной язык, в данном случае индонезийский
console.log(number.toLocaleString(["ban", "id"]));
// 123.456,789
Использование параметра options
Результат, предоставляемый методом toLocaleString(), может быть настроен с помощью параметра options:
var number = 123456.789;
// Запрашиваем формат валюты
console.log(
number.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// 123.456,79 €
console.log(
number.toLocaleString("ru-RU", { style: "currency", currency: "RUB" }),
);
// 123 456,79 ₽
// Японская йена не использует младшие единицы
console.log(
number.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// ￥123,457
// Ограничиваем до трёх значащих цифр
console.log(number.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// 1,23,000
// Используем язык системы по умолчанию дял форматирования чисел
const num = 30000.65;
console.log(
num.toLocaleString(undefined, {
minimumFractionDigits: 2,
maximumFractionDigits: 2,
}),
);
// "30,000.65" если язык по умолчанию английский или
// "30.000,65" если язык по умолчанию немецкий или
// "30 000,65" если язык по умолчанию французский
Спецификации
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-number.prototype.tolocalestring |
| ECMAScript® 2026 Internationalization API Specification # sup-number.prototype.tolocalestring |
Совместимость с браузерами
Loading…