让开源，少一点语言距离。
npm包中文文档

@dfinity/utils

中文文档
5.0.0发布于 2026/09/22Apache-2.0TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 6.6万

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

中文使用文档
中文原文
文档目录12 节
  1. 目录
  2. 安装
  3. 特征
  4. :工具箱:函数
  5. :扳手:常数
  6. : 构件: 托克纳蒙
  7. : 构件: 托克纳蒙V2
  8. : 构件:罐头
  9. : 要素:代理经理
  10. : 构件: 无效百分比错误
  11. : factory: Nullish Error (英语)
  12. : nut 并 bolt: enum

乌特尔斯 -js

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

npm version GitHub license

目录

安装

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

npm i @dfinity/utils

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

npm i @icp-sdk/core

特征

utils-js 执行以下特性:

:工具箱:函数

: 齿轮: 转换 StringToE8s

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

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

参数:

  • amount: - 以字符串格式

回返情况:

从 String Totoken 错误

:link:出处

: 齿轮: 是 Nullish

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

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

参数:

  • argument:——要检查的论据.

回返情况:

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

:link:出处

: gear: 非 Nullish 语言

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

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

参数:

  • argument:——要检查的论据.

回返情况:

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

:link:出处

: gear: 不是EmptyString 游戏

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

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

参数:

  • value: - 要检查的值 .

回返情况:

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

:link:出处

: gear: isEmptyString (英语)

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

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

参数:

  • value: - 要检查的值 .

回返情况:

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

:link:出处

: 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:出处

: gear: 默认代理

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

函数类型
defaultAgent() => Agent

回返情况:

要使用的默认代理

:link:出处

: gear: 创建代理

为给定身份创建代理

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

参数:

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

:link:出处

: 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:出处

: gear: 断言无语言

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

:link:出处

: 齿轮: 作为 NNullish

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

:link:出处

: 工具:断言

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

:link:出处

: gear: 断言永远不要

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

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

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

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

参数:

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

:link:出处

: gear: uint8 ArrayTo BigInt

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

:link:出处

: gear: 大进取取取 8 箭头

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

:link:出处

: gear: 数字 ToUint8 箭头

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

:link:出处

: gear: 阵列BufferToUint8 箭头

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

:link:出处

: gear: uint8 箭头图数

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

:link:出处

: gear: Number ToUint8 阵列

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

:link:出处

: gear: ascii String ToByte 箭头

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

:link:出处

: 齿轮: 六进制 TOUINT8 箭头

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

:link:出处

: gear: uint8 箭头平方

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

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

参数:

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

回返情况:

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

:link:出处

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

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

:link:出处

: gear: 坦率的数字箭头

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

:link:出处

: gear: 编码Base32

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

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

参数:

  • input: 编码的输入数组.

回返情况:

输入的 Base32 字符串编码 .

:link:出处

: gear: 解码Base32

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

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

参数:

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

:link:出处

: 齿轮: uint8 ArrayToBase64

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

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

参数:

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

回返情况:

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

:link:出处

: gear: base64 ToUint8 箭头

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

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

参数:

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

回返情况:

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

:link:出处

: 齿轮: BigEndianCrc32

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

:link:出处

: 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:出处

: 齿轮: jsonReviver

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

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

支持的转换 :

  • { "__bigint__": string } → BigInt
  • { "__principal__": string } → Principal
  • { "__uint8array__": number[] } → Uint8Array
函数类型
jsonReviver(_key: string, value: unknown) => unknown

参数:

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

回返情况:

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

:link:出处

: 工具:散列对象

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

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

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

参数:

  • params: - 散列对象.

回返情况:

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

:link:出处

: gear: 散列图文

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

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

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

参数:

  • text: - 文本为散列.

回返情况:

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

:link:出处

: 齿轮: 秒

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

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

参数:

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

回返情况:

人可读取的时间弦.

:link:出处

: gear: 现在的InBigIntNanoseconds

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

函数类型
nowInBigIntNanoSeconds() => bigint

回返情况:

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

:link:出处

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

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

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

参数:

  • date- 那个 Date 对象转换.

回返情况:

时间戳在纳秒.

:link:出处

: 弹出

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

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

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

参数:

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

回返情况:

被解除的原功能版本 .

:link:出处

: 齿轮: 直取

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

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

参数:

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

回返情况:

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

:link:出处

: 齿轮: 从 Nullable

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

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

参数:

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

回返情况:

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

:link:出处

: 齿轮: 从定义Nullable

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

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

参数:

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

回返情况:

所取出值.

:link:出处

: 齿轮:取自 NullishNullable

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

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

参数:

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

回返情况:

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

:link:出处

: gear: 主子账户

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

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

参数:

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

:link:出处

: 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:出处

:扳手:常数

:齿轮: E8S PER TOKEN

常数类型
E8S_PER_TOKENbigint

:link:出处

: gear: 比较方案托肯

常数类型
ICPTokenToken

:link:出处

: 构件: 托克纳蒙

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

代表一个代币.

:link:出处

静态方法

: 齿轮: 从 E8s

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

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

参数:

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

:link:出处

: 齿轮: 从 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:出处

: gear: 从数字

从数字初始化.

1 整数被认为是 E8S PER TOKEN

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

参数:

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

:link:出处

方法

: 齿轮: toE8s
方法类型
toE8s() => bigint

回返情况:

E8的数量.

:link:出处

: 构件: 托克纳蒙V2

代表一个代币.

:link:出处

静态方法

: 齿轮: 从Ulps

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

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

参数:

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

:link:出处

: 齿轮: 从 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:出处

: gear: 从数字

从数字初始化.

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

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

参数:

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

:link:出处

方法

: 齿轮: toUlps
方法类型
toUlps() => bigint

回返情况:

口浆之多.

:link:出处

: 齿轮: toE8s
方法类型
toE8s() => bigint

回返情况:

E8s精度的硫磺数量

:link:出处

: 构件:罐头

:link:出处

: 要素:代理经理

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

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

:link:出处

静态方法

: gear: 创建

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

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

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

参数:

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

回返情况:

一个新的实例 AgentManager。 。 。 .

:link:出处

方法

: gear: 获取代理

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

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

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

参数:

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

回返情况:

与给定身份相关的HttpAgent.

:link:出处

: 齿轮: 清除代理

清除 HTTP 代理的缓存 .

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

方法类型
clearAgents() => void

:link:出处

: 构件: 无效百分比错误

:link:出处

: factory: Nullish Error (英语)

:link:出处

: nut 并 bolt: enum

: gear: 从 String Totoken 错误

财产类型说明
FractionalMoreThan8Decimals``
InvalidFormat``
FractionalTooManyDecimals``

:link:出处

版本与发布记录

@dfinity/utils 共发布 1,054 个版本，首次发布于 2022/08/05；过去 12 个月发布了 34 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.0latest2026/09/221 个月前
4.2.1-next-2026-04-21.1next2026/04/216 个月前
4.2.1-next-2026-04-212026/04/216 个月前
4.2.1-next-2026-04-202026/04/216 个月前
4.0.3patch2026/03/257 个月前
4.2.12026/03/247 个月前

其他发布通道：nightly → 0.0.1-nightly-2022-08-08.1，beta → 4.0.2-beta-2025-12-18，patch → 4.0.3，next → 4.2.1-next-2026-04-21.1。

关于 @dfinity/utils 的常见问题

@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 和提交记录判断。