# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<Currency>`
URL: https://generaltranslation.com/zh/docs/react/reference/components/currency.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 按当前活动的区域设置格式化货币金额。`<Currency>` 组件的 API 参考。

`<Currency>` 组件会将数值渲染为符合当前活动的区域设置的货币格式。它仅负责格式化，不会进行汇率换算。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。*

## 概览 [#overview]

将金额作为子元素传入，并设置 `currency` 代码。

```tsx
<Currency>{100}</Currency>
// 输出：$100.00
```

所有格式化都在本地由 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 处理。

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

* **本地格式化。** 金额会在浏览器中使用 `Intl.NumberFormat` 进行格式化，其值绝不会发送到 General Translation API。
* **不进行转换。** `<Currency>` 会根据所选货币和区域设置格式化货币符号、分组和小数位，但不会在不同货币之间进行换算。
* **区域设置解析。** 默认由当前活动的区域设置决定格式，除非使用 `locales` 覆盖。

## 属性 [#props]

| Prop                    | 描述                      | Type                       | 可选 | 默认值    |
| ----------------------- | ----------------------- | -------------------------- | -- | ------ |
| [`children`](#children) | 要格式化的金额。                | `number \| string`         | 否  | —      |
| [`currency`](#currency) | ISO 4217 货币代码。          | `string`                   | 是  | `USD`  |
| [`options`](#options)   | `Intl.NumberFormat` 选项。 | `Intl.NumberFormatOptions` | 是  | `{}`   |
| [`locales`](#locales)   | 用于格式化的区域设置 (覆盖当前设置) 。   | `string[]`                 | 是  | 当前区域设置 |
| [`name`](#name)         | 该条目的变量名。                | `string`                   | 是  | —      |

### `children` [#children]

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

要格式化为货币的数值。字符串会先解析为数字，再进行格式化。

### `currency` [#currency]

**Type** `string` · **可选** · **默认值** `USD`

ISO 4217 货币代码，例如 `USD` 或 `EUR`。它决定所使用的符号和格式。

### `options` [#options]

**类型** `Intl.NumberFormatOptions` · **可选** · **默认** `{}`

该 prop 接受 [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)。常用选项包括：

| 选项                         | 描述                                           | 类型                                                                                                                   | 可选 | 默认                       |
| -------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -- | ------------------------ |
| `localeMatcher`            | 区域设置匹配算法。                                    | `'lookup' \| 'best fit'`                                                                                             | 是  | `'best fit'`             |
| `numberingSystem`          | 数字系统，例如 `latn` 或 `arab`。                     | `string`                                                                                                             | 是  | `'latn'`                 |
| `style`                    | 数字格式化样式。                                     | `'decimal' \| 'currency' \| 'percent' \| 'unit'`                                                                     | 是  | `'currency'`             |
| `currency`                 | ISO 4217 货币代码。在此处提供时，会覆盖顶层的 `currency` prop。 | `string`                                                                                                             | 是  | `currency` prop          |
| `currencyDisplay`          | 货币的显示方式。                                     | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'`                                                                     | 是  | `'symbol'`               |
| `currencySign`             | 负值采用标准记法还是会计记法。                              | `'standard' \| 'accounting'`                                                                                         | 是  | `'standard'`             |
| `unit`                     | 当 `style` 设为 `'unit'` 时使用的单位标识符。             | `string`                                                                                                             | 是  | —                        |
| `unitDisplay`              | 单位标签的宽度。                                     | `'long' \| 'short' \| 'narrow'`                                                                                      | 是  | `'short'`                |
| `minimumIntegerDigits`     | 最少整数位数；不足时用零补齐。                              | `number` (`1`–`21`)                                                                                                  | 是  | `1`                      |
| `minimumFractionDigits`    | 小数分隔符后的最少位数。                                 | `number` (`0`–`100`)                                                                                                 | 是  | 取决于货币                    |
| `maximumFractionDigits`    | 小数分隔符后的最多位数。                                 | `number` (`0`–`100`)                                                                                                 | 是  | 取决于货币                    |
| `minimumSignificantDigits` | 最少有效数字位数。                                    | `number` (`1`–`21`)                                                                                                  | 是  | `1`                      |
| `maximumSignificantDigits` | 最多有效数字位数。                                    | `number` (`1`–`21`)                                                                                                  | 是  | `21`                     |
| `roundingPriority`         | 小数位数或有效数字位数的优先级。                             | `'auto' \| 'morePrecision' \| 'lessPrecision'`                                                                       | 是  | `'auto'`                 |
| `roundingIncrement`        | 在选定舍入位数上使用的增量。                               | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000`                    | 是  | `1`                      |
| `roundingMode`             | 舍入时采用的方向。                                    | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | 是  | `'halfExpand'`           |
| `trailingZeroDisplay`      | 是否保留整数末尾的零。                                  | `'auto' \| 'stripIfInteger'`                                                                                         | 是  | `'auto'`                 |
| `notation`                 | 标准、科学、工程或紧凑记数法。                              | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`                                                           | 是  | `'standard'`             |
| `compactDisplay`           | 紧凑记数法使用长标签还是短标签。                             | `'short' \| 'long'`                                                                                                  | 是  | `'short'`                |
| `useGrouping`              | 何时显示分组分隔符。                                   | `boolean \| 'always' \| 'auto' \| 'min2'`                                                                            | 是  | `'auto'`；紧凑记数法为 `'min2'` |
| `signDisplay`              | 何时显示正号或负号。                                   | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'`                                                        | 是  | `'auto'`                 |

该组件会先应用 `style: 'currency'`、顶层 `currency` prop 和 `numberingSystem: 'latn'`，再应用 `options`。因此，通过 `options` 提供的值会覆盖这些默认值。

* Currency 的小数位默认值取自该货币标准的最小货币单位。
* `compactDisplay` 仅在 `notation` 为 `'compact'` 时生效。
* `roundingIncrement` 不能与有效数字舍入或值不为 `'auto'` 的 `roundingPriority` 结合使用。
* 支持的单位、编号系统、舍入字段和选项值取决于 JavaScript 运行时。

有关最新可用选项及运行时行为，请参阅 [`Intl.NumberFormat` 选项文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)。

### `locales` [#locales]

**Type** `string[]` · **可选** · **默认值** 当前活动的区域设置

用于格式化的区域设置。省略时，将使用当前活动的区域设置。请参阅 [`locales` 参数](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)。

### `name` [#name]

**类型** `string` · **可选**

货币字段的可选名称，用作元数据。

## 示例 [#examples]

*示例从 `gt-react` 导入；请改为从您所用框架的软件包导入。*

```tsx title="PriceDisplay.tsx"
import { Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return <Currency>{item.price}</Currency>; // [!code highlight]
}
```

```tsx title="PriceDisplay.tsx"
import { Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return <Currency currency="EUR">{item.price}</Currency>; // [!code highlight]
}
```

```tsx title="PriceDisplay.tsx"
import { T, Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return (
    <T>
      The price is <Currency>{item.price}</Currency>. // [!code highlight]
    </T>
  );
}
```

```tsx title="PriceDisplay.tsx"
import { Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return (
    <Currency
      currency="GBP"
      options={{ // [!code highlight]
        currencyDisplay: 'narrowSymbol',
        minimumFractionDigits: 2,
        maximumFractionDigits: 2,
      }}
    >
      {item.price}
    </Currency>
  );
}
```

## 说明 [#notes]

* `<Currency>` 会按照当前区域设置格式化货币数值；它不会在不同货币之间进行换算。
* 它的内容始终在本地格式化，不会发送到 API。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.