# General Translation Platform: formatNum URL: https://generaltranslation.com/fr/docs/platform/core/reference/gt-class-methods/formatting/format-num.mdx --- title: formatNum description: Met en forme les nombres, les devises, les pourcentages et les valeurs numériques selon le paramètre régional. Référence de l’API pour formatNum. --- Met en forme un nombre selon les conventions propres au paramètre régional sur une instance de [GT](/docs/platform/core/reference/gt-class/constructor). General Translation utilise l’API intégrée `Intl.NumberFormat` pour gérer automatiquement les séparateurs décimaux, les séparateurs de regroupement et les systèmes de numération du paramètre régional cible. ## Vue d’ensemble [#overview] Appelez `formatNum` sur une instance de [`GT`](/docs/platform/core/reference/gt-class/constructor) avec le nombre à formater et, éventuellement, un objet d’options. Elle renvoie le nombre formaté sous forme de chaîne de caractères. ```typescript const gt = new GT({ targetLocale: 'de' }); const formatted = gt.formatNum(1234.56, { style: 'decimal', minimumFractionDigits: 2, }); // "1.234,56" (formatage numérique allemand) ``` Signature : ```typescript formatNum( number: number, options?: { locales?: string | string[] } & Intl.NumberFormatOptions ): string ``` *Remarque : `formatNum` s’exécute localement avec `Intl.NumberFormat` et ne nécessite pas de clé API. Par défaut, il utilise le paramètre régional cible de l’instance pour le formatage, puis se rabat sur le paramètre régional source et enfin sur la valeur par défaut de la bibliothèque (`en`) ; passez `locales` pour remplacer ce comportement. Pour effectuer un formatage sans instance `GT`, consultez la version autonome de [`formatNum`](/docs/platform/core/reference/utility-functions/formatting/format-num).* ## Fonctionnement [#how-it-works] * **Résolution du paramètre régional.** Par défaut, la méthode formate selon le paramètre régional cible de l'instance, avec repli sur le paramètre régional source puis sur la valeur par défaut de la bibliothèque (`en`) — et non sur le tableau de configuration `locales`. Passez `locales` dans les options pour le remplacer lors d'un seul appel. * **Basé sur Intl.** Le formatage est délégué à [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), intégré au navigateur ; toutes les `Intl.NumberFormatOptions` standard sont donc prises en charge et les conventions du paramètre régional sont appliquées automatiquement. * **Exigences de style.** Le formatage des devises nécessite à la fois `style: 'currency'` et un code `currency` valide. Le formatage des unités nécessite à la fois `style: 'unit'` et un identifiant `unit` valide. ## Paramètres [#parameters] | Paramètre | Description | Type | Facultatif | Valeur par défaut | | --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ---------- | ----------------- | | [`number`](#number) | Le nombre à formater. | `number` | Non | — | | [`options`](#options) | Configuration de formatage qui étend `Intl.NumberFormatOptions` avec une redéfinition de `locales`. | `object` | Oui | — | ### `number` [#number] **Type** `number` · **Obligatoire** Le nombre à mettre en forme. ### `options` [#options] **Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Facultatif** Configuration de formatage. Étend `Intl.NumberFormatOptions` avec un champ `locales` supplémentaire : | Nom | Description | Type | Facultatif | Par défaut | | -------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------- | | `locales` | Redéfinit les paramètres régionaux utilisés pour le formatage. | `string \| string[]` | Oui | paramètre régional cible de l’instance | | `style` | Style de formatage des nombres. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Oui | `'decimal'` | | `currency` | Code de devise (requis lorsque `style` vaut `'currency'`). | `string` | Oui | — | | `currencyDisplay` | Mode d’affichage de la devise. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Oui | `'symbol'` | | `currencySign` | Signe monétaire à utiliser. | `'standard' \| 'accounting'` | Oui | `'standard'` | | `unit` | Identifiant d’unité (requis lorsque `style` vaut `'unit'`). | `string` | Oui | — | | `unitDisplay` | Mode d’affichage de l’unité. | `'short' \| 'narrow' \| 'long'` | Oui | `'short'` | | `minimumIntegerDigits` | Nombre minimal de chiffres entiers (1–21). | `number` | Oui | `1` | | `minimumFractionDigits` | Nombre minimal de chiffres fractionnaires (0–20). | `number` | Oui | — | | `maximumFractionDigits` | Nombre maximal de chiffres fractionnaires (0–20). | `number` | Oui | — | | `minimumSignificantDigits` | Nombre minimal de chiffres significatifs (1–21). | `number` | Oui | — | | `maximumSignificantDigits` | Nombre maximal de chiffres significatifs (1–21). | `number` | Oui | — | | `useGrouping` | Indique s’il faut utiliser des séparateurs de regroupement. | `boolean \| 'always' \| 'auto' \| 'min2'` | Oui | `'auto'` | | `notation` | Format de notation des nombres. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Oui | `'standard'` | | `compactDisplay` | Style d’affichage de la notation compacte. | `'short' \| 'long'` | Oui | `'short'` | | `signDisplay` | Moment auquel afficher le signe. | `'auto' \| 'never' \| 'always' \| 'exceptZero'` | Oui | `'auto'` | | `roundingMode` | Mode d’arrondi. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Oui | `'halfExpand'` | | `roundingIncrement` | Incrément d’arrondi. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100` | Oui | `1` | | `trailingZeroDisplay` | Indique s’il faut afficher les zéros finaux non significatifs. | `'auto' \| 'stripIfInteger'` | Oui | `'auto'` | ## Retourne [#returns] **Type** `string` Le nombre formaté, conformément aux conventions du paramètre régional cible. ## Exemples [#examples] ```typescript import { GT } from 'generaltranslation'; const gt = new GT({ targetLocale: 'en-US' }); // Formatage décimal de base console.log(gt.formatNum(1234.567)); // Résultat : "1,234.567" // Formatage avec le paramètre régional allemand console.log(gt.formatNum(1234.567, { locales: 'de-DE' })); // Résultat : "1.234,567" // Formatage avec le paramètre régional français console.log(gt.formatNum(1234.567, { locales: 'fr-FR' })); // Résultat : "1 234,567" ``` ```typescript // Formatage de devise // Formatage en dollar américain console.log(gt.formatNum(1234.56, { style: 'currency', currency: 'USD', })); // Output: "$1,234.56" // Formatage en euro avec le paramètre régional allemand console.log(gt.formatNum(1234.56, { style: 'currency', currency: 'EUR', locales: 'de-DE', })); // Output: "1.234,56 €" // Options d'affichage de la devise console.log(gt.formatNum(1234.56, { style: 'currency', currency: 'USD', currencyDisplay: 'code', })); // Output: "USD 1,234.56" // Format comptable (parenthèses pour les valeurs négatives) console.log(gt.formatNum(-1234.56, { style: 'currency', currency: 'USD', currencySign: 'accounting', })); // Output: "($1,234.56)" ``` ```typescript // Pourcentage et notation scientifique // Pourcentage simple console.log(gt.formatNum(0.1234, { style: 'percent' })); // Output: "12%" // Pourcentage avec décimales console.log(gt.formatNum(0.1234, { style: 'percent', minimumFractionDigits: 1, maximumFractionDigits: 2, })); // Output: "12.34%" // Notation compacte console.log(gt.formatNum(1234567, { notation: 'compact' })); // Output: "1.2M" // Notation scientifique console.log(gt.formatNum(1234567, { notation: 'scientific' })); // Output: "1.235E6" ``` ## Remarques [#notes] * Le formatage des nombres respecte automatiquement les conventions propres au paramètre régional. * La méthode utilise l’API native du navigateur `Intl.NumberFormat` pour garantir de bonnes performances et une grande précision. * Le formatage des devises nécessite à la fois `style: 'currency'` et un code `currency` valide. * Le formatage des unités nécessite à la fois `style: 'unit'` et un identifiant `unit` valide.