Сводка
Метод 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 |
Нет | Нет | Нет |