# General Translation Platform: formatNum URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-num.mdx Docs index: https://generaltranslation.com/llms.txt Description: 无需 GT 实例即可格式化数字、Currency、百分比和数值。formatNum 的 API 参考。 [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) 是 General Translation 核心库中的一个独立实用函数，用于按照特定区域设置的格式约定来格式化数字。它会为小数、Currency、百分比和时间单位返回符合区域设置的字符串。 ## 概览 [#overview] 直接从 `generaltranslation` 导入 `formatNum`，然后传入要格式化的数字和一个选项对象进行调用。它不需要 API Key 或 [GT](/docs/platform/core/reference/gt-class/constructor) 实例，因此适合在任何需要一次性数字格式化的地方使用。如果要使用会继承实例区域设置的实例格式化，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) 方法。 ```typescript import { formatNum } from 'generaltranslation'; const formatted = formatNum(1234.56, { locales: 'de-DE', style: 'currency', currency: 'EUR', }); // 返回: "1.234,56 €" ``` 签名： ```typescript formatNum( number: number, options?: { locales?: string | string[] } & Intl.NumberFormatOptions ): string ``` ## 工作原理 [#how-it-works] * **底层 API。** 使用与 GT 类方法相同的 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)，因此支持所有标准的 `Intl.NumberFormat` 选项。 * **区域设置解析。** 当 `locales` 是一个数组时，会按顺序尝试各个区域设置，并使用第一个受支持的区域设置。当省略 `locales` 时，会回退到库的默认区域设置 `en`。 * **缓存。** 为了提升重复使用相同区域设置和选项组合时的性能，结果会在内部缓存。 ## 参数 [#parameters] | 参数 | 描述 | Type | 可选 | 默认值 | | --------------------- | ------------------------------------------ | ------------------------------------------------------------- | -- | ---- | | [`number`](#number) | 要格式化的数字。 | `number` | 否 | — | | [`options`](#options) | 格式化配置，包括目标区域设置以及任何 `Intl.NumberFormat` 选项。 | `{ locales?: string \| string[] } & Intl.NumberFormatOptions` | 是 | `{}` | ### `number` [#number] **类型** `number` · **必填** 要格式化的数值。 ### `options` [#options] **类型** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **可选** · **默认值** `{}` 格式化配置。该表列出了已发布的 核心 类型中提供的常用选项及其实际生效的 核心 默认值。 (有关补充的标准和运行时特定详细信息，请参阅 [`Intl.NumberFormat` 构造函数选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)) 。 | 属性 | 描述 | 类型 | 可选 | 默认值 | | -------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -- | ------------------------------------------------- | | `locales` | 用于格式化的区域设置。传入数组时按顺序尝试。 | `string \| string[]` | 是 | `en` | | `localeMatcher` | 区域设置匹配算法。 | `'lookup' \| 'best fit'` | 是 | `'best fit'` | | `numberingSystem` | 数字系统，例如 `latn` 或 `arab`。 | `string` | 是 | `'latn'` | | `style` | 数字格式化样式。 | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | 是 | `'decimal'` | | `currency` | Currency代码 (当 `style` 为 `'currency'` 时必填) 。 | `string` | 是 | — | | `currencyDisplay` | Currency的显示方式。 | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | 是 | `'symbol'` | | `currencySign` | 使用的Currency符号。 | `'standard' \| 'accounting'` | 是 | `'standard'` | | `unit` | 时间单位标识符 (当 `style` 为 `'unit'` 时必填) 。 | `string` | 是 | — | | `unitDisplay` | 时间单位的显示方式。 | `'short' \| 'narrow' \| 'long'` | 是 | `'short'` | | `minimumIntegerDigits` | 最少整数位数 (1–21) 。 | `number` | 是 | `1` | | `minimumFractionDigits` | 最少小数位数 (0–100) 。样式会影响默认值。 | `number` | 是 | 小数和百分比为 `0`；Currency为Currency最小时间单位的小数位数；使用紧凑表示法的默认值时为 `0` | | `maximumFractionDigits` | 最多小数位数 (0–100) 。样式和最小值会影响默认值。 | `number` | 是 | 小数为 `3`；百分比为 `0`；Currency为Currency最小时间单位的小数位数；使用紧凑表示法的默认值时为 `0` | | `minimumSignificantDigits` | 启用有效数字舍入时的最少有效数字位数 (1–21) 。 | `number` | 是 | `1` | | `maximumSignificantDigits` | 启用有效数字舍入时的最多有效数字位数 (1–21) 。 | `number` | 是 | `21`；使用紧凑表示法的默认值时为 `2` | | `roundingPriority` | 小数位和有效数字设置的优先级。 | `'auto' \| 'morePrecision' \| 'lessPrecision'` | 是 | `'auto'`；使用紧凑表示法的默认值时为 `'morePrecision'` | | `notation` | 数字表示法格式。 | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | 是 | `'standard'` | | `compactDisplay` | 紧凑表示法的显示样式。 | `'short' \| 'long'` | 是 | `'short'` | | `useGrouping` | 是否以及何时使用分组分隔符。 | `boolean \| 'always' \| 'auto' \| 'min2'` | 是 | `'auto'`；使用紧凑表示法时为 `'min2'` | | `signDisplay` | 何时显示正负号。 | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | 是 | `'auto'` | | `roundingMode` | 舍入模式。 | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | 是 | `'halfExpand'` | | `roundingIncrement` | 舍入增量。非默认值要求有效的最小和最大小数位数相同，且不能与有效数字舍入或非 `'auto'` 的 `roundingPriority` 一起使用。 | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | 是 | `1` | | `trailingZeroDisplay` | 是否显示末尾的零。 | `'auto' \| 'stripIfInteger'` | 是 | `'auto'` | 当设置 `notation: 'compact'` 且未指定任何小数位或有效数字选项时，实际采用的数字设置默认为 `minimumFractionDigits: 0`、`maximumFractionDigits: 0`、`minimumSignificantDigits: 1` 和 `maximumSignificantDigits: 2`。此时，`roundingPriority` 默认为 `'morePrecision'`，`useGrouping` 默认为 `'min2'`。 ## 返回值 [#returns] **类型** `string` 按区域设置约定格式化的数字。 ## 示例 [#examples] ```typescript import { formatNum } from 'generaltranslation'; // 基本数字格式化 console.log(formatNum(1234.567, { locales: 'en-US' })); // 输出："1,234.567" // 德语格式化 console.log(formatNum(1234.567, { locales: 'de-DE' })); // 输出："1.234,567" ``` ```typescript // 货币格式化 // 美元 console.log(formatNum(1234.56, { locales: 'en-US', style: 'currency', currency: 'USD', })); // 输出: "$1,234.56" // 使用德语区域设置的欧元 console.log(formatNum(1234.56, { locales: 'de-DE', style: 'currency', currency: 'EUR', })); // 输出: "1.234,56 €" // 日元 console.log(formatNum(1234.56, { locales: 'ja-JP', style: 'currency', currency: 'JPY', })); // 输出: "¥1,235" ``` ## 注意事项 [#notes] * 使用与 GT 类方法相同的底层 `Intl.NumberFormat`。 * 为了在重复使用相同区域设置/选项组合时提升性能，结果会缓存在内部。 * 如果主区域设置不受支持，则会按顺序处理后备区域设置。 * 支持所有标准的 `Intl.NumberFormat` 选项。 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.