# General Translation Platform: formatNum
URL: https://generaltranslation.com/ru/docs/platform/core/reference/utility-functions/formatting/format-num.mdx
---

title: formatNum
description: Форматирование чисел, валют, процентов и числовых значений без экземпляра GT. Справка API для formatNum.

---

[`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) — это автономная вспомогательная функция из основной библиотеки General Translation, которая форматирует числа в соответствии с правилами конкретной локали. Она возвращает строку, отформатированную с учетом локали, для десятичных чисел, валют, процентов и единиц измерения.

## Обзор [#overview]

Импортируйте `formatNum` напрямую из `generaltranslation` и вызовите её, передав число для форматирования и объект параметров. Для этого не нужен API-ключ или экземпляр [GT](/docs/platform/core/reference/gt-class/constructor), поэтому используйте её везде, где требуется разовое форматирование чисел. Если же вам нужно форматирование через экземпляр с унаследованной от него локалью, используйте метод [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) экземпляра [`GT`](/docs/platform/core/reference/gt-class/constructor).

```typescript
import { formatNum } from 'generaltranslation';

const formatted = formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
});
// Возвращает: "1.234,56 €"
```

Сигнатура:

```typescript
formatNum(
  number: number,
  options?: { locales?: string | string[] } & Intl.NumberFormatOptions
): string
```

## Как это работает [#how-it-works]

* **Базовый API.** Использует тот же [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), что и метод класса GT, поэтому поддерживаются все стандартные параметры `Intl.NumberFormat`.
* **Определение локали.** Если `locales` — это массив, локали перебираются по порядку, и используется первая поддерживаемая локаль. Если `locales` не указано, используется локаль библиотеки по умолчанию — `en`.
* **Кэширование.** Для повышения производительности результаты кэшируются для повторяющихся сочетаний локалей и параметров.

## Параметры [#parameters]

| Параметр              | Описание                                                                                           | Тип                                                           | Необязательный | По умолчанию |
| --------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------- | ------------ |
| [`number`](#number)   | Число, которое нужно отформатировать.                                                              | `number`                                                      | Нет            | —            |
| [`options`](#options) | Параметры форматирования, включая целевую локаль или локали и любые параметры `Intl.NumberFormat`. | `{ locales?: string \| string[] } & Intl.NumberFormatOptions` | Да             | `{}`         |

### `number` [#number]

**Тип** `number` · **Обязательный**

Числовое значение, которое нужно отформатировать.

### `options` [#options]

**Тип** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Необязательный** · **По умолчанию** `{}`

Параметры форматирования. Помимо `locales`, поддерживаются любые параметры [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat). Наиболее распространённые поля:

| Свойство                | Описание                                                                    | Тип                                                        | Необязательно | По умолчанию |
| ----------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------- | ------------ |
| `locales`               | Локали для форматирования. Если передан массив, они проверяются по порядку. | `string \| string[]`                                       | Да            | `en`         |
| `style`                 | Стиль форматирования числа.                                                 | `'decimal' \| 'currency' \| 'percent' \| 'unit'`           | Да            | `'decimal'`  |
| `currency`              | Код валюты (обязателен, если `style` имеет значение `'currency'`).          | `string`                                                   | Да            | —            |
| `minimumIntegerDigits`  | Минимальное количество цифр в целой части (1–21).                           | `number`                                                   | Да            | —            |
| `minimumFractionDigits` | Минимальное количество цифр в дробной части (0–20).                         | `number`                                                   | Да            | —            |
| `maximumFractionDigits` | Максимальное количество цифр в дробной части (0–20).                        | `number`                                                   | Да            | —            |
| `useGrouping`           | Нужно ли использовать разделители разрядов.                                 | `boolean \| 'always' \| 'auto' \| 'min2'`                  | Да            | `'auto'`     |
| `notation`              | Формат записи числа.                                                        | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Да            | `'standard'` |

## Возвращает [#returns]

**Тип** `string`

Число, отформатированное по правилам локали.

## Примеры [#examples]

```typescript
import { formatNum } from 'generaltranslation';

// Базовое форматирование чисел
console.log(formatNum(1234.567, { locales: 'en-US' }));
// Вывод: "1,234.567"

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

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

// Доллар США
console.log(formatNum(1234.56, {
  locales: 'en-US',
  style: 'currency',
  currency: 'USD',
}));
// Output: "$1,234.56"

// Евро с немецкой локалью
console.log(formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
}));
// Output: "1.234,56 €"

// Японская иена
console.log(formatNum(1234.56, {
  locales: 'ja-JP',
  style: 'currency',
  currency: 'JPY',
}));
// Output: "¥1,235"
```

## Примечания [#notes]

* Использует тот же механизм `Intl.NumberFormat`, что и метод класса GT.
* Для повышения производительности результаты кэшируются при повторном использовании одинаковых комбинаций локали и параметров.
* Если основная локаль не поддерживается, резервные локали обрабатываются по порядку.
* Поддерживаются все стандартные параметры `Intl.NumberFormat`.