# 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. Le tableau répertorie les options courantes exposées par les types Core publiés et leurs valeurs par défaut effectives dans Core. Consultez les [options du constructeur `Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) pour obtenir des informations complémentaires sur les normes et les spécificités du runtime. | Nom | Description | Type | Facultatif | Par défaut | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `locales` | Remplace les paramètres régionaux utilisés pour le formatage. | `string \| string[]` | Oui | `targetLocale` → `sourceLocale` → `en` | | `localeMatcher` | Algorithme de correspondance des paramètres régionaux. | `'lookup' \| 'best fit'` | Oui | `'best fit'` | | `numberingSystem` | Système de numérotation, tel que `latn` ou `arab`. | `string` | Oui | `'latn'` | | `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–100). Le style affecte la valeur par défaut. | `number` | Oui | `0` pour les nombres décimaux/pourcentages ; chiffres de l’unité mineure de la devise pour les devises ; `0` avec les valeurs par défaut compactes | | `maximumFractionDigits` | Nombre maximal de chiffres fractionnaires (0–100). Le style et le minimum affectent la valeur par défaut. | `number` | Oui | `3` pour les nombres décimaux ; `0` pour les pourcentages ; chiffres de l’unité mineure de la devise pour les devises ; `0` avec les valeurs par défaut compactes | | `minimumSignificantDigits` | Nombre minimal de chiffres significatifs (1–21), lorsque l’arrondi par chiffres significatifs est actif. | `number` | Oui | `1` | | `maximumSignificantDigits` | Nombre maximal de chiffres significatifs (1–21), lorsque l’arrondi par chiffres significatifs est actif. | `number` | Oui | `21` ; `2` avec les valeurs par défaut compactes | | `roundingPriority` | Mode d’interaction entre les paramètres de chiffres fractionnaires et de chiffres significatifs. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Oui | `'auto'` ; `'morePrecision'` avec les valeurs par défaut compactes | | `notation` | Format de notation des nombres. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Oui | `'standard'` | | `compactDisplay` | Style d’affichage de la notation compacte. | `'short' \| 'long'` | Oui | `'short'` | | `useGrouping` | Indique s’il faut utiliser des séparateurs de regroupement et à quel moment. | `boolean \| 'always' \| 'auto' \| 'min2'` | Oui | `'auto'` ; `'min2'` avec la notation compacte | | `signDisplay` | Moment auquel afficher le signe. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Oui | `'auto'` | | `roundingMode` | Mode d’arrondi. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Oui | `'halfExpand'` | | `roundingIncrement` | Incrément d’arrondi. Les valeurs autres que la valeur par défaut nécessitent des nombres minimal et maximal effectifs de chiffres fractionnaires égaux et ne peuvent pas être combinées avec un arrondi par chiffres significatifs ou une valeur `roundingPriority` autre que `'auto'`. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Oui | `1` | | `trailingZeroDisplay` | Indique s’il faut afficher les zéros finaux non significatifs. | `'auto' \| 'stripIfInteger'` | Oui | `'auto'` | Lorsque `notation: 'compact'` est défini sans option relative aux chiffres fractionnaires ou significatifs, les valeurs effectives par défaut sont `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1` et `maximumSignificantDigits: 2`. Dans ce cas, `roundingPriority` prend par défaut la valeur `'morePrecision'` et `useGrouping`, la valeur `'min2'`. ## 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.