# gt-next: General Translation Next.js SDK: 货币
URL: https://generaltranslation.com/zh/docs/next/api/components/currency.mdx
---
title: 货币
description: Currency 组件 API 参考
---

{/* 自动生成：请不要直接编辑。请在 content/docs-templates/ 中编辑模板。 */}


## 概述

`<Currency>` 组件会将数值按货币格式渲染。
数字将根据当前 locale 以及传入的可选参数进行格式化。
该组件仅负责格式化，不进行任何汇率换算。

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

所有重新格式化均在本地进行，使用 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 库实现。


## 参考

### Props

<TypeTable
  type={{
    "children?": {
        type: 'any',
        optional: true,
        default: 'undefined',
    },
    "name?": {
        type: 'string',
        optional: true,
        default: 'undefined',
    },
    "value?": {
        decription: '可选值。若未提供，则使用 children 作为 value。',
        type: 'string | number',
        optional: true,
        default: 'undefined',
    },
    "currency?": {
        type: 'string',
        optional: true,
        default: '"USD"',
    },
    "options?": {
        type: 'Intl.NumberFormatOptions',
        optional: true,
        default: '{}',
    },
    "locales?": {
        type: 'string[]',
        optional: true,
        default: 'undefined',
    },
  }}
/>

### 描述

| Prop      | 描述                                                                                                                                            |
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `children`  | 要在组件内部渲染的内容。通常是表示需要格式化为货币的数值。若提供，则优先于 `value` 属性生效。 |
| `name`      | 可选的货币字段名称，用于元数据。                                                                                      |
| `value`     | 货币的默认值。若未提供，则回退至 children。可为字符串或数字。字符串会在格式化前解析为数字。                                  |
| `currency`  | 货币类型，例如“USD”或“EUR”。用于确定货币符号和格式。                                            |
| `options`   | 可选的货币格式化 options，遵循 [`Intl.NumberFormatOptions` 规范](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat)。使用它来定义最大小数位、分组等样式。 |
| `locales`   | 可选的 locales，用于指定格式化所用的 locale。若未提供，将使用用户的默认 locale。关于指定 locales 的更多信息参见[此处](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)。                                            |

### 返回值

一个 `JSX.Element`，其中包含格式化后的货币字符串。

---

## 示例

### 基本示例

`<Currency>` 组件可用于显示本地化的货币金额。

```jsx title="PriceDisplay.jsx" copy
import { Currency } from 'gt-next'; // [!code highlight]

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


### 指定货币

这里我们将价格显示为欧元。

```jsx title="PriceDisplay.jsx" copy
import { Currency } from 'gt-next';

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


### 翻译 Currency 组件

假设你希望在一段也会被翻译的句子中显示货币。
你可以将 `<Currency>` 组件包裹在 `<T>` 组件中。

```jsx title="PriceDisplay.jsx" copy
import { T, Currency } from 'gt-next';

export default function PriceDisplay(item) {
  return (
    <T id="itemPrice"> // [!code highlight]
      价格为 <Currency> {item.price} </Currency>。
    </T> // [!code highlight]
  );
}
```


### 自定义格式

此处我们以 GBP 显示价格，精确指定小数位数，并使用该货币的窄符号（即显示为“$100”而非“US$100”）。
在此阅读 [Intl.NumberFormatOptions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 以了解更多可用选项。

```jsx title="PriceDisplay.jsx" copy
import { Currency } from 'gt-next';

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

***


## 注意事项

* `<Currency>` 组件用于根据当前 `locale` 和传入的可选参数对货币 `value` 进行格式化。
 * 该组件仅负责格式化，不进行任何汇率换算。
 * `<Currency>` 组件的内容不会发送到 API 进行翻译。
   所有重新格式化均在本地通过 [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) 库完成。

## 后续步骤

* 如需了解 `<Currency>` 组件及 `<Num>`、`<DateTime>`、`<Var>` 等其他变量组件的更多详情与使用示例，请参阅 [使用变量组件](/docs/next/guides/variables) 文档。