# @gooddata/number-formatter 中文文档

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

版本：1\.0\.6
npm 元数据更新时间：2026-10-27T14:12:41.610Z
中文译文更新时间：2026-11-16T19:16:54.185Z
软件包许可：LicenseRef-LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40gooddata/number-formatter
原文对照：https://npmcn.com/package/%40gooddata/number-formatter/?lang=original
项目主页：https://github.com/gooddata/gooddata-formatter#readme
源码仓库：https://github.com/gooddata/gooddata-formatter

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

- 包体积（解压后）：349 kB，52 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2023-08-21T13:34:51.375Z
- 最新版本发布：2024-11-18T08:43:23.195Z
- 近 30 天下载量：34333（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

内容的好数据编号

## 安装

```sh
npm install @gooddata/number-formatter
```

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

## README

# 类型脚本中的好数据编号格式

## 概览

这是原始 gdc- numberjs 库的 TypeScript 重用 。 它以一些修改和例外来反映原作的逻辑.

## 关键特性和差异

### 核心特征

-   包括所有原始特征,不包括由于使用量微不足道而删除的科学格式.
-   已注意到的一些差异是:
    -   浮动点精度差异的四舍五入差异.
    -   不同的处理方式 `\0` 字符键.
    -   原始版本中的bug-fixs .
-   允许选项后继兼容=假以关闭某些行为 .

**支持特征**

-   多数其他特征已纳入调整后的API,以提高效率.
-   例如,条纹颜色现在被表示为"格式选项"# 包含颜色属性.
-   格式选项# 包含颜色和Formatter# 解析从 gdc- numberj 中仿取对应的 。 然而,色彩编码被修改,以便向用户提供更多信息.
-   诸如Excellent Escape和特定格式字符串翻译等具体功能因其特殊性和潜在的复杂性而未包括在内.

## 格式字符串语法

格式字符串与 [Excel 自定义编号格式字符串](https://support.microsoft.com/en-us/office/review-guidelines-for-customizing-a-number-format-c0a1d1fa-d3f4-4018-96b7-9c9354dd99f5)然而,有一些关键差异和额外特征。 本节在不假设对Excel格式字符串有任何事先了解的情况下解释格式字符串语法.

### 数字格式

数字格式是格式字符串的基本单位。 这是一个Unicode字符串,可以应用某些类型的占位符. 例如:"$#,QQ.00"是一个格式字符串,显示数字1为"$1.00",而数字1000为"$1000.00".

在这里,我们探索所有支持的占位符:

#### 0 (零点)

一个零就是一个 **数字占位符**。如果数字的位数比格式中的零少,则显示微不足道的零。 这适用于数字的整数和分数部分.

考虑这些例子以便更好地理解:

| 格式 | 数目 | 结果 |
| --- | --- | --- |
| 0: 00 (简体中文) | 页:1 | `04.00` |
| 0: 00 (简体中文) | \-4号 | `-04.00` |
| 0: 00 (简体中文) | 4.1 国家 | `04.10` |
| 0: 00 (简体中文) | 第40条 | `40.00` |

#### \# (哈许)

大麻也是个 **数字占位符**与 `0` 占位符是它不显示微小的零。 这适用于数字的整数和分数部分.

考虑这些例子以便更好地理解:

| 格式 | 数目 | 结果 |
| --- | --- | --- |
| ## | 页:1 | `4` |
| ## | \-4号 | `-4` |
| ## | 4.1 国家 | `4.1` |
| ## | 第40条 | `40` |
| ## | 40.1 (中文(简体) ) | `40.1` |

#### (问题标记)

这是一个 **数字占位符**与 `0` 占位符是,微小的零将被格式化为空格(')。 这可以帮助左绘数字的整部分,从而确保格式化的结果(字符串)长度相同,并有小数点对齐.

| 格式 | 数目 | 结果 |
| --- | --- | --- |
| #.00 (中文(简体) ) | 页:1 | `4.00` |
| #.00 (中文(简体) ) | 第40条 | `40.00` |
| #.00 (中文(简体) ) | 40.11 联合国 | `40.11` |

**页:1**: 此占位符对格式化字符串的分数部分没有多大用处 。 检查一下关于 十进制精确度和四舍五入来找出原因.

#### , (Comma) (英语)

**显示千位分隔符或平分号** 乘以1000的倍数 事实上,逗号有两种可能的用途, 取决于你放在哪里.

要将数字格式化为千位分隔符,请在任意两个数字占位符之间设置逗号。 比如说 `0,0`, (中文(简体) ), `#,#`,或 `#,0`。 。 。 .

逗号字符的其他位置可以用于应用值缩放. 缩放因数为1000至 函数。 例如,格式 `#,,.#` 表示缩放1000^2=1000.

在规模化方面,有一些微妙之处需要注意.

-   如果在逗号后加上一个数字占位符,那么缩放因子将是1000到数 连续的逗号减一。 例如,格式 `#,,#` 表示缩放1000.
    
-   您可以在格式字符串的完整部分或分部分上指定缩放,或者两者兼有。 如果您指定 缩放格式字符串的两侧,效果是累积的。 例如,格式 `#,.#,` 表示缩放 以 1000^2 = 1000000 为单位.
    
-   如果在格式字符串的一面指定了多次缩放,那么将使用第一个发现的发生; 所有其他事件都将被忽略.
    

让我们举几个例子;请注意,这些是故意编造的,以展示“funny stuff ” 有关 缩放规格。 见下表:

| 格式 | 数目 | 结果 | 说明 |
| --- | --- | --- | --- |
| {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 第1234条 | `1,234` | 千个分隔器 |
| #, 1000个 | 第1234条 | `1.234` | 左侧指定缩放 |
| {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1}千分之数, | 第1234条 | `1.234` | 右侧指定缩放 |
| # | 第1234条 | `1` | 缩放 1000 |
| ,, # , # , # | 第1234条 | `1` | 缩放 1000 |
| ,#.0, (中文(简体) ), | 1234567 (英语) | `1.2` | 缩放 1000 000 |
| # | 1234567 (英语) | `1,234.6` | 分离器和缩放器 |

**建议**:保持简单. 尽量避免数字占位符后面出现逗号表示缩放的情况. 这不必要地使对格式字符串的思考复杂化. 如果可能,请将缩放逗号保留在末尾 格式字符串,最好是在字符串整个部分的末尾.

#### .(期间)

A 类 **小数点的占位符**。如果格式字符串没有指定小数点,那么所有数字将是 四舍五入并格式化为整数.

格式字符串的分部分应该总是从数字占位符字符的顺序开始 表示用于分数部分的理想精确度。 然后,可以使用任何其他字符.

**页:1**: 如果您指定了小数点, 但小数点后的字符串不包括任何数字占位符, 那么 格式化时会忽略小数点右侧的所有字符(包括小数点).

##### 十进制精度、 四舍五入和微缩零

数目 **按小数点排列的连续数字占位符将作为小数精度使用**用于 实例 `#.0000` 或者说 `#.####` 表示小数精度 4. 主题将绕到 显示精确度。 如果数字没有达到理想的精度,则会被扩展并加零.

在替换数字占位符时,在格式化分数部分时逻辑不同 编号。 最重要的是,由于如何精确的设定和处理, **页:1 `?` 对占位符的有效处理相同 作为 `0` 占位符**。 。 。 .

这个 `#` 占位符的处理方式与格式化整个部分时的处理方式相同 - 后面的零被剪切。 此外, 如果分数部分的格式字符串完全由散列组成,而格式数字的分数部分为零,则 所有后端的零被修剪,小数点将完全不打印出.

| 格式 | 数目 | 结果 |
| --- | --- | --- |
| {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 4.1 国家 | 页:1 |
| {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 4.5 国家 | 页:1 |
| 0.0 数据 | 4.1 国家 | 4.1 国家 |
| 0.0 数据 | 4.15 联合国 | 4.2 (中文(简体) ) |
| 0\. □( □) | 4.1 国家 | 4.1 国家 |
| 0\. □( □) | 4.01 (中文(简体) ) | 4.01 (中文(简体) ) |
| 0\. □( □) | 4.001 (中文(简体) ) | 页:1 |
| 0\. □美元(美元) | 4.001 (中文(简体) ) | 4美元(美元) |

#### 逃跑

格式字符串可以从占位符中逃脱,从而表示它们应该被从字面上处理. 逃脱 使用反斜线进行( n)`\`)在占位符前.

请记住,如果您正在按程序构建格式字符串,您必须避免反弹 好(这样) `\\`) (中文(简体) ).

假设您想将格式字符串中的逗号从字面上,而不是作为小数点。 然后你可以密码 格式字符串 `\\. #.#`。 。 。 .

#### 颜色编码

格式字符串可能包括颜色标记,以表示格式化的结果在上下文中应如何被颜色 允许这个。 支持的颜色标记有三种类型:

-   已命名的颜色标记, 例如代码 `[red]`; 格式可以识别几种命名的颜色 这里使用:黑、蓝、青、绿、红、白、黄、无
    
    颜色名称被选中为对大小写不敏感 。 如果您指定了未知的颜色, 那么标记不被当作 名称为颜色标记,但按字面处理。 它将以格式化的值显示
    
-   自定义颜色代码标记, 编码为 `[color=#FF0000]`
    
    颜色码可能包括散列,也可能不包括散列,而外壳不重要.
    
-   自定义背景代码标记, 编码为 `[backgroundColor=#000000]`
    
    背景代码可能包括散列,也可能不包括散列,外壳无关紧要.
    

由于命名为颜色标记和自定义的颜色代码标记都描述了同样的事情 - 格式化值的颜色 渲染器更倾向于自定义颜色标记上指定的值.

颜色标记可以在格式字符串中任意出现. 如果您指定了多个自定义颜色或背景颜色 标记在同一字符串中,第一个发现被考虑进去,其他被丢弃.

_建议_: 要保持格式字符串的正常和易于理解,最好集中颜色编码标记 在一个地方,最好是在格式字符串开头.

### 有条件的格式

迄今为止,我们已经覆盖了基本数字格式字符串。 条件格式化使您能够指定 用于不同数字或数字范围的其他格式字符串.

**页:1**:在有条件格式化的情况下,替代格式将始终是格式化 编号。 这使得您可以完全定制负数的表示.

#### 隐性替代品

在有条件的格式中,替代格式字符串由分号来分隔. 有条件的格式允许 (b) 说明多种隐含的替代办法和/或明确的条件.

一个隐含的有条件格式可以包含最多3个用分号分隔的替代格式(;):

-   第一个格式字符串是用于QQ 0的值.
-   第二个格式字符串用于数值 < 0.
-   第三个格式字符串是为值=0.

示例 `good ##.##;bad ##.##;okay` 格式1为 `good 1`,-1作为 `bad 1`,0为 `okay`。 。 。 .

#### 明确替代品

除隐含格式外,还可以指定明确的条件和格式. 明确条件指定运算符和右侧值,然后指定格式字符串。 比如说, `[=1000]#, grand` 将格式为 1000 `1 grand`。 。 。 .

支持的运算符有: `=`, (中文(简体) ), `<`, (中文(简体) ), `>`, (中文(简体) ), `<=`, (中文(简体) ), `>=`。右手边是正或负 整数或 `NULL`A级 `NULL` 右手边只与等号操作员有道理。 如果你用的话 与任何其他操作员,那么该特定选项将被忽略.

无效条件对于提供格式值时使用的特殊文字有用 `NULL` (单位:千美元)`NULL` 与 完全不存在,而不是无指针)。 无效条件中提供的格式字符串总是按字面处理.

#### 组合格式

明确和隐含的备选办法可以合并.

示例 `[=13]fun;[=666]more fun;[>=1000000]#,,.00M;[>=1000]##,k;##;-##.00;0000`。 。 。 .

#### 条件评估令

条件评价顺序如下:

1.  所有平等条件首先按从左到右顺序进行评估.
2.  所有其他条件按左到右顺序评估.

#### 颜色

每个选项的格式字符串可以包括自己的颜色编码.

### 算术表达式格式

算术表达式允许在格式化前在值上进行分割和调制操作 使用指定的格式字符串。 它们有助于格式化代表持续时间的值.

算术表达式被三边括号所包围,并含有分解器、调制器和格式 由管道分隔的字符串 : `{{{[division]|[modulo][.]|[format]}}}`。 。 。 .

-   `division` 可以是任何正浮点数.
-   `modulo` 也可以是任何正整数,并用于将值向格式的浮点调制. `modulo` 之后可以加一个逗号(`.`) 人物. 这表示是否要下方分数部分 ,是否格式化.
-   `format` 可以是数字格式或有条件格式.

算术表达式 `{{{3600|24|#}}}` 将首先将数值除以格式 `3600`,则 执行模组 `24` ,然后使用 `#` 以格式化该值.

格式字符串可以包含最多256个算术表达式.

### Unicode 支持

格式字符串与Unicode字符效果良好. 您可以通过使用条件格式和专门的Unicode字符来表达自己的艺术面并创建简单的测量仪.

请注意,此处包含的预设执行使用来自私用区域的Unicode字符,从U+E000开始,可能达到U+E2FF. 避免将这些字符列入格式字符串以避免意外结果.

### 示例格式字符串

前几个例子显示的格式显示了基本使用。 这里介绍的一些比较复杂的例子。 为了简洁起见,色彩编码不包括在内.

**条件值缩放**

`[=null]0; [>=1000000000]#,,,.0 B; [>=1000000]$#,,.0 M; [=0]0; [>0]$#,##0; [<=-1000000000]-#,,,.0 B; [<=-1000000]-#,,.0 M; [<0]-$#,##0`

**数字的百分比和小高分格式**

`00.0%[>=.9]██████████; 00.0%[>=.8]█████████░; 00.0%[>=.7]████████░░; 00.0%[>=.6]███████░░░; 00.0%[>=.5]██████░░░░; 00.0%[>=.4]█████░░░░░; 00.0%[>=.3]████░░░░░░; 00.0%[>=.2]███░░░░░░░; 00.0%[>=.1]██░░░░░░░░; #0.0%█░░░░░░░░░`

## 常见问题

### @gooddata/number-formatter 是什么？

内容的好数据编号

### 如何安装 @gooddata/number-formatter？

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

### @gooddata/number-formatter 支持 TypeScript 吗？

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

### @gooddata/number-formatter 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gooddata/number-formatter 可以商用吗？

@gooddata/number-formatter 使用 LicenseRef-LICENSE 许可。声明的许可为 LicenseRef-LICENSE，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @gooddata/number-formatter 的下载量有多少？

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

### @gooddata/number-formatter 还在维护吗？

最新版本 1\.0\.6 发布于 2024/11/18（2 年前）；至今共发布 8 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/08/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

