# vue: <Currency>
URL: https://generaltranslation.com/zh/docs/vue/reference/components/currency.mdx
---

title: "<Currency>"
description: 根据当前区域设置格式化 Currency金额。<Currency> 组件的 API 参考。

---

`<Currency>` 组件使用 `Intl.NumberFormat` 的 Currency `style` 格式格式化必填的数字 `value`。它只会更改显示格式，不会在不同 Currency之间换算金额。

## 概述 [#overview]

通过 `value` 绑定金额，并可选择指定 ISO 4217 Currency代码：

```vue
<Currency :value="100" currency="EUR" />
<!-- en-US：€100.00 -->
```

可单独使用，也可在 [`<T>`](/docs/vue/reference/components/t) 中作为运行时变量使用。

## 工作原理 [#how-it-works]

* 数字会按本地 Currency `style` 格式化。金额不会被翻译，也不会发送进行 Currency换算。
* 字符串必须完整表示一个数字。仅包含空白字符的字符串和 `null` 会渲染为空；无效的数字字符串会原样渲染。
* `currency` 默认为 `USD`。组件会在合并 `options` 后始终应用顶层的 `currency` prop 和 Currency `style`，因此 `options.currency` 和 `options.style` 无法覆盖它们。
* 格式化器槽位中的子元素会被忽略。请始终提供 `value`，并使用自闭合标签。
* 该组件不会添加任何 HTML 包装元素。

### 区域设置解析

当当前区域设置为配置的默认区域设置时，格式化仅使用该默认区域设置，并忽略 `locales`。对于其他任何当前区域设置，独立格式化器会依次尝试显式指定的 `locales`、当前区域设置和默认区域设置。

在 [`<T>`](/docs/vue/reference/components/t) 中，源后备内容使用默认区域设置。已翻译内容会依次尝试当前区域设置和默认区域设置，并忽略显式指定的 `locales` prop。

## 属性 [#props]

| 属性                      | 说明                          | 类型                         | 可选 | 默认值      |
| ----------------------- | --------------------------- | -------------------------- | -- | -------- |
| [`value`](#value)       | 要格式化的 Currency金额。                  | `number \| string \| null` | 否  | —        |
| [`currency`](#currency) | ISO 4217 Currency代码。              | `string`                   | 是  | `USD`    |
| [`options`](#options)   | 额外的 `Intl.NumberFormat` 选项。 | `Intl.NumberFormatOptions` | 是  | `{}`     |
| [`locales`](#locales)   | 首选的格式化区域设置。                 | `string[]`                 | 是  | 区域设置解析顺序 |

### `value`

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

要格式化的完整数值。数字字符串会在格式化前通过 `Number()` 转换。该值保持为所选 Currency，不会应用汇率。

### `currency`

**类型** `string` · **可选** · **默认值** `USD`

ISO 4217 Currency代码，例如 `USD`、`EUR` 或 `JPY`。即使 `options` 中包含不同的 `currency` 字段，此 prop 仍会指定 Currency。

### `options`

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

其他选项会传递给 `Intl.NumberFormat`。常见的 Currency格式化选项包括：

| 选项                         | 描述                       | 类型                                                            | 可选 | 默认值          |
| -------------------------- | ------------------------ | ------------------------------------------------------------- | -- | ------------ |
| `localeMatcher`            | 区域设置匹配算法。                | `'lookup' \| 'best fit'`                                      | 是  | `'best fit'` |
| `numberingSystem`          | 数字系统，例如 `latn` 或 `arab`。 | `string`                                                      | 是  | 取决于区域设置      |
| `currencyDisplay`          | Currency的显示方式。                 | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'`              | 是  | `'symbol'`   |
| `currencySign`             | 负值使用标准记法还是会计记法。          | `'standard' \| 'accounting'`                                  | 是  | `'standard'` |
| `minimumIntegerDigits`     | 最少整数位数。                  | `number`                                                      | 是  | `1`          |
| `minimumFractionDigits`    | 最少小数位数。                  | `number`                                                      | 是  | 取决于Currency        |
| `maximumFractionDigits`    | 最多小数位数。                  | `number`                                                      | 是  | 取决于Currency        |
| `minimumSignificantDigits` | 最少有效数字位数。                | `number`                                                      | 是  | `1`          |
| `maximumSignificantDigits` | 最多有效数字位数。                | `number`                                                      | 是  | `21`         |
| `useGrouping`              | 何时显示分组分隔符。               | `boolean \| string`                                           | 是  | 取决于记法        |
| `notation`                 | 数字记法。                    | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`    | 是  | `'standard'` |
| `compactDisplay`           | 紧凑记法标签的长度。               | `'short' \| 'long'`                                           | 是  | `'short'`    |
| `signDisplay`              | 何时显示正负号。                 | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'` | 是  | `'auto'`     |
| `roundingMode`             | 舍入时采用的方向。                | `string`                                                      | 是  | 取决于运行时       |

该组件会强制使用 `style: 'currency'` 和顶层的 `currency` 值。Currency小数位数的默认值遵循该Currency标准的辅币单位。有关由运行时定义的完整选项集，请参阅 [`Intl.NumberFormat` 选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)。

### `locales`

**类型** `string[]` · **可选** · **默认值** 区域设置解析顺序

用于独立格式化的首选 BCP 47 区域设置代码。仅当当前区域设置不是配置的默认区域设置时，才会优先于当前和默认区域设置尝试这些代码。

## 示例 [#examples]

```vue title="OrderTotal.vue"
<script setup lang="ts">
import { Currency, T } from 'gt-vue';

defineProps<{ total: number }>();
</script>

<template>
  <T>
    Your total is
    <Currency
      :value="total"
      currency="EUR"
      :options="{ currencyDisplay: 'code' }"
    />.
  </T>
</template>
```