# General Translation Platform: formatNum URL: https://generaltranslation.com/it/docs/platform/core/reference/gt-class-methods/formatting/format-num.mdx --- title: formatNum description: Formatta numeri, valute, percentuali e valori numerici in base all'impostazione regionale. Riferimento API per formatNum. --- Formatta un numero secondo le convenzioni specifiche dell'impostazione regionale in un'istanza di [GT](/docs/platform/core/reference/gt-class/constructor). General Translation usa l'API integrata `Intl.NumberFormat` per gestire automaticamente i separatori decimali, quelli delle migliaia e i sistemi di numerazione per l'impostazione regionale di destinazione. ## Panoramica [#overview] Chiama `formatNum` su un'istanza di [`GT`](/docs/platform/core/reference/gt-class/constructor), passando il numero da formattare e, facoltativamente, un oggetto options. Restituisce il numero formattato come stringa. ```typescript const gt = new GT({ targetLocale: 'de' }); const formatted = gt.formatNum(1234.56, { style: 'decimal', minimumFractionDigits: 2, }); // "1.234,56" (formattazione numerica tedesca) ``` Firma: ```typescript formatNum( number: number, options?: { locales?: string | string[] } & Intl.NumberFormatOptions ): string ``` *Nota: `formatNum` viene eseguito localmente con `Intl.NumberFormat` e non richiede una chiave API. Per impostazione predefinita, formatta in base all'impostazione regionale di destinazione dell'istanza, con fallback prima all'impostazione regionale sorgente e poi al valore predefinito della libreria (`en`); specifica `locales` per sovrascriverla. Per la formattazione senza un'istanza `GT`, consulta la versione autonoma di [`formatNum`](/docs/platform/core/reference/utility-functions/formatting/format-num).* ## Come funziona [#how-it-works] * **Risoluzione dell'impostazione regionale.** Per impostazione predefinita, il metodo formatta usando l'impostazione regionale di destinazione dell'istanza, con fallback prima all'impostazione regionale sorgente e poi al valore predefinito della library (`en`) — non all'array di configurazione `locales`. Passa `locales` nelle opzioni per sovrascrivere questo comportamento per una singola chiamata. * **Basato su Intl.** La formattazione è delegata all'API nativa del browser [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), quindi tutte le `Intl.NumberFormatOptions` standard sono supportate e le convenzioni dell'impostazione regionale vengono applicate automaticamente. * **Requisiti di `style`.** 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. ## Parametri [#parameters] | Parametro | Descrizione | Tipo | Facoltativo | Predefinito | | --------------------- | ---------------------------------------------------------------------------------------------------- | -------- | ----------- | ----------- | | [`number`](#number) | Il numero da formattare. | `number` | No | — | | [`options`](#options) | Configurazione di formattazione che estende `Intl.NumberFormatOptions` con un override di `locales`. | `object` | Sì | — | ### `number` [#number] **Tipo** `number` · **Obbligatorio** Il numero da formattare. ### `options` [#options] **Tipo** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Facoltativo** Configurazione della formattazione. Estende `Intl.NumberFormatOptions` con un campo `locales` aggiuntivo: | Nome | Descrizione | Tipo | Facoltativo | Predefinito | | -------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------- | | `locales` | Sovrascrive le impostazioni regionali per la formattazione. | `string \| string[]` | Sì | impostazione regionale di destinazione dell'istanza | | `style` | Stile di formattazione dei numeri. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Sì | `'decimal'` | | `currency` | Codice valuta (obbligatorio quando `style` è `'currency'`). | `string` | Sì | — | | `currencyDisplay` | Come visualizzare la valuta. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Sì | `'symbol'` | | `currencySign` | Segno di valuta da usare. | `'standard' \| 'accounting'` | Sì | `'standard'` | | `unit` | Identificatore dell'unità (obbligatorio quando `style` è `'unit'`). | `string` | Sì | — | | `unitDisplay` | Come visualizzare l'unità. | `'short' \| 'narrow' \| 'long'` | Sì | `'short'` | | `minimumIntegerDigits` | Numero minimo di cifre intere (1–21). | `number` | Sì | `1` | | `minimumFractionDigits` | Numero minimo di cifre decimali (0–20). | `number` | Sì | — | | `maximumFractionDigits` | Numero massimo di cifre decimali (0–20). | `number` | Sì | — | | `minimumSignificantDigits` | Numero minimo di cifre significative (1–21). | `number` | Sì | — | | `maximumSignificantDigits` | Numero massimo di cifre significative (1–21). | `number` | Sì | — | | `useGrouping` | Indica se usare i separatori di raggruppamento. | `boolean \| 'always' \| 'auto' \| 'min2'` | Sì | `'auto'` | | `notation` | Formato della notazione numerica. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Sì | `'standard'` | | `compactDisplay` | Stile di visualizzazione della notazione compatta. | `'short' \| 'long'` | Sì | `'short'` | | `signDisplay` | Quando visualizzare il segno. | `'auto' \| 'never' \| 'always' \| 'exceptZero'` | Sì | `'auto'` | | `roundingMode` | Modalità di arrotondamento. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Sì | `'halfExpand'` | | `roundingIncrement` | Incremento di arrotondamento. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100` | Sì | `1` | | `trailingZeroDisplay` | Indica se visualizzare gli zeri finali. | `'auto' \| 'stripIfInteger'` | Sì | `'auto'` | ## Restituisce [#returns] **Tipo** `stringa` Il numero formattato, in base alle convenzioni dell'impostazione regionale di destinazione. ## Esempi [#examples] ```typescript 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" ``` ```typescript // Formattazione valuta // Formattazione dollaro USA console.log(gt.formatNum(1234.56, { style: 'currency', currency: 'USD', })); // Output: "$1,234.56" // Formattazione 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 valuta console.log(gt.formatNum(1234.56, { style: 'currency', currency: 'USD', currencyDisplay: 'code', })); // Output: "USD 1,234.56" // Formato contabile (parentesi per i negativi) console.log(gt.formatNum(-1234.56, { style: 'currency', currency: 'USD', currencySign: 'accounting', })); // Output: "($1,234.56)" ``` ```typescript // Percentuale e notazione scientifica // 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 [#notes] * La formattazione dei numeri segue automaticamente le convenzioni dell'impostazione regionale. * Il metodo usa `Intl.NumberFormat` integrato nel browser per garantire prestazioni e accuratezza. * La formattazione della valuta richiede sia `style: 'currency'` sia un codice `currency` valido. * La formattazione delle unità richiede sia `style: 'unit'` sia un identificatore `unit` valido.