GT ClassMethodsFormatting

formatNum

Справочник API по методу formatNum для форматирования чисел по правилам локали

Обзор

Метод formatNum форматирует числа в соответствии с локаль‑специфическими правилами с помощью Internationalization API. Он автоматически учитывает десятичные и тысячные разделители, а также системы счисления, исходя из целевой локали.

const gt = new GT({ targetLocale: 'de' });

const formatted = gt.formatNum(1234.56, {
  style: 'decimal',
  minimumFractionDigits: 2
});
// Возвращает: «1.234,56» (немецкий формат чисел)

Справка

Параметры

ИмяТипОписание
numbernumberЧисло для форматирования
options?NumberFormatOptionsНеобязательные параметры форматирования

NumberFormatOptions

Дополняет Intl.NumberFormatOptions возможностью явного указания локали:

NameTypeDescription
locales?string | string[]Переопределение локалей для форматирования (по умолчанию используются локали экземпляра)
style?'decimal' | 'currency' | 'percent' | 'unit'Стиль форматирования числа
currency?stringКод валюты (обязателен, если style — 'currency')
currencyDisplay?'symbol' | 'narrowSymbol' | 'code' | 'name'Способ отображения валюты
currencySign?'standard' | 'accounting'Вид знака валюты
unit?stringИдентификатор единицы (обязателен, если style — 'unit')
unitDisplay?'short' | 'narrow' | 'long'Способ отображения единицы
minimumIntegerDigits?numberМинимальное число целых разрядов (1–21)
minimumFractionDigits?numberМинимальное число дробных разрядов (0–20)
maximumFractionDigits?numberМаксимальное число дробных разрядов (0–20)
minimumSignificantDigits?numberМинимальное количество значащих цифр (1–21)
maximumSignificantDigits?numberМаксимальное количество значащих цифр (1–21)
useGrouping?boolean | 'always' | 'auto' | 'min2'Использовать ли разделители группирования
notation?'standard' | 'scientific' | 'engineering' | 'compact'Формат нотации числа
compactDisplay?'short' | 'long'Стиль отображения компактной нотации
signDisplay?'auto' | 'never' | 'always' | 'exceptZero'Когда показывать знак
roundingMode?'ceil' | 'floor' | 'expand' | 'trunc' | 'halfCeil' | 'halfFloor' | 'halfExpand' | 'halfTrunc' | 'halfEven'Режим округления
roundingIncrement?1 | 2 | 5 | 10 | 20 | 25 | 50 | 100Шаг округления
trailingZeroDisplay?'auto' | 'stripIfInteger'Отображать ли конечные нули

Возвращает

string — отформатированное число в соответствии с правилами выбранной локали.


Примеры

Базовое форматирование чисел

import { GT } from 'generaltranslation';

const gt = new GT({ targetLocale: 'en-US' });

// Базовое форматирование десятичных чисел
console.log(gt.formatNum(1234.567));
// Результат: "1,234.567"

// Форматирование для немецкой локали
console.log(gt.formatNum(1234.567, { locales: 'de-DE' }));
// Результат: "1.234,567"

// Форматирование для французской локали  
console.log(gt.formatNum(1234.567, { locales: 'fr-FR' }));
// Результат: "1 234,567"

Форматирование валюты

// Форматирование в долларах США
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD'
}));
// Вывод: "$1,234.56"

// Форматирование евро для немецкой локали
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'EUR',
  locales: 'de-DE'
}));
// Вывод: "1.234,56 €"

// Варианты отображения валюты
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code'
}));
// Вывод: "USD 1,234.56"

// Бухгалтерский формат (отрицательные значения в скобках)
console.log(gt.formatNum(-1234.56, {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting'
}));
// Вывод: "($1,234.56)"

Проценты и научная запись

// Базовый формат процента
console.log(gt.formatNum(0.1234, { style: 'percent' }));
// Результат: "12%"

// Процент с десятичной точностью
console.log(gt.formatNum(0.1234, {
  style: 'percent',
  minimumFractionDigits: 1,
  maximumFractionDigits: 2
}));
// Результат: "12.34%"

// Компактная запись
console.log(gt.formatNum(1234567, { notation: 'compact' }));
// Результат: "1.2M"

// Научная запись
console.log(gt.formatNum(1234567, { notation: 'scientific' }));
// Результат: "1.235E6"

Примечания

  • Форматирование чисел автоматически следует локальным правилам
  • Метод использует встроенный в браузер Intl.NumberFormat для оптимальной производительности и точности
  • Для форматирования валют необходимо указать и style: 'currency', и действительный код currency
  • Для форматирования единиц измерения необходимо указать и style: 'unit', и действительный идентификатор unit

Дальнейшие шаги

  • Ознакомьтесь с документацией Intl.NumberFormat для дополнительных параметров
  • См. format-currency для специализированного форматирования валюты
  • См. format-message для форматирования сообщений с интерполяцией чисел
  • См. автономную функцию format-num для использования без экземпляра GT
  • См. get-locale-properties для сведений о форматировании, зависящих от локали

Насколько полезно это руководство?

formatNum