# @financica/iso4217 中文文档

规范地址：https://npmcn.com/package/%40financica/iso4217/

版本：0\.2\.0
npm 元数据更新时间：2026-08-17T23:47:41.882Z
中文译文更新时间：2026-11-14T18:26:41.168Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40financica/iso4217
原文对照：https://npmcn.com/package/%40financica/iso4217/?lang=original
项目主页：https://github.com/financica/ts-libs/tree/main/packages/iso4217#readme
源码仓库：https://github.com/financica/ts-libs

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

- 包体积（解压后）：496 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-08-03T00:44:42.080Z
- 最新版本发布：2026-08-17T23:47:41.728Z
- 近 30 天下载量：109758（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

ISO 4217货币代码,数字代码,小单位,以及实体——完全打入,零依赖,O(1)取出.

## 安装

```sh
npm install @financica/iso4217
```

也可以使用：`pnpm add @financica/iso4217`、`yarn add @financica/iso4217`、`bun add @financica/iso4217`

## README

# @ financica/iso4217 (英语)

严格打入,零依赖性 ISO 4217 货币数据集与 O(1)取景.

由六局集团官方制造 `list-one.xml`编辑 `2026-01-01`数字 : 字母代码,数字代码,小单位,名称,基金旗和种类. 国家 关联是ISO 3166-1 alpha-2代码,从不透明的名称字符串. 每个 代码是一个字面结合,所以编译器告诉 `"USD"` 从 `"usd"` 财务报告和审定财务报表 `"US"` 从 `"USA"`。所有导出的数据是 `Object.freeze`d 每个阵列是 `readonly`. 船舶无害环境管理+CJS和树摇杆.

将货币撤回到1970年代的船上 `/historic` 子路径.

## 安装

```sh
npm install @financica/iso4217
```

需要24号节点.

## 使用量

```ts
import {
    getByCode,
    getByNumericCode,
    getByCountry,
    formatAmount,
    CURRENCIES,
    PUBLISHED_AT,
} from "@financica/iso4217";

getByCode("USD");
// → {
//     alphabeticCode: "USD",
//     numericCode: "840",
//     minorUnits: 2,
//     name: "US Dollar",
//     countryCodes: ["AS", "BQ", "EC", "GU", "HT", "IO", "MH", "MP", "PA",
//                    "PR", "PW", "SV", "TC", "TL", "UM", "US", "VG", "VI"],
//     isFund: false,
//     kind: "fiat",
//   }

getByCode("usd")?.alphabeticCode; // "USD"  — case-insensitive
getByNumericCode("840")?.alphabeticCode; // "USD"
getByNumericCode(840)?.alphabeticCode; // "USD"
getByNumericCode(8)?.alphabeticCode; // "ALL" — unpadded input is normalised

getByCountry("CH").map((c) => c.alphabeticCode);
// ["CHE", "CHF", "CHW"]

formatAmount(1234.5, "USD", { locale: "en-US" }); // "$1,234.50"
formatAmount(1234.5, "JPY", { locale: "en-US" }); // "¥1,235"     (0 minor units)
formatAmount(1.5, "BHD", { locale: "en-US" }); // "BHD 1.500"  (3 minor units)

CURRENCIES.length; // 178 (as of 2026-01-01)
PUBLISHED_AT; // "2026-01-01"
```

### 类型警卫

```ts
import { isAlphabeticCode, isNumericCode, isCountryCode } from "@financica/iso4217";

function logCurrency(code: string) {
    if (!isAlphabeticCode(code)) return;
    // `code` is now narrowed to AlphabeticCode.
    console.log(getByCode(code)?.name);
}
```

### 历史货币

退出货币(意大利里拉、扎伊尔、荷兰安的列斯) Guilder等)生活在子路径导入后,以免被挤出主通道 捆绑.

```ts
import { getHistoricByCode, HISTORIC_CURRENCIES } from "@financica/iso4217/historic";

getHistoricByCode("ANG").map((c) => c.withdrawalDate);
// ["2010-10", "2025-03"]  — ANG was withdrawn twice.
```

## API 密码

### 查询

| 函数 | 回返 |
| --- | --- |
| `getByCode(code: string)` | `Currency | undefined` |
| `getByNumericCode(code: string | number)` | `Currency | undefined` |
| `getByCountry(countryCode: string)` | `readonly Currency[]` (可能为空) |

### 类型警卫

| 函数 | 签署 |
| --- | --- |
| `isAlphabeticCode(s)` | `s is AlphabeticCode` |
| `isNumericCode(s)` | `s is NumericCode` |
| `isCountryCode(s)` | `s is CountryCode` |

### 格式化

| 函数 | 签署 |
| --- | --- |
| `formatAmount(amount, code, options?)` | `string` (包装) `Intl.NumberFormat`(中文(简体) ) |

Frede的小单位分类不是ISO 4217(例如. `UGX`, (中文(简体) ), `ISK`, (中文(简体) ), `HUF`;对于跨越斯德莱克边界的金额,请使用助手在 [`@financica/stripe-hosted-invoices`](https://npmcn.com/package/%40financica/stripe-hosted-invoices/README.md#money)。 。 。 .

### 数据

| 导出 | 形状 |
| --- | --- |
| `CURRENCIES` | `readonly Currency[]` ——按字母代码排序 |
| `ALPHABETIC_CODES` | `readonly AlphabeticCode[]` |
| `NUMERIC_CODES` | `readonly NumericCode[]` |
| `COUNTRY_CODES` | `readonly CountryCode[]` (ISO 3166-1 α-2联盟) |
| `PUBLISHED_AT` | `"YYYY-MM-DD"` 嵌入式六X组修改日期 |

### 类型

```ts
interface Currency {
    readonly alphabeticCode: AlphabeticCode; // e.g. "USD"
    readonly numericCode: NumericCode; // e.g. "840"
    readonly minorUnits: number | null; // null for metals and N.A. codes
    readonly name: string;
    readonly countryCodes: readonly CountryCode[];
    readonly isFund: boolean;
    readonly kind: "fiat" | "fund" | "metal" | "special";
}

type CurrencyKind = "fiat" | "fund" | "metal" | "special";
```

`kind` 每个条目的分类:

-   **`fiat`** 主权货币或超国家一般招标货币 (美元、欧元、英镑、自动取款机、XOF、XCD、XCG、XPF、.).
-   **`fund`** 会计/投资单位(CHE、CHW、BOV、CLF、COU、MXV, (原始内容存档于2017-10-10). USN, UYI, UYW.
-   **`metal`** ——贵金属商品代码(XAU,XAG,XPT,XPD).
-   **`special`** ——保留代码:债券单位(XBAQBD),货币基金组织特别提款权(XDR), 亚行单位(XUA)、Sucre(XSU)、阿拉伯会计第纳尔(XAD)、测试(XTS)、, 无货币信使(XXX).

## 数据来源

数据来自SIX Group XML的两个官方列表:

-   `list-one.xml` 活性货币
-   `list-three.xml` ——历史货币/已提取货币

两者都被下载到 `data/` 以 `bun run fetch-data`。 。 。 . `bun run generate` 然后将 XML 重新分割, 将实体行正常化为 ISO 3166-1 alpha-2 国家 代码(通过绘图) `scripts/iso-3166.ts`),并释放出三个 生成源文件于 `src/`数字 :

-   `src/codes.ts`
-   `src/data.ts`
-   `src/historic-data.ts`

生成器在它不知道如何映射的任何实体名称上投放, 所以新的 或者在上游列表中重新命名的国家失败了建设,而不是默默无闻 放弃协会.

## 重新印发新的修订本

1.  `bun run fetch-data`
2.  `bun run generate`
3.  审查 `git diff src/`
4.  `bun run test`
5.  按 [仓库读取器](https://npmcn.com/package/README.md#releasing)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @financica/iso4217 是什么？

ISO 4217货币代码,数字代码,小单位,以及实体——完全打入,零依赖,O\(1\)取出\.

### 如何安装 @financica/iso4217？

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

### @financica/iso4217 支持 TypeScript 吗？

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

### @financica/iso4217 支持 ESM 还是 CommonJS？

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

### @financica/iso4217 需要什么版本的 Node\.js？

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

### @financica/iso4217 可以商用吗？

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

### @financica/iso4217 的下载量有多少？

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

### @financica/iso4217 还在维护吗？

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