wagmi getBlockNumber获取最新区块号的核心 Action 全解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmigetBlockNumber 是 wagmi 面向以太坊应用提供的核心 Action 之一用于一次性获取当前链上最新区块的高度区块号。本文以 getBlockNumber 官方文档 为主线结合wagmi/core的源码实现、Query 层封装、React Hook 与测试用例讲解其导入方式、参数语义、返回值、底层调用链以及在实际项目中的完整用法。功能概述Action for fetching the number of the most recent block seen.getBlockNumber 的作用是获取链上最近一个已见区块的区块号。它是许多链上应用的基石判断交易确认数、估算同步进度、实现轮询式数据刷新、配合 watchBlockNumber 监听新区块等场景都会依赖这一基础数据。与 viem 的getBlockNumber对齐wagmi 的 Action 是一个异步函数返回Promisebigint。导入与基本用法从wagmi/core导入 Action 并传入由createConfig创建的配置对象即可import { getBlockNumber } from wagmi/core import { config } from ./config const blockNumber await getBlockNumber(config)示例中的config来自 config.ts 片段一个典型的配置对象如下import { createConfig, http } from wagmi/core import { mainnet, sepolia } from wagmi/core/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })不传任何额外参数时getBlockNumber 默认使用配置中的当前链由连接的 connector 决定默认取第一条链发起查询返回该链最新区块号。参数详解参数类型为GetBlockNumberParameters从wagmi/core导出import { type GetBlockNumberParameters } from wagmi/corecacheTime类型number | undefined含义缓存区块号在内存中的保留时间毫秒。在该时间窗口内相同参数的重复调用会直接命中缓存避免重复请求 RPC。import { getBlockNumber } from wagmi/core import { config } from ./config const blockNumber await getBlockNumber(config, { cacheTime: 4_000, // 缓存 4 秒 })cacheTime属于 viem 层GetBlockNumberParameters的一部分Action 实现会将除chainId之外的剩余参数即rest原样透传给 viem 的getBlockNumber因此 viem 的缓存语义被完整保留在 cacheTime 内不会重新发起 RPC 调用。合理设置该值可以在“数据实时性”与“RPC 请求频率”之间取得平衡。chainId类型config[chains][number][id] | undefined含义执行查询时使用的链 ID。默认使用当前激活的链显式传入后可强制在其他链上查询。import { getBlockNumber } from wagmi/core import { mainnet } from wagmi/core/chains import { config } from ./config const blockNumber await getBlockNumber(config, { chainId: mainnet.id, // 强制在 mainnet 上查询 })从源码看chainId被从参数中解构出来用于通过config.getClient({ chainId })获取对应链的 viem clientconst { chainId, ...rest } parameters const client config.getClient({ chainId }) const action getAction(client, viem_getBlockNumber, getBlockNumber) return action(rest)其类型约束由 ChainIdParameter 定义保证chainId必须是配置中已注册链的 ID从而在编译期杜绝传入未配置的链。返回值import { type GetBlockNumberReturnType } from wagmi/core类型bigint含义最近一个已见区块的区块号。注意返回类型是bigint而非number因为区块号可能超过 JavaScriptNumber的安全整数范围。在使用时如需转成数字显示应显式处理例如Number(blockNumber)或blockNumber.toString()。错误类型与 TanStack Query 集成import { type GetBlockNumberErrorType } from wagmi/coreGetBlockNumberErrorType继承自 viem 的错误类型见 源码RPC 错误、链不可达等场景都会反映在错误处理中。若在调用时传入onError回调或使用 React Hook 的错误字段即可拿到该类型。此外wagmi/core/query提供了配套的 Query 层导出便于与 TanStack Query 深度集成import { type GetBlockNumberData, type GetBlockNumberOptions, type GetBlockNumberQueryFnData, type GetBlockNumberQueryKey, getBlockNumberQueryKey, getBlockNumberQueryOptions, } from wagmi/core/query在 Query 层实现 中可以看到两个值得注意的设计queryKey 为[blockNumber, { ...参数 }]同一链上默认参数的查询共享同一缓存条目避免重复请求gcTime: 0区块号是高频变化数据默认不做过期缓存留存防止返回陈旧数据。对应的 测试用例 验证了默认 queryKey 为[blockNumber, {}]传入chainId: 1后 queryKey 变为[blockNumber, { chainId: 1 }]说明链 ID 会参与缓存键的区分。React HookuseBlockNumber在 React 应用中更常用的是封装好的useBlockNumberHook源码import { useBlockNumber } from wagmi function LatestBlock() { const { data: blockNumber, isPending, error } useBlockNumber({ watch: true, // 订阅新区块实时刷新 }) if (isPending) return div加载中…/div if (error) return div查询失败{error.message}/div return div最新区块号{blockNumber?.toString()}/div }useBlockNumber的核心逻辑是通过useConfig/useChainId获取当前配置与链 ID调用getBlockNumberQueryOptions生成 Query 选项后交给useQuery当watch: true时内部调用useWatchBlockNumber订阅新区块事件并通过queryClient.setQueryData(options.queryKey, blockNumber)将最新区块号写入缓存实现响应式实时更新。这种“查询 订阅写缓存”的组合让页面上的区块号始终保持最新而无需手动管理轮询定时器。底层调用链从 wagmi 到 viemgetBlockNumber 的完整调用链可概括为wagmi getBlockNumber(config, params) └─ config.getClient({ chainId }) // 获取对应链的 viem client └─ getAction(client, viem_getBlockNumber, getBlockNumber) └─ viem 的 getBlockNumber // 实际发起 RPC 请求其中 getAction 是一个关键的桥接工具它优先读取 client 上已有的同名 action支持自定义覆盖若不存在则回退到树摇tree-shakable的 viem action 实现。这意味着即使项目对 client 做了扩展或覆盖getBlockNumber 也能拿到正确的实现。核心 Action 测试 通过await expect(getBlockNumber(config)).resolves.toBeDefined()验证了在真实测试链配置下默认调用能成功返回区块号。与 viem 的关系wagmi 的 getBlockNumber 与 viem 的公开 Action 一一对应可直接查阅 viem 侧的文档深入理解其实现细节viem 的getBlockNumber单次查询最新区块号viem 的watchBlockNumber监听并持续回调最新区块号是useBlockNumber({ watch: true })的底层基础。实战小结一次性查询await getBlockNumber(config, { chainId })适合交易确认、合约部署前的链状态检查高频轮询结合cacheTime控制 RPC 频率避免频繁请求被打限流响应式监听React 场景直接用useBlockNumber({ watch: true })自动订阅新区块并实时刷新 UI多链切换通过chainId参数在配置的多条链之间精确查询。相关源码与测试可继续查阅Action 实现、Query 层、React Hook、官方文档。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考