# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<Num>`
URL: https://generaltranslation.com/zh/docs/react/reference/components/num.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 按当前区域设置格式化数字。`<Num>` 组件的 API 参考。

`<Num>` 组件会按区域设置对数字进行分组和小数格式化。它是一个变量组件，可在 [`<T>`](/docs/react/reference/components/t) 中使用，也可单独使用。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。*

## 概览 [#overview]

将数字作为子元素传入，`<Num>` 会按照当前区域设置进行格式化。

```tsx
<Num>{100}</Num>
// 输出：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` 为每个实例单独覆盖。
* **在 [`<T>`](/docs/react/reference/components/t) 内部。** 在 [`<T>`](/docs/react/reference/components/t) 中使用时，请将每个动态数字都包裹在 `<Num>` 中，这样它会被视为变量，而不是可翻译文本。

## 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 <Num>{item.quantity}</Num>; // [!code highlight]
}
```

```tsx title="CountDisplay.tsx"
import { Num } from 'gt-react';

export default function CountDisplay({ item }) {
  return <Num locales={['fr-FR']}>{item.count}</Num>; // [!code highlight]
}
```

```tsx title="DynamicPriceDisplay.tsx"
import { T, Num } from 'gt-react';

export default function DynamicPriceDisplay({ item }) {
  return (
    <T>
      There are <Num>{item.count}</Num> units available. // [!code highlight]
    </T>
  );
}
```

```tsx title="CustomFormat.tsx"
import { Num } from 'gt-react';

export default function CustomFormat({ number }) {
  return (
    <Num options={{ style: 'decimal', maximumFractionDigits: 2 }}>
      {number}
    </Num>
  );
}
```

## 注意事项 [#notes]

* `<Num>` 会根据当前区域设置对数字进行格式化。
* 在 [`<T>`](/docs/react/reference/components/t) 内，将所有动态数字都包裹在 `<Num>` 中。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.