# General Translation Platform: formatNum
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-num.mdx
---

title: formatNum
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` · **可选** · **默认值** `{}`

格式化配置。除了 `locales` 之外，还接受 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 的任意选项。最常用的字段：

| 属性                      | 描述                                    | 类型                                                         | 可选 | 默认值          |
| ----------------------- | ------------------------------------- | ---------------------------------------------------------- | -- | ------------ |
| `locales`               | 用于格式化的区域设置。传入数组时会按顺序依次尝试。             | `string \| string[]`                                       | 是  | `en`         |
| `style`                 | 数字格式化样式。                              | `'decimal' \| 'currency' \| 'percent' \| 'unit'`           | 是  | `'decimal'`  |
| `currency`              | 货币代码 (当 `style` 为 `'currency'` 时必需) 。 | `string`                                                   | 是  | —            |
| `minimumIntegerDigits`  | 整数部分的最小位数 (1–21) 。                    | `number`                                                   | 是  | —            |
| `minimumFractionDigits` | 小数部分的最小位数 (0–20) 。                    | `number`                                                   | 是  | —            |
| `maximumFractionDigits` | 小数部分的最大位数 (0–20) 。                    | `number`                                                   | 是  | —            |
| `useGrouping`           | 是否使用分组分隔符。                            | `boolean \| 'always' \| 'auto' \| 'min2'`                  | 是  | `'auto'`     |
| `notation`              | 数字表示法。                                | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | 是  | `'standard'` |

## 返回值 [#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` 选项。