wagmi 的 useWatchPendingTransactions Hook 完全指南在 React 中实时监听待处理交易哈希【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseWatchPendingTransactions是 wagmi React 包中用于实时监听链上待处理pending交易的响应式 Hook它会在新区块产生前捕捉进入交易池的交易哈希并回调给你的应用。本文将基于仓库中的官方文档site/react/api/hooks/useWatchPendingTransactions.md与对应源码系统讲解其导入方式、全部配置参数、底层实现原理与实战验证帮助你用它构建 mempool 监控、交易跟踪面板等实时应用。核心概念什么是待处理交易监听以太坊的交易从广播到上链之间存在一个待处理阶段交易进入节点的交易池mempool等待矿工打包。useWatchPendingTransactions的作用就是订阅这条事件流一旦检测到新的待处理交易就把交易哈希Hash[]通过回调返回给前端。该 Hook 的行为本质上是对 viem 的watchPendingTransactionsaction 的 React 封装见 packages/react/src/hooks/useWatchPendingTransactions.ts底层调用链为React Hook →wagmi/core的 watchPendingTransactions action → viem 的watchPendingTransactions。因此它的类型签名、参数语义都与 viem/core 一脉相承。Import从 wagmi 引入在你的 React 组件中直接引入即可import { useWatchPendingTransactions } from wagmiHook 与配套类型都从包根导出import { useWatchPendingTransactions, type UseWatchPendingTransactionsParameters, type UseWatchPendingTransactionsReturnType, } from wagmi基本用法监听并打印新交易最小可用示例——在组件挂载后开始监听并在有新待处理交易时打印哈希// index.tsx import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ onTransactions(transactions) { console.log(New transactions!, transactions) }, }) }需要说明的是该 Hook 依赖一个已创建的 wagmiConfig。仓库中的官方配置示例site/snippets/react/config.ts展示了标准配置写法// config.ts import { createConfig, http } from wagmi import { mainnet, sepolia } from wagmi/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })默认情况下Hook 会从最近的WagmiProvider中自动获取该ConfiguseConfig内部通过useConfig(parameters)完成注入因此只要在应用根部用WagmiProvider包裹并提供config即可无需每次显式传入。参数详解完整配置项参数类型为UseWatchPendingTransactionsParameters它是由 viem 参数、ChainIdParameterchainId与SyncConnectedChainParametersyncConnectedChain组合而成的联合类型。以下逐一说明每个配置项。batchboolean | undefined是否将每次触发时检测到的交易批量合并为一次回调。默认值为true。import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ batch: true, // 批量回调默认 onTransactions(transactions) { console.log(New transactions!, transactions) }, }) }当设置为false时每检测到一笔新交易就会单独触发一次回调。chainIdconfig[chains][number][id] | undefined指定监听哪条链上的待处理交易。不传时默认使用当前连接链的 chainIdHook 内部通过useChainId获取见 useWatchPendingTransactions.ts。import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ chainId: 1, // 只监听主网mainnet的待处理交易 onTransactions(transactions) { console.log(New transactions!, transactions) }, }) }在配置了多链如 mainnet sepolia时建议显式传入chainId以明确目标网络避免依赖连接链状态。configConfig | undefined显式指定要使用的Config覆盖从最近WagmiProvider获取的默认配置。该参数来自ConfigParameter混入类型关于Config的完整定义见 createConfig 文档。import { useWatchPendingTransactions } from wagmi import { config } from ./config function App() { useWatchPendingTransactions({ config, // 显式传入自定义 Config onTransactions(transactions) { console.log(New transactions!, transactions) }, }) }从源码看config会被解构取出config: _真正使用的配置由useConfig(parameters)决定当显式传入config时用它否则回退到 Provider 上下文中的配置。onError((error: Error) void) | undefined监听过程中抛出错误时的回调用于处理 WebSocket 断连、RPC 异常等错误场景。import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ onError(error) { console.log(Error, error) }, onTransactions(transactions) { console.log(New transactions!, transactions) }, }) }源码中onError与onTransactions一样通过 ref 保存最新引用onErrorRef确保每次渲染后回调始终指向最新闭包见 useWatchPendingTransactions.ts。onTransactions(transactions: Hash[], prevTransactions: Hash[] | undefined) void必填的核心回调当检测到新的待处理交易时被调用。参数transactions为本次新捕获的交易哈希数组prevTransactions为上一次回调收到的哈希数组可能为undefined。import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ onTransactions(transactions) { console.log(New transactions!, transactions) }, }) }从实现看若未提供onTransactionsHook 不会启动订阅if (!onTransactionsRef.current) return因此它是触发监听的前提。pollboolean | undefined是否使用轮询机制代替 WebSocket 订阅来检测新交易。默认值WebSocket Client 为false非 WebSocket Client 为true。import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ onTransactions(transactions) { console.log(New transactions!, transactions) }, poll: true, // 强制使用轮询 }) }这一默认行为在类型层面也有体现测试文件 useWatchPendingTransactions.test-d.ts 验证了当某条链使用http()传输时poll类型收窄为true | undefined而使用webSocket()传输时类型为boolean | undefined——即 HTTP 传输下轮询是唯一可行方式WebSocket 下两者皆可。pollingIntervalnumber | undefined轮询频率单位毫秒。默认值取Config的pollingInterval配置通常为 4_000ms。import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ onTransactions(transactions) { console.log(New transactions!, transactions) }, pollingInterval: 1_000, // 每秒轮询一次 }) }仅当poll: true时该参数生效若使用 WebSocket 订阅轮询间隔会被忽略。syncConnectedChainboolean | undefined是否订阅连接链变化当用户切换连接的网络时自动把监听目标切换到新链。默认值取Config[syncConnectedChain]默认开启。import { useWatchPendingTransactions } from wagmi function App() { useWatchPendingTransactions({ onTransactions(transactions) { console.log(New transactions!, transactions) }, syncConnectedChain: false, // 关闭链切换自动跟随 }) }源码级原理Hook 是如何工作的理解参数之后再看 packages/react/src/hooks/useWatchPendingTransactions.ts 的完整实现可以更清楚地把握其生命周期1. 配置与 chainId 解析const config useConfig(parameters) const configChainId useChainId({ config }) const chainId parameters.chainId ?? configChainIdchainId优先取显式传入值否则回退到当前连接链。2. 回调引用常驻ref 模式const onTransactionsRef useRef(onTransactions) const onErrorRef useRef(rest.onError) onTransactionsRef.current onTransactions onErrorRef.current rest.onError每次渲染都会把最新的回调写入 ref因此重渲染后回调始终是最新的同时 effect 依赖数组不会被回调引用污染。仓库测试 useWatchPendingTransactions.test.ts 中的 uses latest callback after rerender 用例正是验证了这一行为第一次渲染的回调收集 1 笔交易rerender替换回调后再发送交易新回调收到新交易而旧回调不再接收。3. 订阅与清理useEffect(() { if (!enabled) return if (!onTransactionsRef.current) return return watchPendingTransactions(config, { ...rest, chainId, onTransactions: (transactions) onTransactionsRef.current?.(transactions), onError: (error) onErrorRef.current?.(error), }) }, [chainId, config, enabled, rest.batch, rest.poll, rest.pollingInterval, rest.syncConnectedChain])effect 返回的清理函数会调用 core action 返回的unwatch在组件卸载、chainId 或关键参数变化时自动取消订阅避免内存泄漏。依赖数组精确列出影响订阅的参数batch、poll、pollingInterval、syncConnectedChain其余参数变化不会重建订阅。4. 底层 core action 的行为packages/core/src/actions/watchPendingTransactions.tsconst { syncConnectedChain config._internal.syncConnectedChain, ...rest } parameters通过config.getClient({ chainId })获取对应链的 viem Client并用getAction拿到 viem 的watchPendingTransactions执行真正的订阅。syncConnectedChain默认继承自 Config 内部配置当开启且未显式传入chainId时会通过config.subscribe订阅 chainId 变化在链切换时先 unwatch 旧订阅再建立新链的订阅listener函数内的if (unwatch) unwatch()。返回的unwatch函数会同时清理交易监听与链切换订阅。Return Type返回值为 voidimport { type UseWatchPendingTransactionsReturnType } from wagmi与大多数useWatch*Hook 不同useWatchPendingTransactions的返回类型是void源码中明确声明export type UseWatchPendingTransactionsReturnType void。它不返回任何状态所有结果都通过onTransactions回调向外传递——这是一个副作用型Hook与useBlockNumber这类带响应式返回值的 Hook 定位不同。若你需要在非 React 环境或命令式代码中使用相同能力可调用wagmi/core的 watchPendingTransactions action它会返回一个用于取消监听的unwatch函数。实战验证测试如何证明其行为仓库提供了两层测试来验证该 Hook 的真实行为React Hook 层useWatchPendingTransactions.test.ts连接测试连接器后renderHook发送两笔交易并mine一个区块断言onTransactions恰好收到 2 笔交易、哈希符合transactionHashRegex同时验证重渲染后使用最新回调。类型层useWatchPendingTransactions.test-d.ts对HTTP 链poll类型为true | undefined、WebSocket 链为boolean | undefined等类型约束做编译期断言保证参数类型随传输方式自动收窄。Core action 层watchPendingTransactions.test.ts验证调用unwatch()后不再收到新交易确认取消订阅确实生效。这些测试也提示了实际集成时的典型流程发送交易 → 等待监听回调 → 挖块确认可作为你编写业务代码时的参考范式。最佳实践与注意事项确保外层有WagmiProvider除非显式传入config参数否则 Hook 依赖 Provider 上下文注入的 Config请参考 WagmiProvider 文档 正确包裹应用。WebSocket 传输更实时poll默认值随传输类型变化见上文。若追求低延迟可为目标链配置webSocket()传输否则轮询模式按pollingInterval定期拉取。留意batch语义批量模式下一次回调可能携带多笔哈希适合做聚合展示逐笔模式适合逐条落库或告警。利用chainId精确定位多链应用中显式传chainId可避免因连接链切换导致监听目标漂移若希望自动跟随用户切链则保持syncConnectedChain: true默认。回调闭包陷阱已由源码解决由于内部使用 ref 保存最新回调你可以安全地在onTransactions中读取最新的 state 或 props无需手动重建 Hook。相关资源useWatchPendingTransactions 官方文档本文主体来源watchPendingTransactions core action 文档命令式用法Hook 源码实现core action 源码实现Hook 测试用例core action 测试用例配置示例【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考