Number.prototype.toLocaleString()

Сводка

Метод 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
Нет Нет Нет

Смотрите также

Метки документа и участники

 Внесли вклад в эту страницу: Mingun
 Обновлялась последний раз: Mingun,