# generaltranslation: General Translation Core SDK: formatNum
URL: https://generaltranslation.com/ru/docs/core/class/methods/formatting/format-num.mdx
---
title: formatNum
description: Справка по API метода formatNum для форматирования чисел в соответствии с правилами локали
---

## Обзор

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

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

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


## Справка

### Параметры

| Название   | Тип                   | Описание                                |
| ---------- | --------------------- | --------------------------------------- |
| `number`   | `number`              | Число, которое нужно отформатировать    |
| `options?` | `NumberFormatOptions` | Необязательные параметры форматирования |

### NumberFormatOptions

Расширяет `Intl.NumberFormatOptions`, добавляя возможность дополнительно указать локаль:

| Name                        | Type                                                                                                                 | Description                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `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` — Число, отформатированное в соответствии с локалью.

***

## Примеры

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

```typescript copy
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 copy
// Форматирование в долларах США
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD'
}));
// Output: "$1,234.56"

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

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

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


### Проценты и экспоненциальная запись

```typescript copy
// Базовый процент
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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), чтобы узнать о дополнительных возможностях
* См. [`format-message`](/docs/core/class/methods/formatting/format-message) для форматирования сообщений с подстановкой чисел
* См. автономный [`format-num`](/docs/core/functions/formatting/format-num) для использования без экземпляра GT
* См. [`get-locale-properties`](/docs/core/class/methods/locales/get-locale-properties) для получения информации о форматировании, специфичном для локали