# @dfinity/utils 中文文档

规范地址：https://npmcn.com/package/%40dfinity/utils/

版本：5\.0\.0
npm 元数据更新时间：2026-10-05T08:13:11.444Z
中文译文更新时间：2026-11-12T05:23:33.481Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：229 kB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@icp-sdk/core ^6
- 首次发布：2022-08-05T08:42:20.656Z
- 最新版本发布：2026-09-22T07:52:55.318Z
- 近 30 天下载量：66056（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：1054（近 12 个月 34 个）

## 中文简介

为NNS/SNS项目收集的公用事业和常数.

## 安装

```sh
npm install @dfinity/utils
```

也可以使用：`pnpm add @dfinity/utils`、`yarn add @dfinity/utils`、`bun add @dfinity/utils`

## README

# 乌特尔斯 -js

为NNS/SNS项目收集的公用事业和常数.

[![npm version](https://img.shields.io/npm/v/@dfinity/utils.svg?logo=npm)](https://www.npmjs.com/package/@dfinity/utils) [![GitHub license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

## 目录

-   [安装](https://npmcn.com/package/%40dfinity/utils/#readme-installation)
-   [特征](https://npmcn.com/package/%40dfinity/utils/#readme-features)

## 安装

你用得着 `utils-js` 在您的工程中安装它.

```bash
npm i @dfinity/utils
```

捆绑需要同伴的依赖关系, 请确定您的项目中也提供后续资源 .

```bash
npm i @icp-sdk/core
```

## 特征

`utils-js` 执行以下特性:

### :工具箱:函数

-   [转换 StringToE8s](https://npmcn.com/package/%40dfinity/utils/#readme-gear-convertstringtoe8s)
-   [是 Nullish 语](https://npmcn.com/package/%40dfinity/utils/#readme-gear-isnullish)
-   [非波兰语](https://npmcn.com/package/%40dfinity/utils/#readme-gear-nonnullish)
-   [非状态](https://npmcn.com/package/%40dfinity/utils/#readme-gear-notemptystring)
-   [是时态](https://npmcn.com/package/%40dfinity/utils/#readme-gear-isemptystring)
-   [查询和更新日期](https://npmcn.com/package/%40dfinity/utils/#readme-gear-queryandupdate)
-   [默认代理](https://npmcn.com/package/%40dfinity/utils/#readme-gear-defaultagent)
-   [创建代理](https://npmcn.com/package/%40dfinity/utils/#readme-gear-createagent)
-   [创建服务](https://npmcn.com/package/%40dfinity/utils/#readme-gear-createservices)
-   [主张无语言](https://npmcn.com/package/%40dfinity/utils/#readme-gear-assertnonnullish)
-   [作为无语言](https://npmcn.com/package/%40dfinity/utils/#readme-gear-asnonnullish)
-   [百分比](https://npmcn.com/package/%40dfinity/utils/#readme-gear-assertpercentagenumber)
-   [坚持永不](https://npmcn.com/package/%40dfinity/utils/#readme-gear-assertnever)
-   [uint8 箭头到大号](https://npmcn.com/package/%40dfinity/utils/#readme-gear-uint8arraytobigint)
-   [大进取取取取取取取取取取取取取取出](https://npmcn.com/package/%40dfinity/utils/#readme-gear-biginttouint8array)
-   [数字 ToUint8 箭头](https://npmcn.com/package/%40dfinity/utils/#readme-gear-numbertouint8array)
-   [阵列缓冲器 TOUint8 箭头](https://npmcn.com/package/%40dfinity/utils/#readme-gear-arraybuffertouint8array)
-   [金特8 箭头到箭头数](https://npmcn.com/package/%40dfinity/utils/#readme-gear-uint8arraytoarrayofnumber)
-   [向 Uint8 数量阵列](https://npmcn.com/package/%40dfinity/utils/#readme-gear-arrayofnumbertouint8array)
-   [ascii 串联键键](https://npmcn.com/package/%40dfinity/utils/#readme-gear-asciistringtobytearray)
-   [六进制 ToUint8 箭头](https://npmcn.com/package/%40dfinity/utils/#readme-gear-hexstringtouint8array)
-   [平面图](https://npmcn.com/package/%40dfinity/utils/#readme-gear-uint8arraysequal)
-   [金特8 箭头到外层](https://npmcn.com/package/%40dfinity/utils/#readme-gear-uint8arraytohexstring)
-   [直线数字箭头](https://npmcn.com/package/%40dfinity/utils/#readme-gear-candidnumberarraytobigint)
-   [编码Base32](https://npmcn.com/package/%40dfinity/utils/#readme-gear-encodebase32)
-   [解码Base32](https://npmcn.com/package/%40dfinity/utils/#readme-gear-decodebase32)
-   [uint8 箭头TOBase64](https://npmcn.com/package/%40dfinity/utils/#readme-gear-uint8arraytobase64)
-   [基数64 到 Unint8 箭头](https://npmcn.com/package/%40dfinity/utils/#readme-gear-base64touint8array)
-   [大Endians Crc32 数据](https://npmcn.com/package/%40dfinity/utils/#readme-gear-bigendiancrc32)
-   [json 替换器](https://npmcn.com/package/%40dfinity/utils/#readme-gear-jsonreplacer)
-   [jsonReviver 编辑器](https://npmcn.com/package/%40dfinity/utils/#readme-gear-jsonreviver)
-   [散列对象](https://npmcn.com/package/%40dfinity/utils/#readme-gear-hashobject)
-   [散列图文](https://npmcn.com/package/%40dfinity/utils/#readme-gear-hashtext)
-   [秒长度](https://npmcn.com/package/%40dfinity/utils/#readme-gear-secondstoduration)
-   [现在的InBigIntNanoseconds](https://npmcn.com/package/%40dfinity/utils/#readme-gear-nowinbigintnanoseconds)
-   [转到 BigIntNano Seconds](https://npmcn.com/package/%40dfinity/utils/#readme-gear-tobigintnanoseconds)
-   [弹跳](https://npmcn.com/package/%40dfinity/utils/#readme-gear-debounce)
-   [直肠](https://npmcn.com/package/%40dfinity/utils/#readme-gear-tonullable)
-   [从 Nullable 调用](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromnullable)
-   [从定义Nullable](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromdefinednullable)
-   [从 NullishNullable 读取](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromnullishnullable)
-   [主子账户](https://npmcn.com/package/%40dfinity/utils/#readme-gear-principaltosubaccount)
-   [小维](https://npmcn.com/package/%40dfinity/utils/#readme-gear-smallerversion)

#### : 齿轮: 转换 StringToE8s

接收代表数字的字符串并返回大输入或出错.

| 函数 | 类型 |
| --- | --- |
| `convertStringToE8s` | `(value: string) => bigint or FromStringToTokenError` |

参数:

-   `amount`: - 以字符串格式

回返情况:

从 String Totoken 错误

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L12)

#### : 齿轮: 是 Nullish

检查给定的参数是无效还是未定义 .

| 函数 | 类型 |
| --- | --- |
| `isNullish` | `<T>(argument: T or null or undefined) => argument is null or undefined` |

参数:

-   `argument`:——要检查的论据.

回返情况:

`true` 如果论据无效或未定义;否则, `false`。 。 。 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/nullish.utils.ts#L8)

#### : gear: 非 Nullish 语言

检查给定的参数是否既不是无效也不是未定义 .

| 函数 | 类型 |
| --- | --- |
| `nonNullish` | `<T>(argument: T or null or undefined) => argument is NonNullable<T>` |

参数:

-   `argument`:——要检查的论据.

回返情况:

`true` 如果论据不是无效或未定义;否则, `false`。 。 。 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/nullish.utils.ts#L19)

#### : gear: 不是EmptyString 游戏

检查一个给定的值是否不是无效的,不是未定义的,也不是空字符串.

| 函数 | 类型 |
| --- | --- |
| `notEmptyString` | `(value: string or null or undefined) => value is string` |

参数:

-   `value`: - 要检查的值 .

回返情况:

`true` 如果值不是无效的,不是未定义的,也不是空字符串;否则, `false`。 。 。 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/nullish.utils.ts#L29)

#### : gear: isEmptyString (英语)

检查一个给定的值是无效的、未定义的还是空的字符串 .

| 函数 | 类型 |
| --- | --- |
| `isEmptyString` | `(value: string or null or undefined) => value is "" or null or undefined` |

参数:

-   `value`: - 要检查的值 .

回返情况:

键入上游表示该值是否为无效、未定义或为空字符串.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/nullish.utils.ts#L39)

#### : gear: 查询并更新日期

该服务执行查询(未经认证)呼叫和/或更新(经认证)呼叫,并处理结果.

之所以有用,是因为出于安全原因,它可以发出这两种呼吁. 例如,恶意节点在调用索引罐时可以伪造交易和平衡,如果不进行更新来验证结果.

此外,它还能够以不同方式处理这些呼吁的结果:

-   `query` 只执行查询呼叫.
-   `update` 只执行更新呼叫.
-   `query_and_update` 执行两个电话.

决议可以是:

-   `all_settled` 等一切叫唤安住.
-   `race` 等待初次召唤, `query` 这是最快的.

呼叫完成后,由 `onLoad` 调用. 然而,如果发生错误,则由错误回调处理,如果提供的话:一个用于查询呼叫,一个用于更新呼叫. 如果没有为更新呼叫提供错误回调,则错误会被登录到控制台.

| 函数 | 类型 |
| --- | --- |
| `queryAndUpdate` | `<R, E = unknown>({ request, onLoad, onQueryError, onUpdateError, strategy, identity, resolution, }: QueryAndUpdateParams<R, E>) => Promise<void>` |

参数:

-   `params`: 执行请求的参数.
-   `params.request`: 执行请求.
-   `params.onLoad`: 处理请求响应的回调.
-   `params.onQueryError`: 处理错误的回调 `query` 请求.
-   `params.onUpdateError`: 处理错误的回调 `update` 请求.
-   `params.strategy`:要使用的战略. 默认是 `query_and_update`。 。 。 .
-   `params.identity`:用于请求的身份.
-   `params.resolution`:要使用的决议. 默认是 `race`。 。 。 .

回返情况:

一份承诺,当请求完成后就能解决.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/services/query.ts#L37)

#### : gear: 默认代理

获得一个以匿名身份连接主网的默认代理.

| 函数 | 类型 |
| --- | --- |
| `defaultAgent` | `() => Agent` |

回返情况:

要使用的默认代理

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/agent.utils.ts#L14)

#### : gear: 创建代理

为给定身份创建代理

| 函数 | 类型 |
| --- | --- |
| `createAgent` | `({ identity, host, fetchRootKey, verifyQuerySignatures, retryTimes, }: CreateAgentParams) => Promise<HttpAgent>` |

参数:

-   `params`: 创建新 HTTP 代理的参数
-   `params.identity`: 代理人必须使用的身份
-   `params.host`: 可选主机,可连接,特别是对地方发展有用
-   `params.fetchRootKey`: 在本地开发或测试网中获取证书验证的根密钥
-   `params.verifyQuerySignatures`: 检查由回答询问的节点所签名的状态树上的签名——即认证回复.
-   `params.retryTimes`: 设置代理机在出错前应当执行的重试次数.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/agent.utils.ts#L30)

#### : gear: 创建服务

| 函数 | 类型 |
| --- | --- |
| `createServices` | `<T>({ options: { canisterId, serviceOverride, certifiedServiceOverride, agent: agentOption, callTransform, queryTransform, }, idlFactory, certifiedIdlFactory, }: { options: Required<Pick<CanisterOptions<T>, "canisterId">> and Omit<CanisterOptions<T>, "canisterId"> and Pick<...>; idlFactory: IDL.InterfaceFactory; certifi...` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/actor.utils.ts#L17)

#### : gear: 断言无语言

| 函数 | 类型 |
| --- | --- |
| `assertNonNullish` | `<T>(value: T, message?: string or undefined) => asserts value is NonNullable<T>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/asserts.utils.ts#L4)

#### : 齿轮: 作为 NNullish

| 函数 | 类型 |
| --- | --- |
| `asNonNullish` | `<T>(value: T, message?: string or undefined) => NonNullable<T>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/asserts.utils.ts#L18)

#### : 工具:断言

| 函数 | 类型 |
| --- | --- |
| `assertPercentageNumber` | `(percentage: number) => void` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/asserts.utils.ts#L23)

#### : gear: 断言永远不要

在 TypeScript 中执行详尽无遗检查的功能 .

此项职能只应在 `switch` 或有条件 如果工会类型已经得到充分处理,那就无法实现.

输入参数为 `never`,如果 结合中增加了一个新的变体,但不包含在逻辑中.

| 函数 | 类型 |
| --- | --- |
| `assertNever` | `(_: never, message?: string or undefined) => never` |

参数:

-   `_`: - 应该是类型值 `never`如果不是这样的话, typeScript 编译器将标记一个类型错误.
-   `message`: - 可选自定义错误消息, 包含在所抛错误中 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/asserts.utils.ts#L47)

#### : gear: uint8 ArrayTo BigInt

| 函数 | 类型 |
| --- | --- |
| `uint8ArrayToBigInt` | `(array: Uint8Array<ArrayBufferLike>) => bigint` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L3)

#### : gear: 大进取取取 8 箭头

| 函数 | 类型 |
| --- | --- |
| `bigIntToUint8Array` | `(value: bigint) => Uint8Array<ArrayBufferLike>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L14)

#### : gear: 数字 ToUint8 箭头

| 函数 | 类型 |
| --- | --- |
| `numberToUint8Array` | `(value: number) => Uint8Array<ArrayBufferLike>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L30)

#### : gear: 阵列BufferToUint8 箭头

| 函数 | 类型 |
| --- | --- |
| `arrayBufferToUint8Array` | `(buffer: ArrayBuffer) => Uint8Array<ArrayBufferLike>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L39)

#### : gear: uint8 箭头图数

| 函数 | 类型 |
| --- | --- |
| `uint8ArrayToArrayOfNumber` | `(array: Uint8Array<ArrayBufferLike>) => number[]` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L42)

#### : gear: Number ToUint8 阵列

| 函数 | 类型 |
| --- | --- |
| `arrayOfNumberToUint8Array` | `(numbers: number[]) => Uint8Array<ArrayBufferLike>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L45)

#### : gear: ascii String ToByte 箭头

| 函数 | 类型 |
| --- | --- |
| `asciiStringToByteArray` | `(text: string) => number[]` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L48)

#### : 齿轮: 六进制 TOUINT8 箭头

| 函数 | 类型 |
| --- | --- |
| `hexStringToUint8Array` | `(hexString: string) => Uint8Array<ArrayBufferLike>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L51)

#### : gear: uint8 箭头平方

比较两个 Uint8 箭头来表示字节级的平等 .

| 函数 | 类型 |
| --- | --- |
| `uint8ArraysEqual` | `({ a, b }: { a: Uint8Array<ArrayBufferLike>; b: Uint8Array<ArrayBufferLike>; }) => boolean` |

参数:

-   `params.a`: - 第一个Uint8箭头比较.
-   `params.b`: - 第二个Uint8箭头来作比较.

回返情况:

如果两个阵列的长度和内容相同,则为真.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L67)

#### : 齿轮: 取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取

| 函数 | 类型 |
| --- | --- |
| `uint8ArrayToHexString` | `(bytes: Uint8Array<ArrayBufferLike> or number[]) => string` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L70)

#### : gear: 坦率的数字箭头

| 函数 | 类型 |
| --- | --- |
| `candidNumberArrayToBigInt` | `(array: number[]) => bigint` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/arrays.utils.ts#L80)

#### : gear: 编码Base32

将一个 Uint8Array 编码为 Base32 字符串 .

| 函数 | 类型 |
| --- | --- |
| `encodeBase32` | `(input: Uint8Array<ArrayBufferLike>) => string` |

参数:

-   `input`: 编码的输入数组.

回返情况:

输入的 Base32 字符串编码 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/base32.utils.ts#L21)

#### : gear: 解码Base32

将一个碱基32字符串解码为Uint8Array.

| 函数 | 类型 |
| --- | --- |
| `decodeBase32` | `(input: string) => Uint8Array<ArrayBufferLike>` |

参数:

-   `input`: 解码的输入字符串.
-   `input`: Base32 编码字符串来解码.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/base32.utils.ts#L67)

#### : 齿轮: uint8 ArrayToBase64

将一个Uint8Array(二进制数据)转换为基数64编码字符串.

| 函数 | 类型 |
| --- | --- |
| `uint8ArrayToBase64` | `(uint8Array: Uint8Array<ArrayBufferLike>) => string` |

参数:

-   `uint8Array`: - 包含二进制数据的Uint8Array被编码.

回返情况:

-   Base64编码了二进制数据的字符串表示.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/base64.utils.ts#L7)

#### : gear: base64 ToUint8 箭头

将一个已编码的基数64字符串转换为 Uint8Array(二进制数据).

| 函数 | 类型 |
| --- | --- |
| `base64ToUint8Array` | `(base64String: string) => Uint8Array<ArrayBufferLike>` |

参数:

-   `base64String`: - Base64被编码的字符串被解码.

回返情况:

-   解码二进制数据的Uint8Array表示.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/base64.utils.ts#L25)

#### : 齿轮: BigEndianCrc32

| 函数 | 类型 |
| --- | --- |
| `bigEndianCrc32` | `(bytes: Uint8Array<ArrayBufferLike>) => Uint8Array<ArrayBufferLike>` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/crc.utils.ts#L61)

#### : gear: json 重置器

自定义替换器 `JSON.stringify` 转换非本地支持的特定类型 由 API 转换为 JSON 兼容格式.

支持的转换 :

-   `BigInt` → `{ "__bigint__": string }`
-   `Principal` → `{ "__principal__": string }`
-   `Uint8Array` → `{ "__uint8array__": number[] }`

| 函数 | 类型 |
| --- | --- |
| `jsonReplacer` | `(_key: string, value: unknown) => unknown` |

参数:

-   `_key`: - 被忽略了 (英语). 只提供API相容性.
-   `value`: - 字符串化前的转换值.

回返情况:

如果与已知类型相匹配,则转换值,否则就是原值.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/json.utils.ts#L22)

#### : 齿轮: jsonReviver

自定义复活器 `JSON.parse` 重建特定类型 从他们的 JSON 编码的表示.

这逆转了应用的转换 `jsonReplacer`,恢复原始类型.

支持的转换 :

-   `{ "__bigint__": string }` → `BigInt`
-   `{ "__principal__": string }` → `Principal`
-   `{ "__uint8array__": number[] }` → `Uint8Array`

| 函数 | 类型 |
| --- | --- |
| `jsonReviver` | `(_key: string, value: unknown) => unknown` |

参数:

-   `_key`: - 忽略但提供了API相容性.
-   `value`: - 要转换的解析值 .

回返情况:

如果与已知类型相匹配, 则重构值, 否则就是原值 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/json.utils.ts#L55)

#### : 工具:散列对象

从给定对象生成 SHA-256 散列.

对象首先使用自定义字符串 `jsonReplacer`,则 使用 SubtleCrypto API 进行散列。 由此产生的散列被还原为十六进制串.

| 函数 | 类型 |
| --- | --- |
| `hashObject` | `<T extends object>(params: T) => Promise<string>` |

参数:

-   `params`: - 散列对象.

回返情况:

保证能解决SHA -256大麻的六分之一.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/crypto.utils.ts#L14)

#### : gear: 散列图文

从纯文本字符串中生成 SHA-256 散列.

该字符串为UTF-8编码并使用SubtleCrypto API进行散列. 产生的散列作为十六进制字符串返回 .

| 函数 | 类型 |
| --- | --- |
| `hashText` | `(text: string) => Promise<string>` |

参数:

-   `text`: - 文本为散列.

回返情况:

保证能解决SHA -256大麻的六分之一.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/crypto.utils.ts#L31)

#### : 齿轮: 秒

将秒转换为人可读持续时间,如"6天10小时"

| 函数 | 类型 |
| --- | --- |
| `secondsToDuration` | `({ seconds, i18n, }: { seconds: bigint; i18n?: I18nSecondsToDuration or undefined; }) => string` |

参数:

-   `options`: - 选项对象.
-   `options.seconds`: - 转换秒数.
-   `options.i18n`: - 自定义语言和单位的i18n对象. 默认为英语.

回返情况:

人可读取的时间弦.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/date.utils.ts#L43)

#### : gear: 现在的InBigIntNanoseconds

以纳秒计返回当前时间戳 `bigint`。 。 。 .

| 函数 | 类型 |
| --- | --- |
| `nowInBigIntNanoSeconds` | `() => bigint` |

回返情况:

以纳米秒计的当前时间戳.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/date.utils.ts#L123)

#### : gear: to BigIntNanoseconds (中文(简体) )

转换给定 `Date` 以纳米秒计的时标对象 `bigint`。 。 。 .

| 函数 | 类型 |
| --- | --- |
| `toBigIntNanoSeconds` | `(date: Date) => bigint` |

参数:

-   `date`\- 那个 `Date` 对象转换.

回返情况:

时间戳在纳秒.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/date.utils.ts#L132)

#### : 弹出

创建已提供函数的已取消版本.

已取消的函数会将其执行推迟到一定时间之后 自上次援引以来已经过去。 这对限制费率很有用 用于调用某个函数(例如响应用户输入或事件).

| 函数 | 类型 |
| --- | --- |
| `debounce` | `(func: Function, timeout?: number or undefined) => (...args: unknown[]) => void` |

参数:

-   `func`: - 脱发功能. 只有在指定超时内没有新电话出现后才能拨打.
-   `timeout`: - 弹出延迟以毫秒计. 如果不提供或无效, 默认为 300 ms .

回返情况:

被解除的原功能版本 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/debounce.utils.ts#L13)

#### : 齿轮: 直取

将一个值转换为可选值的 Candid- style 变体代表.

| 函数 | 类型 |
| --- | --- |
| `toNullable` | `<T>(value?: T or null or undefined) => Nullable<T>` |

参数:

-   `value`: - 转换为 Candid 风格变体的值 .

回返情况:

一个 Candid- style 的变体表达式: 用于 `null` 财务报告和审定财务报表 `undefined` 或带有数值的数组.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/did.utils.ts#L12)

#### : 齿轮: 从 Nullable

从可选值的 Candid- style 变体代表取出值.

| 函数 | 类型 |
| --- | --- |
| `fromNullable` | `<T>(value: Nullable<T>) => T or undefined` |

参数:

-   `value`: - 一个代表可选值的Candid-style变体.

回返情况:

提取值,或 `undefined` 如果数组为空.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/did.utils.ts#L22)

#### : 齿轮: 从定义Nullable

从可选值的 Candid- style 变体代表取出值, 确保定义值。 如果数组为空或值为无效,则丢出一个错误.

| 函数 | 类型 |
| --- | --- |
| `fromDefinedNullable` | `<T>(value: Nullable<T>) => T` |

参数:

-   `value`: - 一个代表可选值的Candid-style变体.

回返情况:

所取出值.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/did.utils.ts#L34)

#### : 齿轮:取自 NullishNullable

提取无效的 Candid 风格的变体表示值.

| 函数 | 类型 |
| --- | --- |
| `fromNullishNullable` | `<T>(value: NullishNullable<T>) => T or undefined` |

参数:

-   `value`: - Candid-style变体或 `undefined`。 。 。 .

回返情况:

提取值,或 `undefined` 如果输入无效或数组为空.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/did.utils.ts#L49)

#### : gear: 主子账户

将正弦转换为 Uint8Array 32 长度 . 例如,在用 Cmc 弹筒填充周期时转换发罐ID 有用

| 函数 | 类型 |
| --- | --- |
| `principalToSubAccount` | `(principal: Principal) => Uint8Array<ArrayBufferLike>` |

参数:

-   `principal`: 需要转换为子账户的本金

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/principal.utils.ts#L8)

#### : gear: 较小的版本

如果当前版本比 minVersion 更小, 如果相等或更大, 则返回真 . 补丁版本后标记被忽略,例如: 1.0.0-β.1 被认为是等于 1.0.0.

| 函数 | 类型 |
| --- | --- |
| `smallerVersion` | `({ minVersion, currentVersion, }: { minVersion: string; currentVersion: string; }) => boolean` |

参数:

-   `params.minVersion`: 如:" 1.0.0" (中文(简体) )
-   `params.currentVersion`: 如:"2.0.0" (中文(简体) )

回返情况:

布尔

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/version.utils.ts#L34)

### :扳手:常数

-   [E8S PER TOKEN (英语)](https://npmcn.com/package/%40dfinity/utils/#readme-gear-e8s_per_token)
-   [比较方案](https://npmcn.com/package/%40dfinity/utils/#readme-gear-icptoken)

#### :齿轮: E8S PER TOKEN

| 常数 | 类型 |
| --- | --- |
| `E8S_PER_TOKEN` | `bigint` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/constants/constants.ts#L1)

#### : gear: 比较方案托肯

| 常数 | 类型 |
| --- | --- |
| `ICPToken` | `Token` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L116)

### : 构件: 托克纳蒙

堕地. 使用支持小数的TokenAmountV2 !======================.

代表一个代币.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L130)

#### 静态方法

-   [从E8s](https://npmcn.com/package/%40dfinity/utils/#readme-gear-frome8s)
-   [从 String 从](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromstring)
-   [数字](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromnumber)

##### : 齿轮: 从 E8s

从大意初始化. Bigint被认为是e8s.

| 方法 | 类型 |
| --- | --- |
| `fromE8s` | `({ amount, token, }: { amount: bigint; token: Token; }) => TokenAmount` |

参数:

-   `params.amount`: 数额以大写格式表示.
-   `params.token`: 符号类型.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L147)

##### : 齿轮: 从 String

从字符串初始化 。 接受格式:

1234567.8901 (中文(简体) ) 1'234'567.8901 (英语) 1,234,567.8901 (韩语)

| 方法 | 类型 |
| --- | --- |
| `fromString` | `({ amount, token, }: { amount: string; token: Token; }) => FromStringToTokenError or TokenAmount` |

参数:

-   `params.amount`: 以字符串格式表示的金额.
-   `params.token`: 符号类型.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L168)

##### : gear: 从数字

从数字初始化.

1 整数被认为是 E8S PER TOKEN

| 方法 | 类型 |
| --- | --- |
| `fromNumber` | `({ amount, token, }: { amount: number; token: Token; }) => TokenAmount` |

参数:

-   `params.amount`: 数字格式的金额.
-   `params.token`: 符号类型.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L198)

#### 方法

-   [toE8s 数据](https://npmcn.com/package/%40dfinity/utils/#readme-gear-toe8s)

##### : 齿轮: toE8s

| 方法 | 类型 |
| --- | --- |
| `toE8s` | `() => bigint` |

回返情况:

E8的数量.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L224)

### : 构件: 托克纳蒙V2

代表一个代币.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L236)

#### 静态方法

-   [来自Ulps](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromulps)
-   [从 String 从](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromstring)
-   [数字](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromnumber)

##### : 齿轮: 从Ulps

从大意初始化. Bigint被认为是硫磺.

| 方法 | 类型 |
| --- | --- |
| `fromUlps` | `({ amount, token, }: { amount: bigint; token: Token; }) => TokenAmountV2` |

参数:

-   `params.amount`: 数额以大写格式表示.
-   `params.token`: 符号类型.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L249)

##### : 齿轮: 从 String

从字符串初始化 。 接受格式:

1234567.8901 (中文(简体) ) 1'234'567.8901 (英语) 1,234,567.8901 (韩语)

| 方法 | 类型 |
| --- | --- |
| `fromString` | `({ amount, token, }: { amount: string; token: Token; }) => FromStringToTokenError or TokenAmountV2` |

参数:

-   `params.amount`: 以字符串格式表示的金额.
-   `params.token`: 符号类型.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L270)

##### : gear: 从数字

从数字初始化.

1 整数被认为是 10- token. 十进制 } sulps

| 方法 | 类型 |
| --- | --- |
| `fromNumber` | `({ amount, token, }: { amount: number; token: Token; }) => TokenAmountV2` |

参数:

-   `params.amount`: 数字格式的金额.
-   `params.token`: 符号类型.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L294)

#### 方法

-   [ưμ㼯A](https://npmcn.com/package/%40dfinity/utils/#readme-gear-toulps)
-   [toE8s 数据](https://npmcn.com/package/%40dfinity/utils/#readme-gear-toe8s)

##### : 齿轮: toUlps

| 方法 | 类型 |
| --- | --- |
| `toUlps` | `() => bigint` |

回返情况:

口浆之多.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L324)

##### : 齿轮: toE8s

| 方法 | 类型 |
| --- | --- |
| `toE8s` | `() => bigint` |

回返情况:

E8s精度的硫磺数量

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/parser/token.ts#L332)

### : 构件:罐头

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/services/canister.ts#L4)

### : 要素:代理经理

AgentManager类管理不同身份的 HttpAgent 实例.

它通过身份来缓存代理,以优化资源使用并避免不必要的代理创建. 提供创建新代理,取回缓存代理的功能,并在需要时清除缓存.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/agent.utils.ts#L56)

#### 静态方法

-   [创建](https://npmcn.com/package/%40dfinity/utils/#readme-gear-create)

##### : gear: 创建

静态工厂创建新代理经理实例的方法.

这种方法可以替代直接使用私人建筑师, 更方便创建实例 `AgentManager` 使用简单明了的方法.

| 方法 | 类型 |
| --- | --- |
| `create` | `(config: AgentManagerConfig) => AgentManager` |

参数:

-   `config`: - AgentManager 实例的配置选项.
-   `config.fetchRootKey`: - 是否获取证书验证的根键 .
-   `config.host`: - 要连接的宿主.

回返情况:

一个新的实例 `AgentManager`。 。 。 .

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/agent.utils.ts#L72)

#### 方法

-   [获取代理](https://npmcn.com/package/%40dfinity/utils/#readme-gear-getagent)
-   [清除代理](https://npmcn.com/package/%40dfinity/utils/#readme-gear-clearagents)

##### : gear: 获取代理

为给定身份获取或创建 HTTP 代理 .

如果指定身份的代理已创建并缓存,则从缓存中取出. 如果身份不存在代理,则创建新的代理,缓存,然后返回.

| 方法 | 类型 |
| --- | --- |
| `getAgent` | `({ identity, }: { identity: Identity; }) => Promise<HttpAgent>` |

参数:

-   `identity`: - 用来创建代理的身份.

回返情况:

与给定身份相关的HttpAgent.

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/agent.utils.ts#L85)

##### : 齿轮: 清除代理

清除 HTTP 代理的缓存 .

这种方法可以去除所有缓存的代理,在下一次请求任何身份时强制新代理创建. 当身份改变或想要重设所有活动连接时有用 .

| 方法 | 类型 |
| --- | --- |
| `clearAgents` | `() => void` |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/agent.utils.ts#L117)

### : 构件: 无效百分比错误

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/asserts.utils.ts#L1)

### : factory: Nullish Error (英语)

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/utils/asserts.utils.ts#L2)

### : nut 并 bolt: enum

-   [从 String Totoken 错误](https://npmcn.com/package/%40dfinity/utils/#readme-gear-fromstringtotokenerror)

#### : gear: 从 String Totoken 错误

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `FractionalMoreThan8Decimals` | \`\` |  |
| `InvalidFormat` | \`\` |  |
| `FractionalTooManyDecimals` | \`\` |  |

[:link:出处](https://github.com/dfinity/icp-js-canisters/tree/main/packages/utils/src/enums/token.enums.ts#L1)

## 常见问题

### @dfinity/utils 是什么？

为NNS/SNS项目收集的公用事业和常数\.

### 如何安装 @dfinity/utils？

在项目目录运行 npm install @dfinity/utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@icp-sdk/core（^6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dfinity/utils 支持 TypeScript 吗？

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

### @dfinity/utils 支持 ESM 还是 CommonJS？

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

### @dfinity/utils 可以商用吗？

@dfinity/utils 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dfinity/utils 的下载量有多少？

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

### @dfinity/utils 还在维护吗？

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