# vue: <Num>
URL: https://generaltranslation.com/zh/docs/vue/reference/components/num.mdx
---
title: "<Num>"
description: 按活动区域设置格式化数字。<Num> 组件的 API 参考。

---

`<Num>` 组件使用 `Intl.NumberFormat` 格式化必填的数值 `value`。它既可单独使用，也可作为 [`<T>`](/docs/vue/reference/components/t) 中的运行时变量。

## 概述 [#overview]

通过 `value` 绑定数字，并保持组件采用自闭合形式：

```vue
<Num :value="1234.5" />
<!-- en-US：1,234.5 -->
```

格式化在本地进行。数值不会被翻译，也不会包含在富文本翻译源内容中。

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

* 数字会直接传给 `Intl.NumberFormat`。
* 字符串必须表示一个完整的数字。仅含空白字符的字符串和 `null` 会渲染为空；无效的数字字符串会原样渲染。
* 格式化组件插槽中的子元素会被忽略。请始终提供 `value` 并使用自闭合标签。
* 该组件不会添加任何 HTML 包装元素。

### 区域设置解析

当活动区域设置为配置的默认区域设置时，格式化只使用该默认区域设置，并忽略 `locales`。对于其他任何活动区域设置，独立格式化器会依次尝试显式指定的 `locales`、活动区域设置和默认区域设置。重复的区域设置会被移除，但原有顺序不变。

在 [`<T>`](/docs/vue/reference/components/t) 中，富文本翻译会控制格式化：源后备内容使用默认区域设置，而翻译后的内容会依次尝试活动区域设置和默认区域设置。在这种情况下，会忽略显式指定的 `locales` prop。

## 属性 [#props]

| 属性                    | 描述                           | 类型                         | 可选 | 默认值      |
| --------------------- | ---------------------------- | -------------------------- | -- | -------- |
| [`value`](#value)     | 要格式化的数值。                     | `number \| string \| null` | 否  | —        |
| [`options`](#options) | 传递给 `Intl.NumberFormat` 的选项。 | `Intl.NumberFormatOptions` | 是  | `{}`     |
| [`locales`](#locales) | 首选的格式化区域设置。                  | `string[]`                 | 是  | 区域设置解析顺序 |

### `value`

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

要格式化的完整数值。数字字符串会先通过 `Number()` 转换，再进行格式化。`"12 items"` 或 `"1,234.5"` 等值不会被部分解析，而会原样渲染。

```vue
<Num :value="item.quantity" />
```

### `options`

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

传递给 JavaScript 运行时 `Intl.NumberFormat` 实现的选项。常见选项包括：

| 选项                         | 描述                                  | 类型                                                            | 可选 | 默认值          |
| -------------------------- | ----------------------------------- | ------------------------------------------------------------- | -- | ------------ |
| `localeMatcher`            | 区域设置匹配算法。                           | `'lookup' \| 'best fit'`                                      | 是  | `'best fit'` |
| `numberingSystem`          | 数字系统，例如 `latn` 或 `arab`。            | `string`                                                      | 是  | 取决于区域设置      |
| `style`                    | 十进制、百分比、货币或单位格式。                    | `'decimal' \| 'percent' \| 'currency' \| 'unit'`              | 是  | `'decimal'`  |
| `currency`                 | 货币 `style` 所需的 ISO 4217 代码。         | `string`                                                      | 是  | —            |
| `currencyDisplay`          | 货币的显示方式。                            | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'`              | 是  | `'symbol'`   |
| `unit`                     | 单位 `style` 所需的单位标识符，例如 `kilometer`。 | `string`                                                      | 是  | —            |
| `unitDisplay`              | 单位标签的宽度。                            | `'long' \| 'short' \| 'narrow'`                               | 是  | `'short'`    |
| `minimumIntegerDigits`     | 最少整数位数。                             | `number`                                                      | 是  | `1`          |
| `minimumFractionDigits`    | 最少小数位数。                             | `number`                                                      | 是  | 取决于 `style`  |
| `maximumFractionDigits`    | 最大小数位数。                             | `number`                                                      | 是  | 取决于 `style`  |
| `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`。支持的字段和值也可能因 JavaScript 运行时而异。有关完整的运行时定义选项集，请参阅 [`Intl.NumberFormat` 选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options)。

### `locales`

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

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

```vue
<Num :value="1234.5" :locales="['de-DE']" />
```

## 示例 [#examples]

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

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

<template>
  <T>There are <Num :value="count" /> units available.</T>
  <p><Num :value="completionRate" :options="{ style: 'percent' }" /> complete</p>
</template>
```