# General Translation React SDKs (gt-react, gt-next, gt-react-native): URL: https://generaltranslation.com/zh/docs/react/reference/components/currency.mdx --- title: "" description: 按当前活动的区域设置格式化货币金额。 组件的 API 参考。 --- `` 组件会将数值渲染为符合当前活动的区域设置的货币格式。它仅负责格式化，不会进行汇率换算。 *可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。* ## 概览 [#overview] 将金额作为子元素传入，并设置 `currency` 代码。 ```tsx {100} // 输出：$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。 * **不进行转换。** `` 会根据所选货币和区域设置格式化货币符号、分组和小数位，但不会在不同货币之间进行换算。 * **区域设置解析。** 默认由当前活动的区域设置决定格式，除非使用 `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 {item.price}; // [!code highlight] } ``` ```tsx title="PriceDisplay.tsx" import { Currency } from 'gt-react'; export default function PriceDisplay({ item }) { return {item.price}; // [!code highlight] } ``` ```tsx title="PriceDisplay.tsx" import { T, Currency } from 'gt-react'; export default function PriceDisplay({ item }) { return ( The price is {item.price}. // [!code highlight] ); } ``` ```tsx title="PriceDisplay.tsx" import { Currency } from 'gt-react'; export default function PriceDisplay({ item }) { return ( {item.price} ); } ``` ## 说明 [#notes] * `` 会按照当前区域设置格式化货币数值；它不会在不同货币之间进行换算。 * 它的内容始终在本地格式化，不会发送到 API。