# generaltranslation: General Translation Core SDK: formatNum
URL: https://generaltranslation.com/it/docs/core/class/methods/formatting/format-num.mdx
---
title: formatNum
description: Documentazione di riferimento dell'API per il metodo formatNum, che formatta i numeri secondo le convenzioni dell'impostazione regionale
---

## Panoramica

Il metodo `formatNum` formatta i numeri secondo convenzioni specifiche dell’impostazione regionale utilizzando l’API di internazionalizzazione.
Gestisce automaticamente i separatori decimali, i separatori delle migliaia e i sistemi di numerazione in base all’impostazione regionale di destinazione.

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

const formatted = gt.formatNum(1234.56, {
  style: 'decimal',
  minimumFractionDigits: 2
});
// Restituisce: "1.234,56" (formattazione numerica tedesca)
```


## Riferimento

### Parametri

| Nome       | Tipo                  | Descrizione                               |
| ---------- | --------------------- | ----------------------------------------- |
| `number`   | `number`              | Il numero da formattare                   |
| `options?` | `NumberFormatOptions` | Configurazione di formattazione opzionale |

### NumberFormatOptions

Estende `Intl.NumberFormatOptions` con una specifica aggiuntiva per l'impostazione regionale:

| Nome                        | Tipo                                                                                                                 | Descrizione                                                                                                           |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `locales?`                  | `string \| string[]`                                                                                                 | Sostituisce le impostazioni regionali per la formattazione (per impostazione predefinita usa quelle dell'istanza) |
| `style?`                    | `'decimal' \| 'currency' \| 'percent' \| 'unit'`                                                                     | Stile di formattazione dei numeri                                                                                     |
| `currency?`                 | `string`                                                                                                             | Codice valuta (obbligatorio quando lo stile è 'currency')                                                     |
| `currencyDisplay?`          | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'`                                                                     | Modalità di visualizzazione della valuta                                                                              |
| `currencySign?`             | `'standard' \| 'accounting'`                                                                                         | Segno di valuta da usare                                                                                              |
| `unit?`                     | `string`                                                                                                             | Identificatore dell'unità (obbligatorio quando lo stile è 'unit')                                         |
| `unitDisplay?`              | `'short' \| 'narrow' \| 'long'`                                                                                      | Modalità di visualizzazione dell'unità                                                                            |
| `minimumIntegerDigits?`     | `number`                                                                                                             | Numero minimo di cifre intere (1-21)                                                                                  |
| `minimumFractionDigits?`    | `number`                                                                                                             | Numero minimo di cifre decimali (0-20)                                                                                |
| `maximumFractionDigits?`    | `number`                                                                                                             | Numero massimo di cifre decimali (0-20)                                                                               |
| `minimumSignificantDigits?` | `number`                                                                                                             | Numero minimo di cifre significative (1-21)                                                                           |
| `maximumSignificantDigits?` | `number`                                                                                                             | Numero massimo di cifre significative (1-21)                                                                          |
| `useGrouping?`              | `boolean \| 'always' \| 'auto' \| 'min2'`                                                                            | Indica se usare i separatori delle migliaia                                                                           |
| `notation?`                 | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`                                                           | Formato della notazione numerica                                                                                      |
| `compactDisplay?`           | `'short' \| 'long'`                                                                                                  | Stile di visualizzazione della notazione compatta                                                                     |
| `signDisplay?`              | `'auto' \| 'never' \| 'always' \| 'exceptZero'`                                                                      | Quando visualizzare il segno                                                                                          |
| `roundingMode?`             | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Modalità di arrotondamento                                                                                            |
| `roundingIncrement?`        | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100`                                                                         | Incremento di arrotondamento                                                                                          |
| `trailingZeroDisplay?`      | `'auto' \| 'stripIfInteger'`                                                                                         | Indica se visualizzare gli zeri finali                                                                                |

### Restituisce

`string` - Il numero formattato in base alle convenzioni dell'impostazione regionale.

***

## Esempi

### Formattazione di base dei numeri

```typescript copy
import { GT } from 'generaltranslation';

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

// Formattazione decimale di base
console.log(gt.formatNum(1234.567));
// Output: "1,234.567"

// Formattazione con impostazione regionale tedesca
console.log(gt.formatNum(1234.567, { locales: 'de-DE' }));
// Output: "1.234,567"

// Formattazione con impostazione regionale francese  
console.log(gt.formatNum(1234.567, { locales: 'fr-FR' }));
// Output: "1 234,567"
```


### Formattazione delle valute

```typescript copy
// Formattazione in dollari statunitensi
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD'
}));
// Output: "$1,234.56"

// Formattazione in euro con impostazione regionale tedesca
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'EUR',
  locales: 'de-DE'
}));
// Output: "1.234,56 €"

// Opzioni di visualizzazione della valuta
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code'
}));
// Output: "USD 1,234.56"

// Formato contabile (parentesi per i valori negativi)
console.log(gt.formatNum(-1234.56, {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting'
}));
// Output: "($1,234.56)"
```


### Percentuali e notazione scientifica

```typescript copy
// Percentuale di base
console.log(gt.formatNum(0.1234, { style: 'percent' }));
// Output: "12%"

// Percentuale con cifre decimali
console.log(gt.formatNum(0.1234, {
  style: 'percent',
  minimumFractionDigits: 1,
  maximumFractionDigits: 2
}));
// Output: "12.34%"

// Notazione compatta
console.log(gt.formatNum(1234567, { notation: 'compact' }));
// Output: "1.2M"

// Notazione scientifica
console.log(gt.formatNum(1234567, { notation: 'scientific' }));
// Output: "1.235E6"
```

***


## Note

* La formattazione dei numeri segue automaticamente le convenzioni specifiche dell’impostazione regionale
* Il metodo usa `Intl.NumberFormat` nativo del browser per garantire prestazioni e accuratezza ottimali
* La formattazione delle valute richiede sia `style: 'currency'` sia un codice `currency` valido
* La formattazione delle unità richiede sia `style: 'unit'` sia un identificatore `unit` valido

## Passi successivi

* Consulta la documentazione di [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) per altre opzioni
* Vedi [`format-message`](/docs/core/class/methods/formatting/format-message) per la formattazione dei messaggi con interpolazione numerica
* Vedi la versione autonoma di [`format-num`](/docs/core/functions/formatting/format-num) per l'uso senza un'istanza GT
* Vedi [`get-locale-properties`](/docs/core/class/methods/locales/get-locale-properties) per informazioni sulla formattazione specifiche dell'impostazione regionale