# General Translation Platform: formatCurrency URL: https://generaltranslation.com/ru/docs/platform/core/reference/gt-class-methods/formatting/format-currency.mdx --- title: formatCurrency description: Форматирует значение Currency по локали в экземпляре GT. Справка по API для formatCurrency. --- General Translation использует встроенный API `Intl.NumberFormat` со стилем `currency`, поэтому суммы отображаются с правильным символом валюты, разделителями разрядов и десятичными знаками для каждой локали. ## Обзор [#overview] Вызовите `formatCurrency` у экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor), передав числовое значение, код Currency и необязательный объект параметров. Метод возвращает строку с отформатированным значением Currency. ```typescript const gt = new GT({ targetLocale: 'en-US' }); const price = gt.formatCurrency(1234.56, 'USD'); // "$1,234.56" ``` Сигнатура: ```typescript formatCurrency( value: number, currency: string, options?: { locales?: string | string[] } & Intl.NumberFormatOptions ): string ``` *Примечание: `formatCurrency` работает локально с использованием `Intl.NumberFormat` и не требует API-ключа. По умолчанию форматирование применяется к целевой локали экземпляра; если она недоступна, используется исходная локаль, а затем локаль библиотеки по умолчанию (`en`). Чтобы переопределить это поведение, передайте `locales`. О форматировании без экземпляра `GT` см. в отдельной функции [`formatCurrency`](/docs/platform/core/reference/utility-functions/formatting/format-currency).* ## Как это работает [#how-it-works] * **Стиль Currency.** Форматирование выполняется через [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) с `style: 'currency'` и указанным кодом `currency`. * **Определение локали.** По умолчанию метод форматирует значение для целевой локали этого экземпляра, с откатом сначала к исходной локали, а затем к локали библиотеки по умолчанию (`en`) — а не к массиву конфигурации `locales`. Чтобы переопределить это поведение, передайте `locales` в параметре options. * **Положение символа.** Символ валюты, разделители групп разрядов и формат десятичной части определяются выбранной локалью, а не страной валюты. ## Параметры [#parameters] | Параметр | Описание | Тип | Необязательно | По умолчанию | | ----------------------- | -------------------------------------------------------------------------------------------------------- | -------- | ------------- | ------------ | | [`value`](#value) | Числовое значение для форматирования. | `number` | Нет | — | | [`currency`](#currency) | Код валюты по стандарту ISO 4217, например `USD` или `EUR`. | `string` | Нет | — | | [`options`](#options) | Параметры форматирования, расширяющие `Intl.NumberFormatOptions` и позволяющие переопределить `locales`. | `object` | Да | — | ### `value` [#value] **Тип** `number` · **Обязательно** Число, которое нужно отформатировать. ### `currency` [#currency] **Тип** `string` · **Обязательно** Код Currency по стандарту ISO 4217, например `USD`, `EUR` или `JPY`. ### `options` [#options] **Тип** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Необязательно** Параметры форматирования. В таблице перечислены распространённые параметры Currency, предоставляемые опубликованными типами Ядра, и их фактические значения по умолчанию в Ядре. Дополнительные стандартные сведения и сведения, зависящие от 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` | Стиль форматирования чисел. `formatCurrency` задаёт стиль Currency, если его не переопределить. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Да | `'currency'` | | `currency` | Код валюты, используемый форматтером. Это значение задаётся позиционным аргументом `currency`, если его не переопределить. | `string` | Да | позиционный аргумент `currency` | | `currencyDisplay` | Способ отображения валюты. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Да | `'symbol'` | | `currencySign` | Используемый формат обозначения валюты. | `'standard' \| 'accounting'` | Да | `'standard'` | | `unit` | Идентификатор единицы времени. Обязателен, если `style` имеет значение `'unit'`. | `string` | Да | — | | `unitDisplay` | Способ отображения единицы времени. | `'short' \| 'narrow' \| 'long'` | Да | `'short'` | | `minimumFractionDigits` | Минимальное количество знаков после запятой (0–100). | `number` | Да | количество знаков в дробной части для валюты; `0` при компактных настройках по умолчанию | | `maximumFractionDigits` | Максимальное количество знаков после запятой (0–100), не меньше `minimumFractionDigits`. | `number` | Да | количество знаков в дробной части для валюты; `0` при компактных настройках по умолчанию | | `minimumSignificantDigits` | Минимальное количество значащих цифр (1–21), если включено округление по значащим цифрам. | `number` | Да | `1` | | `maximumSignificantDigits` | Максимальное количество значащих цифр (1–21), если включено округление по значащим цифрам. | `number` | Да | `21`; `2` при компактных настройках по умолчанию | | `roundingPriority` | Взаимодействие настроек знаков после запятой и значащих цифр. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Да | `'auto'`; `'morePrecision'` при компактных настройках по умолчанию | | `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` | | `useGrouping` | Следует ли использовать разделители групп и когда. | `boolean \| 'always' \| 'auto' \| 'min2'` | Да | `'auto'`; `'min2'` при компактных настройках по умолчанию | | `notation` | Формат представления чисел. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Да | `'standard'` | | `compactDisplay` | Стиль отображения в компактной нотации. | `'short' \| 'long'` | Да | `'short'` | | `signDisplay` | Когда отображать знак. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Да | `'auto'` | | `trailingZeroDisplay` | Следует ли отображать конечные нули. | `'auto' \| 'stripIfInteger'` | Да | `'auto'` | Если `notation: 'compact'` задан без параметров дробных или значимых цифр, по умолчанию используются следующие эффективные значения: `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1` и `maximumSignificantDigits: 2`. В этом случае для `roundingPriority` по умолчанию используется значение `'morePrecision'`, а для `useGrouping` — `'min2'`. Для `style: 'unit'` также необходимо указать допустимую единицу времени. ## Returns [#returns] **Type** `string` Значение, отформатированное в виде локализованной строки Currency. ## Примеры [#examples] ```typescript import { GT } from 'generaltranslation'; const gt = new GT({ targetLocale: 'en-US' }); // Целевая локаль экземпляра по умолчанию console.log(gt.formatCurrency(1234.56, 'USD')); // Вывод: "$1,234.56" // Переопределение локали для отдельного вызова console.log(gt.formatCurrency(1234.56, 'EUR', { locales: ['de-DE'] })); // Вывод: "1.234,56 €" // Без дробных разрядов console.log(gt.formatCurrency(1234, 'JPY', { locales: ['ja-JP'] })); // Вывод: "￥1,234" ``` ## Заметки [#notes] * Метод использует встроенный в браузер `Intl.NumberFormat`, поэтому формат сумм соответствует правилам локали. * Передайте любые `Intl.NumberFormatOptions` (например, `minimumFractionDigits`) вместе с `locales`, чтобы точнее настроить вывод.