# General Translation Platform: formatNum URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/formatting/format-num.mdx --- title: formatNum description: 按区域设置格式化数字、货币、百分比和数值。formatNum 的 API 参考。 --- 在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，按照区域设置的惯例格式化数字。General Translation 使用内置的 `Intl.NumberFormat` API，自动处理目标区域设置的小数分隔符、分组分隔符和数字系统。 ## 概览 [#overview] 在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `formatNum`，传入要格式化的数字和一个可选的选项对象。它会返回格式化后的数字字符串。 ```typescript const gt = new GT({ targetLocale: 'de' }); const formatted = gt.formatNum(1234.56, { style: 'decimal', minimumFractionDigits: 2, }); // "1.234,56"（德语数字格式） ``` 签名： ```typescript formatNum( number: number, options?: { locales?: string | string[] } & Intl.NumberFormatOptions ): string ``` *注意：`formatNum` 在本地通过 `Intl.NumberFormat` 运行，不需要 API 密钥。默认情况下，它会按该实例的目标区域设置进行格式化，并依次回退到源区域设置以及库的默认值 (`en`) ；传入 `locales` 可覆盖此设置。若要在没有 `GT` 实例的情况下进行格式化，请参阅独立版 [`formatNum`](/docs/platform/core/reference/utility-functions/formatting/format-num)。* ## 工作方式 [#how-it-works] * **区域设置解析。** 默认情况下，此方法会使用实例的目标区域设置进行格式化，并依次回退到 源区域设置 和库默认值 (`en`) ——而不是 `locales` 配置数组。若要仅覆盖单次调用，请在选项中传入 `locales`。 * **由 Intl 支持。** 格式化由浏览器原生的 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 处理，因此支持所有标准的 `Intl.NumberFormatOptions`，并会自动应用相应的区域设置惯例。 * **style 要求。** 货币格式化同时需要 `style: 'currency'` 和有效的 `currency` 代码。时间单位格式化同时需要 `style: 'unit'` 和有效的 `unit` 标识符。 ## 参数 [#parameters] | 参数 | 说明 | 类型 | 可选 | 默认值 | | --------------------- | ------------------------------------------------------- | -------- | -- | --- | | [`number`](#number) | 要格式化的数字。 | `number` | 否 | — | | [`options`](#options) | 格式化配置，基于 `Intl.NumberFormatOptions` 扩展，并支持覆盖 `locales`。 | `object` | 是 | — | ### `number` [#number] **类型** `number` · **必填** 要格式化的数字。 ### `options` [#options] **类型** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **可选** 格式化配置。在 `Intl.NumberFormatOptions` 的基础上额外扩展了 `locales` 字段： | 名称 | 描述 | 类型 | 可选 | 默认值 | | -------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -- | -------------- | | `locales` | 覆盖格式化时使用的区域设置。 | `string \| string[]` | 是 | 实例的目标区域设置 | | `style` | 数字格式化样式。 | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | 是 | `'decimal'` | | `currency` | 货币代码 (当 `style` 为 `'currency'` 时必需) 。 | `string` | 是 | — | | `currencyDisplay` | 如何显示货币。 | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | 是 | `'symbol'` | | `currencySign` | 要使用的货币符号样式。 | `'standard' \| 'accounting'` | 是 | `'standard'` | | `unit` | 单位标识符 (当 `style` 为 `'unit'` 时必需) 。 | `string` | 是 | — | | `unitDisplay` | 如何显示单位。 | `'short' \| 'narrow' \| 'long'` | 是 | `'short'` | | `minimumIntegerDigits` | 整数部分的最小位数 (1–21) 。 | `number` | 是 | `1` | | `minimumFractionDigits` | 小数部分的最小位数 (0–20) 。 | `number` | 是 | — | | `maximumFractionDigits` | 小数部分的最大位数 (0–20) 。 | `number` | 是 | — | | `minimumSignificantDigits` | 最少有效数字位数 (1–21) 。 | `number` | 是 | — | | `maximumSignificantDigits` | 最多有效数字位数 (1–21) 。 | `number` | 是 | — | | `useGrouping` | 是否使用分组分隔符。 | `boolean \| 'always' \| 'auto' \| 'min2'` | 是 | `'auto'` | | `notation` | 数字表示法。 | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | 是 | `'standard'` | | `compactDisplay` | 紧凑表示法的显示样式。 | `'short' \| 'long'` | 是 | `'short'` | | `signDisplay` | 何时显示符号。 | `'auto' \| 'never' \| 'always' \| 'exceptZero'` | 是 | `'auto'` | | `roundingMode` | 舍入模式。 | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | 是 | `'halfExpand'` | | `roundingIncrement` | 舍入增量。 | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100` | 是 | `1` | | `trailingZeroDisplay` | 是否显示尾随零。 | `'auto' \| 'stripIfInteger'` | 是 | `'auto'` | ## 返回值 [#returns] **类型** `string` 根据目标区域设置的惯例格式化后的数字。 ## 示例 [#examples] ```typescript 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 // 货币格式化 // 美元格式化 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 // 百分比和科学计数法 // 基本百分比 console.log(gt.formatNum(0.1234, { style: 'percent' })); // Output: "12%" // 带小数位的百分比 console.log(gt.formatNum(0.1234, { style: 'percent', minimumFractionDigits: 1, maximumFractionDigits: 2, })); // Output: "12.34%" // 紧凑表示法 console.log(gt.formatNum(1234567, { notation: 'compact' })); // Output: "1.2M" // 科学计数法 console.log(gt.formatNum(1234567, { notation: 'scientific' })); // Output: "1.235E6" ``` ## 注意事项 [#notes] * 数字格式会自动遵循区域设置中的惯例。 * 该方法使用浏览器原生的 `Intl.NumberFormat`，以确保性能和准确性。 * 货币格式化需要同时提供 `style: 'currency'` 和有效的 `currency` 代码。 * 时间单位格式化需要同时提供 `style: 'unit'` 和有效的 `unit` 标识符。