# General Translation Platform: formatNum URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/formatting/format-num.mdx Docs index: https://generaltranslation.com/llms.txt Description: Форматирует числа, валюты, проценты и числовые значения в зависимости от локали. Справочник по API для formatNum. Форматирует число в экземпляре [GT](/docs/platform/core/reference/gt-class/constructor) в соответствии с правилами конкретной локали. General Translation использует встроенный API `Intl.NumberFormat`, чтобы автоматически обрабатывать десятичные разделители, разделители групп разрядов и системы нумерации для целевой локали. ## Обзор [#overview] Вызовите `formatNum` у экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor), передав число для форматирования и, при необходимости, объект параметров. Метод возвращает отформатированное число в виде строки. ```typescript const gt = new GT({ targetLocale: 'de' }); const formatted = gt.formatNum(1234.56, { style: 'decimal', minimumFractionDigits: 2, }); // "1.234,56" (немецкое форматирование чисел) ``` Сигнатура: ```typescript formatNum( number: number, options?: { locales?: string | string[] } & Intl.NumberFormatOptions ): string ``` *Примечание: `formatNum` выполняется локально с помощью `Intl.NumberFormat` и не требует API-ключа. По умолчанию форматирование выполняется для целевой локали экземпляра; если она недоступна, используется исходная локаль, а затем локаль библиотеки по умолчанию (`en`). Чтобы переопределить это поведение, передайте `locales`. О форматировании без экземпляра `GT` см. отдельную функцию [`formatNum`](/docs/platform/core/reference/utility-functions/formatting/format-num).* ## Как это работает [#how-it-works] * **Определение локали.** По умолчанию метод форматирует данные для целевой локали экземпляра; если она недоступна, используется исходная локаль, а затем локаль библиотеки по умолчанию (`en`) — а не массив конфигурации `locales`. Чтобы переопределить это для одного вызова, передайте `locales` в параметрах. * **На базе Intl.** Форматирование делегируется встроенному в браузер [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), поэтому поддерживаются все стандартные `Intl.NumberFormatOptions`, а правила локали применяются автоматически. * **Требования к style.** Для форматирования валюты нужны и `style: 'currency'`, и корректный код `currency`. Для форматирования единиц измерения нужны и `style: 'unit'`, и корректный идентификатор `unit`. ## Параметры [#parameters] | Параметр | Описание | Тип | Необязательный | По умолчанию | | --------------------- | -------------------------------------------------------------------------------------------------------- | -------- | -------------- | ------------ | | [`number`](#number) | Число, которое нужно отформатировать. | `number` | Нет | — | | [`options`](#options) | Параметры форматирования, расширяющие `Intl.NumberFormatOptions` и позволяющие переопределить `locales`. | `object` | Да | — | ### `number` [#number] **Тип** `number` · **Обязательный** Число, которое нужно отформатировать. ### `options` [#options] **Тип** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Необязательно** Параметры форматирования. В таблице перечислены распространённые параметры, доступные в опубликованных типах Ядра, и их фактические значения по умолчанию в Ядре. (Дополнительные сведения о стандарте и особенностях Runtime см. в [параметрах конструктора `Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)). | Имя | Описание | Тип | Необязательно | По умолчанию | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `locales` | Переопределяет локали для форматирования. | `string \| string[]` | Да | `targetLocale` → `sourceLocale` → `en` | | `localeMatcher` | Алгоритм сопоставления локалей. | `'lookup' \| 'best fit'` | Да | `'best fit'` | | `numberingSystem` | Система нумерации, например `latn` или `arab`. | `string` | Да | `'latn'` | | `style` | Стиль форматирования числа. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Да | `'decimal'` | | `currency` | Код валюты (обязательно, если `style` имеет значение `'currency'`). | `string` | Да | — | | `currencyDisplay` | Как отображать валюту. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Да | `'symbol'` | | `currencySign` | Какой знак валюты использовать. | `'standard' \| 'accounting'` | Да | `'standard'` | | `unit` | Идентификатор единицы измерения (обязательно, если `style` имеет значение `'unit'`). | `string` | Да | — | | `unitDisplay` | Как отображать единицу измерения. | `'short' \| 'narrow' \| 'long'` | Да | `'short'` | | `minimumIntegerDigits` | Минимальное количество цифр в целой части (1–21). | `number` | Да | `1` | | `minimumFractionDigits` | Минимальное количество цифр в дробной части (0–100). Стиль влияет на значение по умолчанию. | `number` | Да | `0` для decimal/percent; количество цифр дробной единицы валюты для currency; `0` с компактными настройками по умолчанию | | `maximumFractionDigits` | Максимальное количество цифр в дробной части (0–100). Стиль и минимальное значение влияют на значение по умолчанию. | `number` | Да | `3` для decimal; `0` для percent; количество цифр дробной единицы валюты для currency; `0` с компактными настройками по умолчанию | | `minimumSignificantDigits` | Минимальное количество значащих цифр (1–21), когда активно округление по значащим цифрам. | `number` | Да | `1` | | `maximumSignificantDigits` | Максимальное количество значащих цифр (1–21), когда активно округление по значащим цифрам. | `number` | Да | `21`; `2` с компактными настройками по умолчанию | | `roundingPriority` | Как взаимодействуют настройки дробных и значащих цифр. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Да | `'auto'`; `'morePrecision'` с компактными настройками по умолчанию | | `notation` | Формат записи числа. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Да | `'standard'` | | `compactDisplay` | Стиль отображения компактной записи. | `'short' \| 'long'` | Да | `'short'` | | `useGrouping` | Использовать ли и когда разделители разрядов. | `boolean \| 'always' \| 'auto' \| 'min2'` | Да | `'auto'`; `'min2'` при компактной записи | | `signDisplay` | Когда отображать знак. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Да | `'auto'` | | `roundingMode` | Режим округления. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Да | `'halfExpand'` | | `roundingIncrement` | Шаг округления. Значения, отличные от значения по умолчанию, требуют одинакового фактического минимального и максимального количества цифр в дробной части и не могут сочетаться с округлением по значащим цифрам или `roundingPriority`, отличным от `'auto'`. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Да | `1` | | `trailingZeroDisplay` | Показывать ли конечные нули. | `'auto' \| 'stripIfInteger'` | Да | `'auto'` | Если параметр `notation: 'compact'` задан без параметров дробных или значимых цифр, по умолчанию используются следующие эффективные значения: `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1` и `maximumSignificantDigits: 2`. В этом случае для `roundingPriority` по умолчанию используется `'morePrecision'`, а для `useGrouping` — `'min2'`. ## Возвращает [#returns] **Тип** `string` Число, отформатированное в соответствии с правилами целевой локали. ## Примеры [#examples] ```typescript 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" ``` ```typescript // Форматирование валюты // Форматирование в долларах США 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)" ``` ```typescript // Процентный формат и научная нотация // Базовый процентный формат 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" ``` ## Заметки [#notes] * Форматирование чисел автоматически учитывает правила текущей локали. * Для производительности и точности метод использует встроенный в браузер `Intl.NumberFormat`. * Для форматирования валюты нужны и `style: 'currency'`, и корректный код `currency`. * Для форматирования единиц измерения нужны и `style: 'unit'`, и корректный идентификатор `unit`. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.