# 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 参考。 --- 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` · **可选** 格式化配置。下表列出了已发布的 Core 类型中公开的常用货币选项及其实际采用的 Core 默认值。有关补充的标准及运行时特定详细信息，请参阅 [`Intl.NumberFormat` 构造函数选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)。 | 名称 | 描述 | 类型 | 可选 | 默认值 | | -------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -- | -------------------------------------- | | `locales` | 覆盖格式化所用的区域设置。 | `string \| string[]` | 是 | `targetLocale` → `sourceLocale` → `en` | | `localeMatcher` | 区域设置匹配算法。 | `'lookup' \| 'best fit'` | 是 | `'best fit'` | | `numberingSystem` | 数字编号系统，例如 `latn` 或 `arab`。 | `string` | 是 | `'latn'` | | `style` | 数字格式样式。除非显式覆盖，否则 `formatCurrency` 会提供货币样式。 | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | 是 | `'currency'` | | `currency` | 格式化器使用的货币代码。除非显式覆盖，否则位置参数 `currency` 会提供此值。 | `string` | 是 | 位置参数 `currency` | | `currencyDisplay` | 货币的显示方式。 | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | 是 | `'symbol'` | | `currencySign` | 使用的货币符号。 | `'standard' \| 'accounting'` | 是 | `'standard'` | | `unit` | 单位标识符。当 `style` 为 `'unit'` 时必填。 | `string` | 是 | — | | `unitDisplay` | 单位的显示方式。 | `'short' \| 'narrow' \| 'long'` | 是 | `'short'` | | `minimumFractionDigits` | 最小小数位数 (0–100) 。 | `number` | 是 | 货币最小单位的小数位数；使用紧凑默认值时为 `0` | | `maximumFractionDigits` | 最大小数位数 (0–100) ，不得小于 `minimumFractionDigits`。 | `number` | 是 | 货币最小单位的小数位数；使用紧凑默认值时为 `0` | | `minimumSignificantDigits` | 启用有效数字舍入时的最小有效数字位数 (1–21) 。 | `number` | 是 | `1` | | `maximumSignificantDigits` | 启用有效数字舍入时的最大有效数字位数 (1–21) 。 | `number` | 是 | `21`；使用紧凑默认值时为 `2` | | `roundingPriority` | 小数位和有效数字设置的优先级关系。 | `'auto' \| 'morePrecision' \| 'lessPrecision'` | 是 | `'auto'`；使用紧凑默认值时为 `'morePrecision'` | | `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` | | `useGrouping` | 是否以及何时使用分组分隔符。 | `boolean \| 'always' \| 'auto' \| 'min2'` | 是 | `'auto'`；使用紧凑默认值时为 `'min2'` | | `notation` | 数字表示法。 | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | 是 | `'standard'` | | `compactDisplay` | 紧凑表示法的显示样式。 | `'short' \| 'long'` | 是 | `'short'` | | `signDisplay` | 符号的显示时机。 | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | 是 | `'auto'` | | `trailingZeroDisplay` | 是否显示尾随零。 | `'auto' \| 'stripIfInteger'` | 是 | `'auto'` | 当设置 `notation: 'compact'` 且未指定任何小数位数或有效数字选项时，实际生效的数字默认值为 `minimumFractionDigits: 0`、`maximumFractionDigits: 0`、`minimumSignificantDigits: 1` 和 `maximumSignificantDigits: 2`。此时，`roundingPriority` 默认为 `'morePrecision'`，`useGrouping` 默认为 `'min2'`。设置 `style: 'unit'` 时，还必须提供有效的 `unit`。 ## 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` 一起使用，以微调输出结果。