Благодаря конструктору Intl.NumberFormat нативный js позволяет создавать языко-зависимые пользовательские интерфейсы. Он способен представить любое число, например, денежные единицы, в нужном формате с учетом особенностей страны и языка.
Что может конструктор Intl.NumberFormat
Он создает объект с возможностью предоставления чисел в более понятном для пользователя той или иной страны формате. Вместо получения чисел, как они есть (например, 1234 или 4561254), их можно представить в виде 1,234 или $4,561.254.
Зачем это нужно? В разных странах используются различные способы отображения чисел. Например, в Испании число 123456 будет отображаться в виде 123.456, в Англии — 123,456, а в Индии — 1,23,456.
Раньше приходилось использовать, например такой вариант:
const money = 100;
let localMoney = money.toLocaleString('en-US', {
style: 'currency',
currency: 'USD'
}
);
console.log(localMoney); // Получим $100.00 в формате строкиСинтаксис, параметры и настройки Intl.NumberFormat
Объект может принимать два параметра.
const formatterObject = new Intl.NumberFormat([locales[, options]]);
FormatterObject является объектом, созданным конструктором Intl.NumberFormat. Он содержит методы, доступные для форматирования чисел. Locales представляет собой код языка и страны, для которой будет осуществляться форматирование числа.
const num = 1234567890.1234;
// Задаем форматирование
const hindiNumberFormatter = new Intl.NumberFormat('en-IN');
const britishNumberFormatter = new Intl.NumberFormat('en-GB');
const spanishNumberFormatter = new Intl.NumberFormat('es-ES');
// Получаем отформатированные числа для каждой страны и языка
console.log(hindiNumberFormatter.format(num)); // 1,23,45,67,890.123
console.log(britishNumberFormatter.format(num)); // 1,234,567,890.123
console.log(spanishNumberFormatter.format(num)); // 1.234.567.890,123Locales
Locales — настройки языка и региона (представляет собой строковый тип данных с языковым тегом BCP 47, состоящий из кода языка и страны). Допускается следующий ключ расширения Unicode:
- nu: используемая система нумерации (возможные значения включают, в том числе ‘adlm’, ‘ahom’, ‘arab’, ‘arabext’, ‘bali’, ‘beng’ и другие.
Например:
'en-CA' // en = English (язык) // CA = Canada (страна) 'en-IN' // английский, Индия 'fr-CA' // Французская, Канада 'ja-JP' // японский, Япония
Эти данные можно найти в списках кодов языков и валют.
Options
Он заключен в квадратные скобки, так как является необязательным.
Может включать некоторые или все доступные свойства:
- compactDisplay: используется только вместе со свойством compact (принимает значение ‘short’ (по умолчанию) или ‘long’);
- currency: валюта, используемая при форматировании денежных единиц; не имеет значения по умолчанию, поэтому при использовании этого свойства указание типа валюты является обязательным (возможные значения — коды валют ISO 4217);
- currencyDisplay: способ отображения формата валюты; может принимать следующие значения (‘symbol’ — символ валюты, например, € (евро), которое установлено по умолчанию; ‘narrowSymbol’ — устанавливает разный формат обозначения валюты ($100 или US$100); ‘code’ — позволяет задать кода валюты согласно стандарту ISO 4217; ‘name’ — для указания названия валюты, например, «доллар»).
- localeMatcher: используемый алгоритм выбора языкового стандарта (возможные значения: ‘lookup’ и ‘best fit’ (стоит по дефолту); в случае отсутствия аргумента options для всех свойств используются значения по умолчанию;
- notation: форматирование числа, по умолчанию стоит ‘standard’ (также доступны значения ‘scientific’ (порядок величины), ‘engineering’ (возвращает экспоненту при делении числа на три), ‘compact’ (возвращает экспоненту, по умолчанию используется «короткая» форма — ‘short’);
- numberingSystem: система нумерации (возможные значения включают ‘adlm’, ‘ahom’, ‘arab’, ‘arabext’, ‘bali’, ‘beng’ и другие);
- signDisplay: позволяет установить, когда необходимо отображать знак числа (по умолчанию принимает значение ‘auto’); другие значения включают ‘never’ (запрет на отображение символа), ‘always’ (всегда отображать) и ‘exceptZero’ (для положительных и отрицательных чисел, но не для нуля);
- style: стиль форматирования (по умолчанию ‘decimal’); также доступны — ‘currency’ (для валюты), ‘percent’ (для процентов), ‘unit’ (для различных единиц измерений);
- unit: позволяет установить тип форматирования единиц измерения (не имеет значения по умолчанию); возможные значения — идентификаторы основных единиц, определенные в стандарте UTS #35; пары простых единиц могут быть объединены с помощью ‘-per-’ для отображений составных единиц измерений (при указании свойства style: ‘unit’ необходимо указывать значение ‘unit’);
- unitDisplay: стиль форматирования единиц измерения, используемый; доступны значения ‘long’ (например, 16 литров), ‘short’ (например, 16 л, установлено по умолчанию) и ‘narrow’ (например, 16 л);
- useGrouping: позволяет указать, следует ли использовать разделители групп цифр (сотен, тысяч и т.д.); возможные значения true (по умолчанию) или false;
- minimumIntegerDigits: минимальное количество целых цифр (доступные значения от 1 (по умолчанию) до 21;
- minimumFractionDigits: минимальное количество цифр дробной части (возможные значения от 0 (по умолчанию для простых чисел и процентов) до 20; для валют используется количество цифр после запятой или точки, указанное в списке кодов валют ISO 4217;
- maximumFractionDigits: максимальное количество цифр дробной части (возможные значения от 0 (по умолчанию для простых чисел и процентов) до 20; значение по умолчанию для простых чисел равно значению minimumFractionDigits, но не менее трех, а для валют — не меньше значения minimumFractionDigits с учетом стандартов ISO 4217, для процентов — больше 0, но не меньше значения minimumFractionDigits;
- minimumSignificantDigits: минимальное количество используемых значимых (важных) цифр (возможные значения от 1 (по умолчанию) до 21;
- maximumSignificantDigits: максимальное количество значимых (важных) цифр (возможные значения от 1 (по умолчанию) до 21.
Следующие свойства делятся на две группы: minimumIntegerDigits, minimumFractionDigits и maximumFractionDigits в одной группе, minimumSignificantDigits и maximumSignificantDigits в другой. Если определено хотя бы одно свойство из второй группы, то первая группа игнорируется.
Style — стиль форматирования чисел(может принимать три значения для форматирования валюты):
- decimal: форматирование простых чисел, установлен по умолчанию;
- currency: формат используемой валюты;
- percent: форматирование процентов,
- maximumSignificantDigits: максимальное количество цифр после запятой;
- minimumFractionDigits: минимальное количество цифр после запятой.
Currency — используемая валюта.
С полным списком кодов мировых валют можно ознакомиться тут.
const num = 1234567890.1234;
// Задаем параметры
const formatConfig = {
style: 'currency',
currency: 'USD',
minimumFractionDigits: 2,
currencyDisplay: 'symbol',
};
// Устанавливаем тип форматирования для конкретной страны и языка
const britishNumberFormatter = new Intl.NumberFormat('en-GB', formatConfig);
const spanishNumberFormatter = new Intl.NumberFormat('es-ES', formatConfig);
// Выводим результат в консоль
console.log(britishNumberFormatter.format(num)); // US$1,234,567,890.12
console.log(spanishNumberFormatter.format(num)); // 1.234.567.890,12 US$Помимо метода format в formatterObject доступен и другой метод, formatToParts. Он возвращает массив объектов, представляющих числовую строку в частях, которые могут быть использованы для пользовательского форматирования с учетом текущих данных locales.
const num = 1234.5678;
const britishNumberFormatter = new Intl.NumberFormat('en-GB');
const spanishNumberFormatter = new Intl.NumberFormat('es-ES');
console.log(britishNumberFormatter.formatToParts(num));
/* Получаем в консоль
[
0: Object { type: "integer", value: "1" }
1: Object { type: "group", value: "," }
2: Object { type: "integer", value: "234" }
3: Object { type: "decimal", value: "." }
4: Object { type: "fraction", value: "568" }
]
*/
console.log(spanishNumberFormatter.formatToParts(num)); // 1.234.567.890,123
/*Получаем в консоль
[
0: Object { type: "integer", value: "1234" }
1: Object { type: "decimal", value: "," }
2: Object { type: "fraction", value: "568" }
] */FormatToParts разбивает отформатированное число на части и определяет его тип (целое или дробное) и тип конкретного символа (группа цифр или десятичная дробь).
Форматирование других единиц измерений
Intl.NumberFormat может использоваться для форматирования и единиц измерения (л, км/ч и т.д.), в том числе с поддержкой типа данных bigint.
const num = 1235.12;
const formatConfig = {
style: 'unit',
unit: 'kilometer-per-hour',
};
// Устанавливаем тип форматирования для конкретной страны и языка
const britishNumberFormatter = new Intl.NumberFormat('ru', formatConfig);
console.log(britishNumberFormatter.format(num)); // Получаем в консоль 1 235,12 км/чКроссбраузерность Intl.NumberFormat
Но эти возможности пока поддерживают не все браузеры, в том числе некоторые встроенные в конструктор Intl API опции и параметры. Поэтому без полифила не обойтись.
