# General Translation React SDKs (gt-react, gt-next, gt-react-native): URL: https://generaltranslation.com/zh/docs/react/reference/components/num.mdx --- title: "" description: 按当前区域设置格式化数字。 组件的 API 参考。 --- `` 组件会按区域设置对数字进行分组和小数格式化。它是一个变量组件，可在 [``](/docs/react/reference/components/t) 中使用，也可单独使用。 *可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。* ## 概览 [#overview] 将数字作为子元素传入，`` 会按照当前区域设置进行格式化。 ```tsx {100} // 输出：100 ``` 所有格式化都在本地使用 [`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` 为每个实例单独覆盖。 * **在 [``](/docs/react/reference/components/t) 内部。** 在 [``](/docs/react/reference/components/t) 中使用时，请将每个动态数字都包裹在 `` 中，这样它会被视为变量，而不是可翻译文本。 ## Props [#props] | Prop | 描述 | Type | 可选 | 默认值 | | ----------------------- | ----------------------- | -------------------------- | -- | ------ | | [`children`](#children) | 要格式化的数字。 | `number \| string` | 否 | — | | [`options`](#options) | `Intl.NumberFormat` 选项。 | `Intl.NumberFormatOptions` | 是 | `{}` | | [`locales`](#locales) | 用于覆盖格式化时所用的区域设置。 | `string[]` | 是 | 当前区域设置 | | [`name`](#name) | 条目的变量名。 | `string` | 是 | — | ### `children` [#children] **类型** `number | string` · **必填** 要格式化的数值。字符串会在格式化前先解析为数字。 ### `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'` | 是 | `'decimal'` | | `currency` | ISO 4217 货币代码。当 `style` 为 `'currency'` 时必填。 | `string` | 是 | — | | `currencyDisplay` | 货币的显示方式。 | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'` | 是 | `'symbol'` | | `currencySign` | 负货币值采用标准或会计记法。 | `'standard' \| 'accounting'` | 是 | `'standard'` | | `unit` | 单位标识符，例如 `kilometer` 或 `megabyte`。当 `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`；对于货币，还取决于该货币的标准辅币单位。 * `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] **类型** `string[]` · **可选** · **默认值** 当前区域设置 用于格式化的区域设置。省略时，将使用当前区域设置。请参阅 [locales 参数](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)。 ### `name` [#name] **类型** `string` · **可选** 数字字段的可选名称，用作元数据。 ## 示例 [#examples] *示例中从 `gt-react` 导入；请改为从你的框架对应的 package 导入。* ```tsx title="QuantityDisplay.tsx" import { Num } from 'gt-react'; export default function Inventory({ item }) { return {item.quantity}; // [!code highlight] } ``` ```tsx title="CountDisplay.tsx" import { Num } from 'gt-react'; export default function CountDisplay({ item }) { return {item.count}; // [!code highlight] } ``` ```tsx title="DynamicPriceDisplay.tsx" import { T, Num } from 'gt-react'; export default function DynamicPriceDisplay({ item }) { return ( There are {item.count} units available. // [!code highlight] ); } ``` ```tsx title="CustomFormat.tsx" import { Num } from 'gt-react'; export default function CustomFormat({ number }) { return ( {number} ); } ``` ## 注意事项 [#notes] * `` 会根据当前区域设置对数字进行格式化。 * 在 [``](/docs/react/reference/components/t) 内，将所有动态数字都包裹在 `` 中。