# General Translation React SDKs (gt-react, gt-next): Currency
URL: https://generaltranslation.com/zh/docs/react/reference/components/currency.mdx
---

title: Currency
description: 使用 General Translation gt-react 按当前区域设置格式化货币金额。Currency 的 API 参考。

---

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

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。示例从 `gt-react` 导入；请改为从你所用框架对应的包中导入。*

## 概览 [#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]

**Type** `Intl.NumberFormatOptions` · **可选** · **默认值** `{}`

遵循 [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 规范的格式化选项，例如 `currencyDisplay` 和小数位数的限制。

### `locales` [#locales]

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

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

### `name` [#name]

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

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

## 示例 [#examples]

```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。