# Vue: `<Num>`
URL: https://generaltranslation.com/zh/docs/vue/reference/components/num.mdx
Docs index: https://generaltranslation.com/llms.txt
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'`     |
| `currencySign`             | 负值货币的标准表示法或会计表示法。                                                                          | `'standard' \| 'accounting'`                                                                                         | 是  | `'standard'`   |
| `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 \| 'auto' \| 'always' \| 'min2'`                                                                            | 是  | 取决于表示法         |
| `notation`                 | 数字表示法。                                                                                     | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`                                                           | 是  | `'standard'`   |
| `compactDisplay`           | 紧凑表示法标签的宽度。                                                                                | `'short' \| 'long'`                                                                                                  | 是  | `'short'`      |
| `signDisplay`              | 何时显示正负号。                                                                                   | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'`                                                        | 是  | `'auto'`       |
| `roundingMode`             | 舍入时采用的方向。                                                                                  | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | 是  | `'halfExpand'` |
| `roundingPriority`         | 解决小数位数设置与有效数字位数设置之间的冲突。                                                                    | `'auto' \| 'morePrecision' \| 'lessPrecision'`                                                                       | 是  | `'auto'`       |
| `roundingIncrement`        | 舍入到 `1`、`2`、`5`、`10`、`20`、`25`、`50`、`100`、`200`、`250`、`500`、`1000`、`2000`、`2500` 或 `5000`。 | `number`                                                                                                             | 是  | `1`            |
| `trailingZeroDisplay`      | 控制整数值上的尾随零。                                                                                | `'auto' \| 'stripIfInteger'`                                                                                         | 是  | `'auto'`       |

小数位数的默认值取决于所选的 `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>
```

## Sitemap

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