JavaScript метод Number.toLocaleString()

Определение и применение

JavaScript метод toLocaleString() преобразует числовое значение (объект Number) в строковое и возвращает это значение, используя текущий или указанный языковой стандарт.

Поддержка браузерами

Метод toLocaleString()	Chrome	Firefox	Opera	Safari	IExplorer	Edge
Базовая поддержка	Да	Да	Да	Да	Да	Да
Параметр locales	24.0	29.0	15.0	10.0	11.0	Да
Параметр options	24.0	29.0	15.0	10.0	11.0	Да

JavaScript синтаксис:

// используя текущий языковой стандарт
num.toLocaleString();

// используя указанный языковой стандарт
num.toLocaleString( locales );

// используя указанный языковой стандарт с дополнительными настройками
num.toLocaleString( locales, options );

Версия JavaScript

1.1

Значения параметров

Параметр	Описание
locales	Параметр должен быть строкой, содержащей языковой тег BCP 47, или массивом таких языковых тегов. Если параметр не указан или не определен, используется языковой стандарт среды выполнения JavaScript по умолчанию. При указании нескольких строк языкового стандарта следует перечислять их в порядке убывания приоритета, чтобы первая запись была предпочитаемым языковым стандартом. Необязательный параметр. Языковой тег BCP 47 определяет язык и минимально содержит код основного языка. В своем наиболее распространенном виде он может содержать по порядку: код языка, код скрипта и код страны или региона, разделенные дефисами. Хотя тег не чувствителен к регистру, рекомендуется использовать заглавные буквы для кода скрипта, верхний регистр для кода страны и региона, а строчный регистр для всего остального.
options	Необязательный параметр, который содержит объект со свойствами, определяющими параметры сравнения: localeMatcher - используемый алгоритм сопоставления. Возможные значения "lookup" (следует алгоритму поиска, указанному в BCP 47) и "best fit" ( позволяет среде выполнения предоставить языковой стандарт, который, возможно, больше подходит для запроса, чем результат алгоритма "lookup"). Значение по умолчанию "best fit". style - используемый стиль форматирования. Возможные значения: "decimal" для простого форматирования числа, "currency" для форматирования денежных единиц и "percent" для форматирования процентов. Значение по умолчанию "decimal". currency - денежная единица, используемая в форматировании. Возможными значениями являются коды валют ISO 4217, например, такие как "USD" для доллара США, или "EUR" для евро. Полный перечень кодов ISO 4217 доступен по ссылке. Значение по умолчанию для свойства отсутствует. currencyDisplay - определяет как отображать денежные единицы (в символьном, числовом или строковом виде). Возможными значениями являются "symbol", чтобы использовать символ валюты, например €, значение "code" определяет, что будет использован код валюты по стандарту ISO, а значение "name", что будет использовано название валюты, например "dollar". Значение по умолчанию "symbol".. useGrouping - логическое значение, которое определяет следует ли использовать разделители групп чисел. Значение по умолчанию true. Следующие свойства можно разделить на две группы: свойства minimumIntegerDigits, minimumFractionDigits и maximumFractionDigits в одной группе, minimumSignificantDigits и maximumSignificantDigits в другой группе. Если определено хотя бы одно свойство из второй группы, то первая группа игнорируется. minimumIntegerDigits - определяет минимальное количество целых цифр для использования. Возможные значения от 1 до 21. Значение по умолчанию 1. minimumFractionDigits - определяет минимальное количество цифр дроби для использования. Возможные значения: от 0 до 20. Значение по умолчанию для простого числа и процентного форматирования равно 0, для форматирования денежных единиц это количество второстепенных цифр в единицах измерения, указанное в списке кодов валют ISO 4217 (2, если список не содержит этой информации). maximumFractionDigits - определяет максимальное число используемых цифр дроби. Возможные значения от 0 до 20. Значение по умолчанию для обычного форматирования чисел больше minimumFractionDigits и 3, для форматирования денежных единиц это значение больше minimumFractionDigits и количества второстепенных цифр, предусмотренных в списке кодов валют ISO 4217 (2, если список не дает такой информации). Значение по умолчанию для форматирования процентов больше minimumFractionDigits и 0. minimumSignificantDigits - определяет минимальное количество значащих цифр для использования. Возможные значения от 1 до 21. Значение по умолчанию 1. maximumSignificantDigits - определяет максимальное количество значащих цифр для использования. Возможные значения от 1 до 21. Значение по умолчанию соответствует значению свойства minimumSignificantDigits.

Параметр

Описание

locales

Параметр должен быть строкой, содержащей языковой тег BCP 47, или массивом таких языковых тегов. Если параметр не указан или не определен, используется языковой стандарт среды выполнения JavaScript по умолчанию. При указании нескольких строк языкового стандарта следует перечислять их в порядке убывания приоритета, чтобы первая запись была предпочитаемым языковым стандартом. Необязательный параметр.
Языковой тег BCP 47 определяет язык и минимально содержит код основного языка. В своем наиболее распространенном виде он может содержать по порядку: код языка, код скрипта и код страны или региона, разделенные дефисами. Хотя тег не чувствителен к регистру, рекомендуется использовать заглавные буквы для кода скрипта, верхний регистр для кода страны и региона, а строчный регистр для всего остального.

options

Необязательный параметр, который содержит объект со свойствами, определяющими параметры сравнения:

localeMatcher - используемый алгоритм сопоставления. Возможные значения "lookup" (следует алгоритму поиска, указанному в BCP 47) и "best fit" ( позволяет среде выполнения предоставить языковой стандарт, который, возможно, больше подходит для запроса, чем результат алгоритма "lookup"). Значение по умолчанию "best fit".
style - используемый стиль форматирования. Возможные значения: "decimal" для простого форматирования числа, "currency" для форматирования денежных единиц и "percent" для форматирования процентов. Значение по умолчанию "decimal".
currency - денежная единица, используемая в форматировании. Возможными значениями являются коды валют ISO 4217, например, такие как "USD" для доллара США, или "EUR" для евро. Полный перечень кодов ISO 4217 доступен по ссылке. Значение по умолчанию для свойства отсутствует.
currencyDisplay - определяет как отображать денежные единицы (в символьном, числовом или строковом виде). Возможными значениями являются "symbol", чтобы использовать символ валюты, например €, значение "code" определяет, что будет использован код валюты по стандарту ISO, а значение "name", что будет использовано название валюты, например "dollar". Значение по умолчанию "symbol"..
useGrouping - логическое значение, которое определяет следует ли использовать разделители групп чисел. Значение по умолчанию true.

Следующие свойства можно разделить на две группы: свойства minimumIntegerDigits, minimumFractionDigits и maximumFractionDigits в одной группе, minimumSignificantDigits и maximumSignificantDigits в другой группе. Если определено хотя бы одно свойство из второй группы, то первая группа игнорируется.

minimumIntegerDigits - определяет минимальное количество целых цифр для использования. Возможные значения от 1 до 21. Значение по умолчанию 1.
minimumFractionDigits - определяет минимальное количество цифр дроби для использования. Возможные значения: от 0 до 20. Значение по умолчанию для простого числа и процентного форматирования равно 0, для форматирования денежных единиц это количество второстепенных цифр в единицах измерения, указанное в списке кодов валют ISO 4217 (2, если список не содержит этой информации).
maximumFractionDigits - определяет максимальное число используемых цифр дроби. Возможные значения от 0 до 20. Значение по умолчанию для обычного форматирования чисел больше minimumFractionDigits и 3, для форматирования денежных единиц это значение больше minimumFractionDigits и количества второстепенных цифр, предусмотренных в списке кодов валют ISO 4217 (2, если список не дает такой информации). Значение по умолчанию для форматирования процентов больше minimumFractionDigits и 0.
minimumSignificantDigits - определяет минимальное количество значащих цифр для использования. Возможные значения от 1 до 21. Значение по умолчанию 1.
maximumSignificantDigits - определяет максимальное количество значащих цифр для использования. Возможные значения от 1 до 21. Значение по умолчанию соответствует значению свойства minimumSignificantDigits.

Пример использования

var num = 123456;                    // инициализируем числовую переменную
var options1 = { style: "percent" }; // определяем объект со свойствами, определяющими параметры сравнения
var options2 = { style: "currency",  // определяем объект со свойствами, определяющими параметры сравнения
		 currency: "EUR" }; 

num.toLocaleString( "de-DE" );                     // Возвращаемое значение "123.456" (German)
num.toLocaleString( "en-IN" );                     // Возвращаемое значение "1,23,456" (India)
num.toLocaleString( "zh-Hans-CN-u-nu-hanidec" );   // Возвращаемое значение "一二三,四五六" (Chinese)

num.toLocaleString( "en-US", options1);      // "12,345,600%"
num.toLocaleString( undefined, options1);    // "12 345 600 %" (текущий язык сценария)
num.toLocaleString( "en-US", options2);      // "€123,456.00"
num.toLocaleString( undefined, options2);    // "123 456,00 €" (текущий язык сценария)

JavaScript Number