# @automattic/number-formatters 中文文档

规范地址：https://npmcn.com/package/%40automattic/number-formatters/

版本：1\.3\.0
npm 元数据更新时间：2026-11-06T18:39:19.416Z
中文译文更新时间：2026-11-07T06:57:42.297Z
软件包许可：GPL-2\.0-or-later

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40automattic/number-formatters
原文对照：https://npmcn.com/package/%40automattic/number-formatters/?lang=original
项目主页：https://github.com/Automattic/jetpack/tree/HEAD/projects/js-packages/number-formatters/#readme
源码仓库：https://github.com/Automattic/number-formatters

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：171 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-04-07T11:34:28.945Z
- 最新版本发布：2026-11-02T18:06:45.514Z
- 近 30 天下载量：64560（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 29 个）

## 中文简介

公用事业的格式

## 安装

```sh
npm install @automattic/number-formatters
```

也可以使用：`pnpm add @automattic/number-formatters`、`yarn add @automattic/number-formatters`、`bun add @automattic/number-formatters`

## README

# 数字格式

JavaScript/TypeScript应用程序中格式化编号的公用工具集合.

## 使用量

在内部,软件包要求一个用于格式化数字(平面),货币,紧凑数字等格式化方法的前置关闭/构件. 关闭处理地处地州.

```typescript
import { setLocale, formatNumber } from '@automattic/number-formatters';

setLocale( 'de' ); // See notes below about locale state
formatNumber( 1000 ); // Returns "1.000"

setLocale( 'en' );
formatNumber( 1000 ); // Returns "1,000"
```

在未来的版本中,我们可能会揭露那些接受一种 `locale` 参数代替。 见 `Dev/Setup` 注释如下.

### 注释: 本地状态 / `setLocale`

包输出 a `setLocale` 方法(见下文"方法"),它允许设置用于将数字定位的地方变量。 默认值有一个后退链,这可能足以满足许多情况(因此不需要在代码中手动设置) `setLocale`) (中文(简体) ). 后退地被定义为:

1.  当前 WordPress 用户语言,如果通过 `@wordpress/date` 设置( 假设在 WordPress 上下文中运行) 。 请注意,这源于 **用户设置**,不是网站的.
2.  浏览器的用地,如果通过 `window.navigator.language`
3.  内部回落方位常数( q)`en` - 可以切换到 `en-US`(中文(简体) )

如果通过调用设置到 `setLocale`那么这显然将优先.

## 方法

如下所述各种TS类型,见我们 [类型定义](https://npmcn.com/package/%40automattic/number-formatters/src/types.ts)。 。 。 .

### 创建数字格式

```typescript
createNumberFormatters(): NumberFormatters
```

以下列所有方法返回实例/对象的主要工厂方法。 大部分情况下,称这个是没有必要的,因为软件包已经创建了默认物. 如果消费者需要更多的控制,例如多例用于单独处理当地国家处理的地物,将是有益的.

### 格式( )

```typescript
formatNumber(
    number: number,
    options?: Omit< NumberFormatParams, 'browserSafeLocale' >
): string;

```

这个 `formatNumber` 方法用于使用已装入的地语设置(即特定地语千和小数分隔符)格式化数字。 您通过数字(整数或浮点数)和(可选择的)您想要的小数位数(或一个选项对象),然后返回一个字符串,其格式符合当前装入的地块。 如果有必要,您还可以将第二个参数扩展为带有您想要覆盖的属性的对象,从而覆盖特定数字的语言设置.

#### 实例

```typescript
// These examples assume a 'de' (German) locale to demonstrate
formatNumber( 2500.25 ); // '2.500'
formatNumber( 2500.33, { decimals: 3 } ); // '2.500,330'
```

### 格式 编号 契约 ()

`formatNumberCompact` 将使用带有小数点1的紧凑符号格式化和本地化数字,如1K、1.5M等。 它的工作原理与 `formatNumber` (同数与辩相.

### 格式紧迫( C)

```typescript
formatCurrency(
    number: number,
    currency: string,
    options: FormatCurrencyOptions = {}
): string
```

使用给定的货币代码格式化货币.

货币将定义用于这种格式化的属性,但这些属性可以使用选项被覆盖. 这样做要小心.

对于包括小数的货币,这总能将包含小数的金额还原出,即使这些小数是零. 要排除零,请使用 `stripZeros` 选项。 例如,该函数通常会格式化 `10.00` 内 `USD` 作为 `$10.00` 但是,当这个选项是真的, 它会返回 `$10` 换句话说.

由于四舍五入误差在浮动点数学中很常见,因此有时会以货币最小单位的整数(如:美元一分钱或日元一分钱)提供价格. 设定 `isSmallestUnit` 来更改函数以在整数上运行。 如果此选项没有设置或错误, 函数将格式化该金额 `1025` 内 `USD` 作为 `$1,025.00`,但当选项是真实的, 它会返回 `$10.25` 换句话说.

要显示一个固定的十进制数而不是货币本身的(例如:商店的价格小数设置),通过 `decimals`数字 : `formatCurrency( 92, 'USD', { decimals: 0 } )` 返回时 `$92`,以及 `formatCurrency( 92, 'JPY', { decimals: 2 } )` 返回时 `¥92.00`。它需要从 0 到 20 的整数,而忽略了其他任何东西,它不会改变 `isSmallestUnit` 除以数量. `getCurrencyObject()` 选择相同.

#### 页:1

-   我们总是显示 `US$` 当用户的地理位置不在美国境内时, 这一点很重要,因为其他货币使用 `$` 对于它们的货币,有时感到惊讶,如果它们实际上以美元计费(这是许多用户的违约)。 我们无法安全展示 `US$` 对每个人来说,因为我们发现美国用户 被这种风格所迷惑 并降低了对产品的信心.
-   从货币最小单位格式化货币的选项(如:美元分,日元分). 这一点很重要,因为用代码中浮点数进行价格数学会产生出乎意料的四舍五入错误,所以大多数货币金额应该作为整数提供并被操纵.

### 获取当前对象( )

这是一种可选的API,可以分别返回价格中格式化的片段,因此消费者可以决定如何最好地制作出(例如:这用于将不同的HTML标记以价格和货币符号来包装). 联合来文已经将这一特征列为: `Intl.NumberFormat.formatToParts()` 但是,我们的API还必须包括这里列出的其他特征以及货币符号位置等额外信息(数字之前或之后).

```typescript
getCurrencyObject(
    number: number,
    currency: string,
    options: FormatCurrencyOptions = {}
): CurrencyObject
```

返回格式化的价格对象。 有关该对象属性的详情,见下文.

货币将定义用于这种格式化的属性,但这些属性可以使用选项被覆盖. 这样做要小心.

对于包括小数的货币,这总能将包含小数的金额还原出,即使这些小数是零. 要排除零,请使用 `stripZeros` 选项。 例如,该函数通常会格式化 `10.00` 内 `USD` 作为 `$10.00` 但是,当这个选项是真的, 它会返回 `$10` 换句话说 或者,你可以使用 `hasNonZeroFraction` 返回值以决定是否显示小数节.

由于四舍五入误差在浮动点数学中很常见,因此有时会以货币最小单位的整数(如:美元一分钱或日元一分钱)提供价格. 设定 `isSmallestUnit` 来更改函数以在整数上运行。 如果此选项没有设置或错误, 函数将格式化该金额 `1025` 内 `USD` 作为 `$1,025.00`,但当选项是真实的, 它会返回 `$10.25` 换句话说.

### 设置本地( C)

```typescript
setLocale( locale: string ): void
```

一个函数,可用于设置默认的地块,供各种格式化者使用.

### 设置GeoLocation ()

```typescript
setGeoLocation( geoLocation: string ): void
```

默认情况下,USD的货币符号将基于地籍(不同于使用硬编码的首字母列表的其他货币代码) `en-US`编号 :`en` 这将是 `$` 对于其他所有的地方来说 `US$`然而,如果地理定位确定该国不在美国境内,则美元符号为: `US$` 不论地方。 这是为了防止非美国国家使用英语地语的用户产生混淆.

在美国,用户会看到美元价格用货币符号表示 `$`然而,还有许多其他货币使用 `$` 作为其货币符号(例如: `CAD`) (中文(简体) ). 此套件试图防止这些符号之间的混淆,在地语不匹配货币时使用国际版本的符号. 所以如果你的地址是 `en-CA`,美元价格将随文号而产生 `US$`。 。 。 .

然而,这取决于用户是否将其界面语言设定为非 `en-US`编号 :`en`,许多说英语的非美国用户仍然有这种界面语言(例如:我们的设置中没有可供阿根廷英语使用的英语语言),因此这些用户很可能仍然有 `en`) (中文(简体) ). 因此,这些用户将看到一个价格 `$` 并且可能会被误导 关于什么货币正在显示。 设置 `geoLocation` 帮助通过显示来防止这种情况发生 `US$` 这些用户.

关于实际用法,参见wp-calypso monorepo.

## 德维

### 设置

我们试图保持类似的功能分离 与 `Intl.NumberFormat( ... ).format( ... )`数字 :

```
src/
├── number-format-currency/index.ts
├── number-format.ts { numberformat, numberFormatCompact }
```

-   它们带回缓存实例 `Intl.NumberFormat()`
-   单项出口,需要 `locale` 作为参数通过(我们目前不导出这些参数,但我们可以下行)
-   以上情况还不是 `number-format-currency`。它返回格式化编号,所以基本上是一个完整的 `Intl.NumberFormat( ... ).format( ... )` 电话 它可能会收到一个重新同步到下行的功能,希望这能改善一些代码共享

```
src/
├── create-number-formatters.ts { formatNumber, formatNumberCompact, formatCurrency, etc.}
```

-   关闭处理 `locale` 状态,在数字格式化器上返回抽象,称为 `formatNumber`, (中文(简体) ), `formatNumberCompact`等 (中文(简体) ).
-   方法接受参数化基本格式化参数的参数,并允许方便于通用(例如方便) `decimals` 圆柱形)

在混音中添加一个新的前题, 说"格式百分比", 基本上只是重复我们为“ compact” 数字所做的: 一个方法从 `create-number-formatters.ts` 函数在 `number-format.ts` (或如果有比几个简单的默认更深的东西,则单独文件).

### 工作流程

修改时,该软件包可以通过 `jetpack build -v js-packages/number-formatters` (假定 [CLI 工具](https://npmcn.com/package/%40automattic/number-formatters/%60https://github.com/Automattic/jetpack/blob/trunk/tools/cli/README.md%60) )或 `pnpm run build` (JP 用途) `pnpm`)),最新版本通过npm/yarn链接到相应的外部 repo来测试,例如wp-calypso.

一旦提交/合并更改,就应遵循典型的Jetpack工作流程,公布对国家预防机制的更改.

## 常见问题

### @automattic/number-formatters 是什么？

公用事业的格式

### 如何安装 @automattic/number-formatters？

在项目目录运行 npm install @automattic/number-formatters，或使用 pnpm add / yarn add / bun add。

### @automattic/number-formatters 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @automattic/number-formatters 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @automattic/number-formatters 可以商用吗？

@automattic/number-formatters 使用 GPL-2\.0-or-later 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @automattic/number-formatters 的下载量有多少？

根据 npm 官方下载统计，@automattic/number-formatters 在 2026/10/07 – 2026/11/05 这 30 天内被下载 64,560 次，日均约 2,152 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @automattic/number-formatters 还在维护吗？

最新版本 1\.3\.0 发布于 2026/11/03（5 天前）；至今共发布 46 个版本，其中过去 12 个月发布了 29 个；首次发布于 2025/04/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。