# General Translation Platform: formatCurrency
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/formatting/format-currency.mdx
---

title: formatCurrency
description: 在 GT 实例上按区域设置格式化货币值。formatCurrency 的 API 参考。

---

在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，将数值格式化为本地化的货币字符串。General Translation 使用内置的 `Intl.NumberFormat` API 和货币样式，因此金额会按照每种区域设置对应的符号、分组和小数规则正确显示。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `formatCurrency` 方法，并传入一个数值、一个货币代码以及一个可选的选项对象。该方法会返回格式化后的货币字符串。

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

const price = gt.formatCurrency(1234.56, 'USD');
// "$1,234.56"
```

签名：

```typescript
formatCurrency(
  value: number,
  currency: string,
  options?: { locales?: string | string[] } & Intl.NumberFormatOptions
): string
```

*注意：`formatCurrency` 在本地使用 `Intl.NumberFormat` 运行，不需要 API 密钥。默认情况下，它会按实例的目标区域设置进行格式化，并依次回退到源区域设置和库默认值 (`en`) ；传入 `locales` 可覆盖这一行为。如需在没有 `GT` 实例的情况下进行格式化，请参阅独立的 [`formatCurrency`](/docs/platform/core/reference/utility-functions/formatting/format-currency)。*

## 工作方式 [#how-it-works]

* **货币样式。** 格式化由 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 处理，使用 `style: 'currency'` 以及提供的 `currency` 代码。
* **区域设置解析。** 默认情况下，该方法会按实例的目标区域设置进行格式化；如果没有，则依次回退到源区域设置和 library 默认值 (`en`) ——而不是 `locales` 配置数组。可在选项中传入 `locales` 进行覆盖。
* **符号位置。** 货币符号、分组分隔符和小数格式遵循解析后的区域设置，而不是该货币所属国家/地区的规则。

## 参数 [#parameters]

| 参数                      | 描述                                                         | 类型       | 可选 | 默认值 |
| ----------------------- | ---------------------------------------------------------- | -------- | -- | --- |
| [`value`](#value)       | 要格式化的数值。                                                   | `number` | 否  | —   |
| [`currency`](#currency) | ISO 4217 货币代码，例如 `USD` 或 `EUR`。                            | `string` | 否  | —   |
| [`options`](#options)   | 格式化配置，在 `Intl.NumberFormatOptions` 的基础上增加了对 `locales` 的覆盖。 | `object` | 是  | —   |

### `value` [#value]

**Type** `number` · **必填**

要格式化的数字值。

### `currency` [#currency]

**类型** `string` · **必填**

ISO 4217 货币代码，例如 `USD`、`EUR` 或 `JPY`。

### `options` [#options]

**类型** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **可选**

格式化配置。在 `Intl.NumberFormatOptions` 的基础上额外扩展了 `locales` 字段：

| 名称        | 描述               | 类型                   | 可选 | 默认值          |
| --------- | ---------------- | -------------------- | -- | ------------ |
| `locales` | 覆盖格式化时使用的区域设置。   | `string \| string[]` | 是  | 实例的目标区域设置    |
| `style`   | 数字格式化样式；默认为货币格式。 | `string`             | 是  | `'currency'` |

## Returns [#returns]

**Type** `string`

格式化为本地化货币字符串的值。

## 示例 [#examples]

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

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

// 默认实例目标区域设置
console.log(gt.formatCurrency(1234.56, 'USD'));
// 输出: "$1,234.56"

// 逐次调用覆盖区域设置
console.log(gt.formatCurrency(1234.56, 'EUR', { locales: ['de-DE'] }));
// 输出: "1.234,56 €"

// 不显示小数位
console.log(gt.formatCurrency(1234, 'JPY', { locales: ['ja-JP'] }));
// 输出: "￥1,234"
```

## 注意事项 [#notes]

* 该方法底层使用浏览器原生的 `Intl.NumberFormat`，因此金额格式会遵循相应区域设置的惯例。
* 你可以传入任意 `Intl.NumberFormatOptions` (例如 `minimumFractionDigits`) ，并配合 `locales` 一起使用，以微调输出结果。