# generaltranslation: General Translation Core SDK: formatNum
URL: https://generaltranslation.com/zh/docs/core/class/methods/formatting/format-num.mdx
---
title: formatNum
description: 用于按区域设置惯例格式化数字的 formatNum 方法 API 参考
---

## 概述

`formatNum` 方法使用 Internationalization API 按照特定区域设置的约定来格式化数字。
它会根据目标区域设置自动处理小数分隔符、千位分隔符和数字系统。

```typescript
const gt = new GT({ targetLocale: 'de' });

const formatted = gt.formatNum(1234.56, {
  style: 'decimal',
  minimumFractionDigits: 2
});
// 返回："1.234,56"（德语数字格式）
```


## 参考文档

### 参数

| 名称         | 类型                    | 描述        |
| ---------- | --------------------- | --------- |
| `number`   | `number`              | 要进行格式化的数字 |
| `options?` | `NumberFormatOptions` | 可选的格式化选项  |

### NumberFormatOptions

在 `Intl.NumberFormatOptions` 的基础上扩展，增加了额外的区域设置选项：

| Name                        | Type                                                                                                                 | Description                        |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `locales?`                  | `string \| string[]`                                                                                                 | 覆盖用于格式化的 locales (默认为实例的 locales)  |
| `style?`                    | `'decimal' \| 'currency' \| 'percent' \| 'unit'`                                                                     | 数字格式化样式                            |
| `currency?`                 | `string`                                                                                                             | 货币代码 (当样式为 `'currency'` 时必填)       |
| `currencyDisplay?`          | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'`                                                                     | 货币的显示方式                            |
| `currencySign?`             | `'standard' \| 'accounting'`                                                                                         | 使用的货币符号格式                          |
| `unit?`                     | `string`                                                                                                             | 单位标识符 (当样式为 `'unit'` 时必填)          |
| `unitDisplay?`              | `'short' \| 'narrow' \| 'long'`                                                                                      | 单位的显示方式                            |
| `minimumIntegerDigits?`     | `number`                                                                                                             | 整数部分的最少位数 (1-21)                   |
| `minimumFractionDigits?`    | `number`                                                                                                             | 小数部分的最少位数 (0-20)                   |
| `maximumFractionDigits?`    | `number`                                                                                                             | 小数部分的最多位数 (0-20)                   |
| `minimumSignificantDigits?` | `number`                                                                                                             | 最少有效数字位数 (1-21)                    |
| `maximumSignificantDigits?` | `number`                                                                                                             | 最多有效数字位数 (1-21)                    |
| `useGrouping?`              | `boolean \| 'always' \| 'auto' \| 'min2'`                                                                            | 是否使用分组分隔符                          |
| `notation?`                 | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`                                                           | 数字记数法格式                            |
| `compactDisplay?`           | `'short' \| 'long'`                                                                                                  | 紧凑记数法的显示样式                         |
| `signDisplay?`              | `'auto' \| 'never' \| 'always' \| 'exceptZero'`                                                                      | 何时显示正负号                            |
| `roundingMode?`             | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | 舍入模式                               |
| `roundingIncrement?`        | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100`                                                                         | 舍入增量                               |
| `trailingZeroDisplay?`      | `'auto' \| 'stripIfInteger'`                                                                                         | 是否显示末尾的零                           |

### 返回值

`string` - 按区域设置约定格式化后的数字字符串。

***

## 示例

### 基础数字格式化

```typescript copy
import { GT } from 'generaltranslation';

const gt = new GT({ targetLocale: 'en-US' });

// 基本小数格式化
console.log(gt.formatNum(1234.567));
// Output: "1,234.567"

// 德语区域设置格式化
console.log(gt.formatNum(1234.567, { locales: 'de-DE' }));
// Output: "1.234,567"

// 法语区域设置格式化  
console.log(gt.formatNum(1234.567, { locales: 'fr-FR' }));
// Output: "1 234,567"
```


### 货币格式化

```typescript copy
// 美元格式化
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD'
}));
// 输出："$1,234.56"

// 使用德语区域设置的欧元格式化
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'EUR',
  locales: 'de-DE'
}));
// 输出："1.234,56 €"

// 货币显示选项
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code'
}));
// 输出："USD 1,234.56"

// 会计格式（负数用括号表示）
console.log(gt.formatNum(-1234.56, {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting'
}));
// 输出："($1,234.56)"
```


### 百分比和科学记数法

```typescript copy
// 基本百分比
console.log(gt.formatNum(0.1234, { style: 'percent' }));
// 输出："12%"

// 带小数位的百分比
console.log(gt.formatNum(0.1234, {
  style: 'percent',
  minimumFractionDigits: 1,
  maximumFractionDigits: 2
}));
// 输出："12.34%"

// 紧凑记数法
console.log(gt.formatNum(1234567, { notation: 'compact' }));
// 输出："1.2M"

// 科学记数法
console.log(gt.formatNum(1234567, { notation: 'scientific' }));
// 输出："1.235E6"
```

***


## 注意事项

* 数字格式会自动遵循区域设置的惯例
* 该方法使用浏览器原生的 `Intl.NumberFormat`，以获得最佳性能和准确性
* 货币格式化同时需要设置 `style: 'currency'` 并提供有效的 `currency` 代码
* 单位格式化同时需要设置 `style: 'unit'` 并提供有效的 `unit` 标识符

## 后续步骤

* 查阅 [`Intl.NumberFormat` 文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)，了解更多选项
* 参见 [`format-message`](/docs/core/class/methods/formatting/format-message)，了解如何进行带数字插值的消息格式化
* 参见独立的 [`format-num`](/docs/core/functions/formatting/format-num)，了解如何在不创建 GT 实例的情况下使用
* 参见 [`get-locale-properties`](/docs/core/class/methods/locales/get-locale-properties)，了解区域设置特定的格式化信息