Сводка
Метод toLocaleString() возвращает строку с языко-зависимым представлением числа.
Новые аргументы locales и options позволяют приложениям определять язык, чьё поведение и соглашения по форматированию которого оно хочет использовать. В старых реализациях, игнорирующих аргументы locales и options, используемая локаль и форма возвращённой строки целиком зависит от реализации.
Синтаксис
numObj.toLocaleString([locales[, options]])Параметры
Проверьте раздел Совместимость с браузерами, чтобы увидеть, какие браузеры поддерживают аргументы locales и options, и Пример: проверка поддержки аргументов locales и options для определения этой возможности.
Обратите внимание: API интернационализации ECMAScript, реализованное в Firefox 29, добавляет аргумент locales к методу Number.toLocaleString(). Если этот аргумент равен undefined, этот метод возвращает локализованные цифры на языке, определяемом ОС, в то время, как предыдущие версии Firefox возвращали цифры на английском языке. Это изменение было помечено, как регрессия, затрагивающая обратную совместимость, которая скоро может быть исправлена. (ошибка 999003)
locales-
Необязательный параметр. Строка с языковой меткой BCP 47, либо массив таких строк. Описание общей формы и интерпретации аргумента
localesсмотрите на странице, посвящённой объекту Intl. Разрешены следующие ключи расширения Unicode:nu- Используемая система нумерации. Возможные значения включают в себя:
"arab","arabext","bali","beng","deva","fullwide","gujr","guru","hanidec","khmr","knda","laoo","latn","limb","mlym","mong","mymr","orya","tamldec","telu","thai","tibt".
options-
Необязательный параметр. Объект с некоторыми или всеми из следующих свойств:
localeMatcher- Используемый алгоритм сопоставления локалей. Возможными значениями являются
"lookup"и"best fit"; значением по умолчанию является"best fit". Информацию по этой опции смотрите на странице, посвящённой объекту Intl. style- Используемый стиль форматирования. Возможными значениями являются
"decimal"для простого форматирования числа,"currency"для форматирования валюты и"percent"для форматирования процентов; значением по умолчанию является"decimal". currency- Валюта, используемая при форматировании валют. Возможными значениями являются коды валют ISO 4217, например,
"USD"для доллара США,"EUR"для евро или"CNY"для китайского юаня — смотрите список кодов текущих валют и денежных средств. Свойство не имеет значения по умолчанию; если свойствоstyleравно"currency", свойствоcurrencyтакже должно присутствовать. currencyDisplay- Определяет, как отображать валюту при форматировании валют. Возможными значениями являются
"symbol"для использования локализованного символа валюты, например € для евро,"code"для использования кода валюты ISO,"name"для использования локализованного названия валюты, например"доллар США"для доллара; значением по умолчанию является"symbol". useGrouping- Определяет, использовать ли разделители групп разрядов, например, разделители тысяч или тысяч/лакх/крор. Возможными значениями являются
trueиfalse; значением по умолчанию являетсяtrue.
Следующие свойства разбиваются на две группы:
minimumIntegerDigits,minimumFractionDigitsиmaximumFractionDigitsвходят в одну группу, аminimumSignificantDigitsиmaximumSignificantDigits— в другую. Если определено хотя бы одно свойство из второй группы, свойства из второй первой группы будут проигнорированы.minimumIntegerDigits- Минимальное используемое количество цифр целой части числа. Возможными значениями являются значения от 1 до 21; значением по умолчанию является 1.
minimumFractionDigits- Минимальное используемое количество цифр дробной части числа. Возможными значениями являются значения от 0 до 20; значением по умолчанию для простого и процентного форматирования является 0; значением по умолчанию для форматирования валюты является число цифр младших единиц, определяемое в списке кодов валют ISO 4217 (2, если данный список не предоставляет такой информации).
maximumFractionDigits- Максимальное используемое количество цифр дробной части числа. Возможными значениями являются значения от 0 до 20; значением по умолчанию для простого форматирования является наибольшее значение из
minimumFractionDigitsи 3; значением по умолчанию для форматирования валюты является число цифр младших единиц, определяемое в списке кодов валют ISO 4217 (2, если данный список не предоставляет такой информации); значением по умолчанию для процентного форматирования является наибольшее значение изminimumFractionDigitsи 0. minimumSignificantDigits- Минимальное используемое количество значащих цифр числа. Возможными значениями являются значения от 1 до 21; значением по умолчанию является 1.
maximumSignificantDigits- Максимальное используемое количество значащих цифр числа. Возможными значениями являются значения от 1 до 21; значением по умолчанию является
minimumSignificantDigits.
Примеры
Пример: использование toLocaleString
При базовом использовании без указания локали возвращается строка, отформатированная в соответствии с локалью и опциями по умолчанию.
var number = 3500; console.log(number.toLocaleString()); // Отобразит '3,500' в локали U.S. English
Пример: проверка поддержки аргументов locales и options
Аргументы locales и options поддерживаются ещё не всеми браузерами. Для проверки того, поддерживает ли их уже реализация, можно затребовать несуществующую метку языка и проверить, будет ли выброшено исключение RangeError:
function toLocaleStringSupportsLocales() {
var number = 0;
try {
number.toLocaleString('i');
} catch (e) {
return e.name === 'RangeError';
}
return false;
}
Пример: использование аргумента 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
Производительность
При форматировании большого количества чисел лучшим вариантом будет создание объекта NumberFormat и использование функции, предоставляемой его свойством NumberFormat.format.
Спецификации
| Спецификация | Статус | Комментарии |
|---|---|---|
| ECMAScript 3-е издание. | Стандарт | Изначальное определение. Реализована в JavaScript 1.5. |
| ECMAScript 5.1 (ECMA-262) Определение 'Number.prototype.toLocaleString' в этой спецификации. |
Стандарт | |
| ECMAScript 6 (ECMA-262) Определение 'Number.prototype.toLocaleString' в этой спецификации. |
Кандидат в рекомендации | |
| ECMAScript Internationalization API 1.0 (ECMA-402) Определение 'Number.prototype.toLocaleString' в этой спецификации. |
Стандарт |
Совместимость с браузерами
| Возможность | Chrome | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
|---|---|---|---|---|---|
| Базовая поддержка | (Да) | (Да) | (Да) | (Да) | (Да) |
Аргументы locales и options |
24 | 29 (29) | 11 | 15 | Нет |
| Возможность | Android | Chrome для Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
|---|---|---|---|---|---|---|
| Базовая поддержка | (Да) | (Да) | (Да) | (Да) | (Да) | (Да) |
Аргументы locales и options |
Нет | 26 |
Нет ошибка 864843 |
Нет | Нет | Нет |