# @checkdigit/currency 中文文档

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

版本：9\.0\.0
npm 元数据更新时间：2026-10-05T17:50:17.731Z
中文译文更新时间：2026-11-09T12:26:29.231Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：353 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.18\.0
- 运行依赖：0 个
- 首次发布：2020-03-10T15:01:41.812Z
- 最新版本发布：2026-09-08T21:02:25.440Z
- 近 30 天下载量：2752（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：93（近 12 个月 33 个）

## 中文简介

标准货币处理

## 安装

```sh
npm install @checkdigit/currency
```

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

## README

# 检查数字货币库

版权所有 2021-2026 [检查 Digit, LLC](https://checkdigit.com/)

Check Digit货币库是Check Digit服务在特定日期/时间处理货币类型,格式化以及国家/货币关系的官方认可方法. 特征 :

-   从2018年开始的某个特定日期/时间及以后,任何更早的货币和国家查询功能都会出错.
-   数量、货币、 ISO 3166 国家代码( 数字, alpha2, alpha3) 和 ISO 4217 货币代码( 名称、 字母、 数字) 类型
-   check Digit- Standard 货币格式化 Money 对象,有多种选项
-   将字符串分析为检查数字标准货币对象
-   测试以确保遵守基于数字的Intl。 数字格式货币执行
-   测试,以确保基本JS引擎在货币方面的正确性
-   多地( 所有现代浏览器和节点 24+ 包含全 [伊斯兰法院联盟](http://icu-project.org/)(中文(简体) )
-   使用内置JS引擎 `Intl` 执行,无依赖

## 安装

```shell
npm install @checkdigit/currency
```

然后:

```ts
import * as currency from '@checkdigit/currency';
```

## 类型和接口

货币库的四个核心类型是:

-   量,是以比和或字符串形式(或-0)为整数.
-   货币,即与货币Alphabetic Code(例如“USD”)的货币结合的金额
-   国家,是含有一国ISO 3166信息和货币的对象
-   货币,是含有货币ISO 4217信息的对象

国家和货币代码有定义的文字类型:

-   货币法
-   货币编码
-   货币Name
-   阿尔法2国
-   阿尔法3国
-   国名

```ts
export interface Money {
  amount: string; // integer amount in minor units, e.g. '12345' for $123.45
  currency: CurrencyAlphabeticCode;
}

export interface Country {
  // ISO 3166 country display name, alpha2/3 and numeric codes
  name: string;
  alpha2: CountryAlpha2; // 'US' | 'NZ' ...
  alpha3: CountryAlpha3; // 'USA' | 'NZL' ...
  numeric: CountryNumeric; // '840' | '554' ...

  // ISO 4217 currencies
  currencyCodes: CurrencyAlphabeticCode[];
}

export interface Currency {
  name: CurrencyName; // 'US Dollar' | 'New Zealand Dollar' ...
  alphabeticCode: CurrencyAlphabeticCode; // 'USD' | 'NZD' ...
  numericCode: CurrencyNumericCode; // '840' | '554' ...
  minorUnits?: number;
  isFund?: true;
}
```

## 职能

### 格式化

-   `format({ amount, currency }: Money, options?: CurrencyFormatOptions, locales?: string | string[]): string`

### 分析

-   `parse(money: string, currency: CurrencyAlphabeticCode, locales?: string | string[]) => Money;`

### 货币

-   `allCurrencies(): Currency[]`
-   `findCurrency(search: string): Currency`
-   `getCurrency(code: CurrencyAlphabeticCode | CurrencyNumericCode): Currency`
-   `getMinorUnitDigits(currency: CurrencyAlphabeticCode)`
-   `getSymbol(currency: CurrencyAlphabeticCode, locales?: string | string[]): string`

### 国家

-   `allCountries(): Country[]`
-   `getCountry(code: CountryAlpha2 | CountryAlpha3 | CountryNumeric): Country`
-   `getCountriesForCurrency(code: CurrencyAlphabeticCode): CountryAlpha3[]`

## 用法实例

### `format`

```ts
currency('2023-11-02T15:35:47.191Z').format({
  amount: '123456789012345678901234567890',
  currency: 'USD',
});
// $1,234,567,890,123,456,789,012,345,678.90

currency('2023-11-02T15:35:47.191Z').format({
  amount: '123456',
  currency: 'USD',
});
// $1234.56

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456', currency: 'USD' },
  {
    useGrouping: false,
    useCurrency: false,
  },
);
// 1234.56

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456', currency: 'USD' },
  {
    useGrouping: false,
    useCurrency: false,
    useDecimal: false,
  },
);
// 123456

currency('2023-11-02T15:35:47.191Z').format({ amount: '-0', currency: 'USD' });
// -$0.00

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456789', currency: 'USD' },
  {
    currencyDisplay: 'code',
  },
  'de-DE',
);
// 1.234.567,89 USD

currency('2023-11-02T15:35:47.191Z').format(
  { amount: '123456', currency: 'USD' },
  {
    useDecimal: false,
    useGrouping: false,
    useCurrency: false,
  },
  'as-IN',
);
// ১২৩৪৫৬
```

### `parse`

```ts
currency('2023-11-02T15:35:47.191Z').parse('.1', 'USD');
// { amount: '10', currency: 'USD' }

currency('2023-11-02T15:35:47.191Z').parse('1', 'USD');
// { amount: '100', currency: 'USD' }

currency('2023-11-02T15:35:47.191Z').parse('$1.23', 'USD');
// { amount: '123', currency: 'USD' }

currency('2023-11-02T15:35:47.191Z').parse('123.456,78', 'EUR', 'de-DE');
// { amount: '12345678', currency: 'EUR' }

currency('2023-11-02T15:35:47.191Z').parse('10€', 'EUR');
// { amount: '1000', currency: 'EUR' }

currency('2023-11-02T15:35:47.191Z').parse('10', 'JPY');
// { amount: '10', currency: 'JPY' }
```

### `getSymbol`

```ts
currency('2023-11-02T15:35:47.191Z').getSymbol('USD');
// $

currency('2023-11-02T15:35:47.191Z').getSymbol('NZD');
// NZ$

currency('2023-11-02T15:35:47.191Z').getSymbol('NZD', 'en-NZ');
// $
```

### `getMinorUnitDigits`

```ts
currency('2023-11-02T15:35:47.191Z').getMinorUnitDigits('USD');
// 2

currency('2023-11-02T15:35:47.191Z').getMinorUnitDigits('JPY');
// 0
```

### `findCurrency`

```ts
currency('2023-11-02T15:35:47.191Z').findCurrency('us dollar');
// {
//   name: 'US Dollar',
//   alphabeticCode: 'USD',
//   numericCode: '840',
//   minorUnits: 2
// }

currency('2023-11-02T15:35:47.191Z').findCurrency(554);
// {
//   name: 'New Zealand Dollar',
//   alphabeticCode: 'NZD',
//   numericCode: '554',
//   minorUnits: 2
// }
```

### `getCurrency`

```ts
currency('2023-11-02T15:35:47.191Z').getCurrency('840');
// {
//   name: 'US Dollar',
//   alphabeticCode: 'USD',
//   numericCode: '840',
//   minorUnits: 2
// }

currency('2023-11-02T15:35:47.191Z').getCurrency('NZD');
// {
//   name: 'New Zealand Dollar',
//   alphabeticCode: 'NZD',
//   numericCode: '554',
//   minorUnits: 2
// }
```

### `getCountry`

```ts
currency('2023-11-02T15:35:47.191Z').getCountry('USA');
// {
//   name: 'US',
//   alpha2: 'US',
//   alpha3: 'USA',
//   numeric: '840',
//   currencyCodes: [ 'USD' ]
// }
```

### `getCountriesForCurrency`

```ts
currency('2023-11-02T15:35:47.191Z').getCountriesForCurrency('NZD');
// [ 'COK', 'NIU', 'NZL', 'PCN', 'TKL' ]
```

## 许可证

麻省理工学院

## 常见问题

### @checkdigit/currency 是什么？

标准货币处理

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

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

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

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

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

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

### @checkdigit/currency 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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