# @exodus/currency 中文文档

规范地址：https://npmcn.com/package/%40exodus/currency/

版本：6\.4\.2
npm 元数据更新时间：2026-10-13T17:13:00.319Z
中文译文更新时间：2026-11-14T03:50:32.142Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40exodus/currency
原文对照：https://npmcn.com/package/%40exodus/currency/?lang=original
项目主页：https://github.com/ExodusMovement/exodus/tree/master/libs/libraries/currency
源码仓库：https://github.com/ExodusMovement/exodus

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

- 包体积（解压后）：69.6 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2018-10-25T05:16:35.435Z
- 最新版本发布：2026-10-13T17:13:00.132Z
- 近 30 天下载量：96264（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 4 个）

## 中文简介

货币供养.

## 安装

```sh
npm install @exodus/currency
```

也可以使用：`pnpm add @exodus/currency`、`yarn add @exodus/currency`、`bun add @exodus/currency`

## README

# @ exodus/ 货币

一个经过重试的JavaScript库,用来与单位一起处理任意的精确数字.

## 为什么?

没有单位的数字毫无意义。 对单位的疏忽会导致灾难. 想想这些出名的事件...

1.  **98年火星探测器**

出自:https://en.wikipedia.org/wiki/Mars Climate Orbiter: 页面存档备份,存于互联网档案馆

> 然而,1999年9月23日,随着航天器进入轨道插入,由于地面计算机软件以磅-秒(lbf s)的非SI单位而不是美国航天局和洛克希德公司合同中规定的新吨-秒(N s)的计量单位输出,与航天器的通信被丢失。 宇宙飞船在使火星过于接近行星的轨道上相遇,使火星从上层大气中穿过并解体.

2.  **加拿大航空公司143号班机**

由https://en.wikipedia.org/wiki/Gimli Glider提供 维基语录链接:名人名言 - 文学作品 - 谚语 - 谚语 - 谚语 - 谚语

> ...在12,500米(41,000英尺)高空上从燃料中抽出, 大约经过从蒙特利尔飞往埃德蒙顿的航班中途。 机组人员得以将飞机安全地滑行到加拿大皇家空军在马尼托巴Gimli的基地Gimli工业园机场紧急降落

> 之后的调查揭示出公司倒闭与连锁人犯错误相结合,挫败了内置保障. 由于对最近采用的取代帝国制度的计量制度有误解,燃料装载被误判.

* * *

如果你正在写软件 **处理别人的钱** (单位:千美元)[http://www.exodus.com/ (中文(简体) )](http://www.exodus.com/)),你不能承担错误. **这就是为什么 这个图书馆是建成的.**

## 安装

```sh
pnpm add @exodus/currency
```

## 重要概念

### 单位类型

一个 UnitType 定义一个单元的家族. 实例:

-   美元:美元和分数
-   叶特鲁姆:ETH,Finney,szaboe,wei,gwei,......
-   比特币:比特币,比特币,相克币
-   体重:千克、克、毫克、.

根据使用情况,您可以多多少少地定义您的单位,例如,对于Ethereum您可能只需要 `ETH` 财务报告和审定财务报表 `wei` 并省取放纵.

UnitType 可用于解析像 `1 BTC` 或者说 `100000000 satoshis` 返回数字单元实例.

#### 单位Type.prototype.base 单元

一个家庭最小的不可分割单位称为基单位. 家庭中的每一个其他单位都界定其与最小单位的关系,其中 `power`,使该单位具有 `10 ^ power` 基数单位。 例如,在比特币家族 `BTC` 单位被定义为有功率8,因为10^8 satowshis组成了1比特币. 目前只支持基础10个单元类型. 基地单位有 `power === 0`。 。 。 .

#### UnitType.prototype. 默认单位

单位最大 `power` 在家庭中,称为默认单位.

### 数字单位

数字单元(Number Cunit)是带有给定的UnitType数字的不可改变的包装器. 可用于:

-   在同一家庭内与其他数字单元实例进行算术,例如加元和美分.
-   同一家庭中的比较数字单元实例.
-   用数字进行算术,例如:. `amount.mul(2)`。 。 。 .
-   序列化为人可读格式,例如:. `1 BTC` 或者说 `100000000 satoshis`。 。 。 .

重要: 数字单元操作只对同一家庭的单元有意义:

-   : 白色 检查 标记 : `bitcoinAmount.add(satoshisAmount)`
-   : x : `bitcoinAmount.add(etherAmount)`

要转换 _贝文_ 来自不同家庭的单位,如比特币 - > 美元,使用 [转换](https://npmcn.com/package/%40exodus/currency/#readme-unittype-conversion) 函数.

## 使用量

### 示例

```js
import NumberUnit, { UnitType } from '@exodus/currency'

// create a unit family
const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 }) // 1 BTC = 10^8 satoshis; 1 bit = 10^2 satoshis
bitcoin.units.satoshis === bitcoin.baseUnit // true
bitcoin.units.BTC === bitcoin.defaultUnit // true

// now create a NumberUnit
const amount1 = NumberUnit.create(1.53, bitcoin.units.BTC) // alternatively: `bitcoin.defaultUnit(1.53)`
const amount2 = NumberUnit.create('1530000', bitcoin.units.bits) // notice it can accept number strings

// when serializing, be sure to provide the right unit
amount1.toString({ unitInstance: bitcoin.units.BTC }) // '1.53 BTC'
amount1.toString({ unitInstance: bitcoin.units.bits }) // '1530000 bits'
amount2.toString({ unitInstance: bitcoin.units.BTC }) // '1.53 BTC'
amount2.toString({ unitInstance: bitcoin.units.bits }) // '1530000 bits'

// compare numerical values
amount1.equals(amount2) // true
```

### 单位类型

#### UnitType.create( 单位)

**参数**

-   `units`: 对象将单位名称映射到其上 [动力](https://npmcn.com/package/%40exodus/currency/#readme-unittypeprototypebaseunit),也就是说. `{ [unitName]: power }`

**回返**(单位:千美元) `UnitType` 举个例子.

**示例**

```js
import { UnitType } from '@exodus/currency'

const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 })
```

#### UnitType.prototype.parse( 数字 UnitString) 数据

**参数**

-   `numberUnitString`:一个序列编号单位. 见 [数字单元. prototype.to String](https://npmcn.com/package/%40exodus/currency/#readme-numberunitprototypetostring-unit-unitinstance-format)。 。 。 .

**回返情况:** 实例 `NumberUnit`。 。 。 .

```js
const amount = bitcoin.parse('1.53 BTC')
amount.toNumber(bitcoin.defaultUnit) // 1.53
```

#### UnitType.prototype.ZERO (英语)

0值的方便财产 `NumberUnit`。 。 。 .

```js
bitcoin.ZERO.toBaseNumber() // 0
bitcoin.ZERO.toDefaultNumber() // 0
```

### 数字单位

**说明:** `NumberUnit` 实例是不可改变的。 全体 `NumberUnit` 实例方法返回两个新实例 `NumberUnit`,或在某些情况下,未修改的 `NumberUnit` 为了最优化的目的.

```js
const amount0 = bitcoin.defaultUnit(3.5)
const amount1 = bitcoin.defaultUnit(3.5)
const amount2 = bitcoin.defaultUnit(4)
amount0 instanceof NumberUnit // true
amount0 === amount2 // false as the underlying amounts are different
amount0 === amount1 // even though the underlying units and amounts are the same, do NOT rely on this always being false. Use amount0.equals(amount1) to be sure
```

#### 数字单位. prototype.abs ()

**回返情况:** 一个新的实例 `NumberUnit` 与数字的绝对值.

**示例**

```js
const amount = bitcoin.defaultUnit(-3.5)
amount.abs().toNumber(bitcoin.defaultUnit) // 3.5
```

#### 数字单位. prototype.add(数字单位)

**回返情况:** 一个新的实例 `NumberUnit` 这是两个数字的总和.

**示例**

```js
const amount = bitcoin.defaultUnit(-3.5)
const sum = amount.add(bitcoin.parse('1000000 bits'))
sum.toString({ unitInstance: bitcoin.defaultUnit }) // '-2.5 BTC'
```

#### 数字单位. prototype.clamp 下Zero ()

**回返情况:** 数字单位的示例 `num = Math.max(num, 0)`

**示例**

```js
bitcoin.defaultUnit(1.53).clampLowerZero().toDefaultString({ unit: true }) // '1.53 BTC'

bitcoin.defaultUnit(-1.53).clampLowerZero().toDefaultString({ unit: true }) // '0 BTC'
```

#### 数字单位. prototype.clone ()

**回返情况:** 新实例 `NumberUnit` 价值一样.

**示例**

```js
const amount = bitcoin.BTC(1.3)
const amount2 = amount.clone()
amount2.toDefaultString({ unit: true }) // '1.3 BTC'
```

#### 数字单位. prototype.equals (数字单位)

单位不可知平等检查(如:. `1000 m === 1 km`(中文(简体) )

**参数:**

-   `numberUnit`: 实例 `NumberUnit` 比较一下.

**回返情况:** A 类 `boolean`。 。 。 .

**示例**

```js
const distance1 = distanceSI.parse('1 km')
const distance2 = distanceSI.parse('1000 m')

distance1.equals(distance2) // true
```

#### 数字单位. prototype.gt(数字单位)

单位不可知性检查一个数字单位是否大于另一个数字单位(例如. `1.1 km > 1000 m`) (中文(简体) ).

**参数:**

-   `numberUnit`: 另一个实例 `NumberUnit`。 。 。 .

**回返情况:** A 类 `boolean`, (中文(简体) ), `true` 如果它比过去大 `numberUnit`。 。 。 .

**示例**

```js
const distance1 = distanceSI.parse('1.1 km')
const distance2 = distanceSI.parse('1000 m')

distance1.gt(distance2) // true
```

#### 数字单位. prototype.gte(数字单位)

单位不可知性检查一个数字单位是大于还是等于另一个数字单位(例如. `1.1 km >= 1000 m`) (中文(简体) ).

**参数:**

-   `numberUnit`: 另一个实例 `NumberUnit`。 。 。 .

**回返情况:** A 类 `boolean`, (中文(简体) ), `true` 如果它大于或等于通过 `numberUnit`。 。 。 .

**示例**

```js
const distance1 = distanceSI.parse('1.1 km')
const distance2 = distanceSI.parse('1000 m')

distance1.gte(distance2) // true
```

#### 数字单位. prototype.isZero

`boolean` 财产, `true` 如果数字是 `0`。 。 。 .

**示例**

```js
bitcoin.BTC(0).isZero // true
bitcoin.BTC(-1).isZero // false
```

#### 数字单位. prototype.lt(数字单位)

单位不可知性检查一个数字单位是否小于另一个数字单位(例如. `1000 m < 1.1 km`) (中文(简体) ).

**参数:**

-   `numberUnit`: 另一个实例 `NumberUnit`。 。 。 .

**回返情况:** A 类 `boolean`, (中文(简体) ), `true` 如果它比通过在 `numberUnit`。 。 。 .

**示例**

```js
const distance1 = distanceSI.parse('1000 m')
const distance2 = distanceSI.parse('1.1 km')

distance1.lt(distance2) // true
```

#### 数字单位. prototype.lte(数字单位)

单位不可知性检查一个数字单位是否小于或等同另一个数字单位(例如. `1000 m <= 1.1 km`) (中文(简体) ).

**参数:**

-   `numberUnit`: 另一个实例 `NumberUnit`。 。 。 .

**回返情况:** A 类 `boolean`, (中文(简体) ), `true` 如果它小于或等于通过 `numberUnit`。 。 。 .

**示例**

```js
const distance1 = distanceSI.parse('1000 m')
const distance2 = distanceSI.parse('1.1 km')

distance1.lt(distance2) // true
```

#### 数字 Unit.prototype.negate ()

忽略了数字.

**回返情况:** 新实例 `NumberUnit` 数字被否定.

**示例**

```js
const distance1 = distanceSI.parse('1 km')
const distance2 = distance1.negate()

distance3.toDefaultString({ unit: true }) // '-1 km'
```

#### 数字单位. prototype.sub(数字单位)

计算两个数字的相差 .

**参数:**

-   `numberUnit`: 另一个实例 `NumberUnit`。 。 。 .

**回返情况:** 代表两者差异的"数字单元"实例.

**示例**

```js
const distance1 = distanceSI.parse('3 km')
const distance2 = distanceSI.parse('1000 m')
const distance3 = distance1.subtract(distance2)

distance3.toDefaultString({ unit: true }) // '2 km'
```

#### 数字 Unit.prototype.mul(数字相似)

将数字单位乘以平分.

**参数:**

-   `numberLike`:一个数字或数字字符串,例如. `100` 或者说 `'100'`

**回返情况:** 数字单位 `numberLike` 乘数.

**示例**

```js
const distance1 = distanceSI.parse('3 km')
const distance2 = distance1.mul(2)
distance3.toDefaultString({ unit: true }) // '6 km'
```

#### 数字 Unit.prototype.div(数字类似)

将数字单位除以平分.

**参数:**

-   `numberLike`:一个数字或数字字符串,例如. `100` 或者说 `'100'`

**回返情况:** 数字单位 `numberLike` 分卫.

**示例**

```js
const distance1 = distanceSI.parse('3 km')
const distance2 = distance1.mul(2)
distance3.toDefaultString({ unit: true }) // '6 km'
```

#### Number Unit.prototype.toString({单位,单位Instance,格式})

序列化 a `NumberUnit` 改为 `string`。 。 。 .

**签署:** `toString([options])`

**参数:** `options`类型 `object`. 可选.

-   `unitInstance`: 字符串表示式中使用的单位.
-   `unit`数字 : `boolean`,默认为 `true`如果 `true`,包括单位字符串.

**回返情况:** A 类 `string` 代表数字和单位.

**示例**

```js
const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 })
const amount1 = bitcoin.parse('1.5 BTC')
amount1.toString({ unitInstance: bitcoin.units.BTC }) // '1.5 BTC'
amount1.toString({ unitInstance: bitcoin.units.BTC, unit: false }) // '1.5'
amount1.toString({ unitInstance: bitcoin.units.bits }) // '1500000 bits'
```

#### Number Cunit.prototype.toBaseString({单位=假}={})

序列化 a `NumberUnit` 改为 `string`时,使用其 [基准单位](https://npmcn.com/package/%40exodus/currency/#readme-unittypeprototypebaseunit)。 。 。 .

**参数**

-   `unit`: 如果 `true`,包括单位字符串.

**回返情况:** A 类 `string` 代表数字 [基准单位](https://npmcn.com/package/%40exodus/currency/#readme-unittypeprototypebaseunit)。 。 。 .

**示例**

```js
const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 })
const amount1 = bitcoin.parse('1.5 BTC')
amount1.toDefaultString() // '1.5'
amount1.toDefaultString({ unit: true }) // '1.5 BTC'
```

#### Number Cunit.prototype.to DefaultString ({单位=假}= {}) 互联网档案馆的存檔,存档日期2011-12-02

序列化 a `NumberUnit` 改为 `string`时,使用其 [默认单位](https://npmcn.com/package/%40exodus/currency/#readme-unittypeprototypedefaultunit)。 。 。 .

**参数**

-   `unit`: 如果 `true`,包括单位字符串.

**回返情况:** A 类 `string` 代表数字 [默认单位](https://npmcn.com/package/%40exodus/currency/#readme-unittypeprototypedefaultunit)。 。 。 .

**示例**

```js
const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 })
const amount1 = bitcoin.parse('1.5 BTC')
amount1.toDefaultString() // '1.5'
amount1.toDefaultString({ unit: true }) // '1.5 BTC'
```

#### 数字Unit.prototype. is Negative

`boolean` 财产, `true` 如果数字为负数.

**示例**

```js
const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 })
const amount1 = bitcoin.defaultUnit(-1.5)
amount1.isNegative // true
```

#### Number Unit.prototype.is 亲切性

`boolean` 财产, `true` 如果数字为正数.

**示例**

```js
const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 })
const amount1 = bitcoin.defaultUnit(1.5)
amount1.isPositive // true
```

## 单位类型转换

要在单位的不同家族间进行转换,例如比特币 - > 乙醚基于已知的汇率,使用转换ByRate工具.

```js
import { conversionByRate } from '@exodus/currency'

// define the conversion rate, e.g. 1 BTC = 10 ETH
const bitcoin = UnitType.create({ satoshis: 0, bits: 2, BTC: 8 })
const ethereum = UnitType.create({ wei: 0, ETH: 18 })
const convert = conversionByRate(bitcoin, ethereum, 10)
const etherAmount = convert(bitcoin.defaultUnit(2))
etherAmount.toDefaultString({ unit: true }) // '20 ETH'
```

## 资产使用

```js
import assets from '@exodus/assets-base'
import { UnitType } from '@exodus/currency'

const ether = UnitType.create(assets.ethereum.units)

const e1 = ether.defaultUnit(2)
const e2 = ether.parse('2 ETH')
const e3 = e2.add(ether.units.ETH(3))

e1.equals(e2) // true
e3.toDefaultString() // '5'
e3.toDefaultNumber() // 5
e3.toString({ unitInstance: ether.units.ETH }) // '5 ETH'
e3.toBaseString() // '5000000000000000000'
e3.toString({ unitInstance: ether.units.wei }) // '5000000000000000000 wei'
e3.toString({ unitInstance: ether.units.Gwei }) // '5000000000 Gwei'
```

## 常见问题

### @exodus/currency 是什么？

货币供养\.

### 如何安装 @exodus/currency？

在项目目录运行 npm install @exodus/currency，或使用 pnpm add / yarn add / bun add。

### @exodus/currency 支持 TypeScript 吗？

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

### @exodus/currency 支持 ESM 还是 CommonJS？

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

### @exodus/currency 可以商用吗？

@exodus/currency 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @exodus/currency 的下载量有多少？

根据 npm 官方下载统计，@exodus/currency 在 2026/10/14 – 2026/11/12 这 30 天内被下载 96,264 次，日均约 3,209 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @exodus/currency 还在维护吗？

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