使用 wagmi/vue 的 useTransaction Composable 查询链上交易详情【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi导读useTransaction是wagmi/vue提供的响应式组合式函数Composable用于根据交易哈希hash或区块标识符block identifier获取链上交易详情。在 Vue 3 应用中无论是实现交易详情页、交易历史列表还是合约交互后的状态回显都可以通过它一次性获得类型安全、带缓存与自动重新获取refetch能力的交易数据。读完本文你将掌握useTransaction的全部参数与返回值语义、与底层getTransactionAction 的调用关系以及如何在真实项目中落地配置。Import引入方式在 Vue 项目中从wagmi/vue包中直接引入即可import { useTransaction } from wagmi/vueuseTransaction的类型定义UseTransactionParameters、UseTransactionReturnType同样从该包导出便于在业务代码中进行精确的类型标注。Usage基础用法最常见的用法是传入一个交易哈希Composable 会立即发起查询并在数据就绪后响应式地更新返回值script setup langts import { useTransaction } from wagmi/vue const result useTransaction({ hash: 0x0fa64daeae54e207aa98613e308c2ba8abfe274f75507e741508cc4db82c8cb5, }) /script上述示例需要项目内存在有效的 Wagmi 配置。配置方式参考 site/snippets/vue/config.ts通过createConfig创建包含chains与transports的config并经WagmiPlugin注入应用未显式传入config时useTransaction会从WagmiPlugin自动获取。模板中的使用方式由于返回值是基于 TanStack Query 的响应式结果在模板中可直接解构或访问template div v-ifresult.isPending.value加载中…/div div v-else-ifresult.isError.value查询出错/div div v-else p交易哈希{{ result.data.value?.hash }}/p p区块号{{ result.data.value?.blockNumber }}/p p发送方{{ result.data.value?.from }}/p p接收方{{ result.data.value?.to }}/p /div /templateParameters全部参数详解UseTransactionParameters类型如下import { type UseTransactionParameters } from wagmi/vuehash0x${string} | undefined要查询的交易哈希。注意当hash与index均为undefined时enabled会被自动置为false查询不会发起详见下文enabled 自动控制。script setup langts import { useTransaction } from wagmi/vue const result useTransaction({ hash: 0x0fa64daeae54e207aa98613e308c2ba8abfe274f75507e741508cc4db82c8cb5, }) /scriptblockHashbigint | undefined区块哈希需配合index使用用于获取该区块内指定位置的交易。script setup langts import { useTransaction } from wagmi/vue const result useTransaction({ blockHash: 0x4ca7ee652d57678f26e887c149ab0735f41de37bcad58c9f6d3ed5824f15b74d, index: 0, }) /scriptblockNumberbigint | undefined区块高度需配合index使用注意bigint字面量要加n后缀。script setup langts import { useTransaction } from wagmi/vue const result useTransaction({ blockNumber: 17829139n, index: 0, }) /scriptblockTaglatest | earliest | pending | safe | finalized | undefined区块标签需配合index使用。其中safe与finalized适用于支持相应概念的链如以太坊 PoS 后的安全/最终确定区块pending用于尚未打包的交易。script setup langts import { useTransaction } from wagmi/vue const result useTransaction({ blockTag: safe, index: 0, }) /scriptindexnumber | undefined与区块标识符hash、blockNumber或blockTag配合使用表示区块内的交易索引。当index与hash均为undefined时enabled自动为false。script setup langts import { useTransaction } from wagmi/vue const result useTransaction({ blockTag: safe, index: 0 }) /scriptchainIdconfig[chains][number][id] | undefined指定要查询的目标链 ID。不传时默认使用当前激活的链。适合多链应用中强制指定查询链script setup langts import { useTransaction } from wagmi/vue import { mainnet } from wagmi/chains const result useTransaction({ chainId: mainnet.id, hash: 0x0fa64daeae54e207aa98613e308c2ba8abfe274f75507e741508cc4db82c8cb5, }) /scriptconfigConfig | undefined显式传入Config以覆盖从WagmiPlugin获取的默认配置。适合在插件上下文之外使用或需要切换不同配置的场景script setup langts import { useTransaction } from wagmi/vue import { config } from ./config const result useTransaction({ hash: 0x0fa64daeae54e207aa98613e308c2ba8abfe274f75507e741508cc4db82c8cb5, config, }) /scriptqueryTanStack Query 参数用于精细控制查询行为。Wagmi 内部已占用queryFn与queryKey不允许覆盖其余参数均可使用常用项如下参数类型说明enabledboolean \| undefined设为false可禁用自动执行可用于依赖查询Dependent QueriesgcTimenumber \| Infinity \| undefined非活跃缓存保留时间默认5 * 60 * 10005 分钟SSR 期间为InfinityinitialDataTData \| (() TData) \| undefined初始缓存数据默认视为过期除非设置staleTime会被持久化到缓存networkModeonline \| always \| offlineFirst \| undefined网络模式默认onlinerefetchIntervalnumber \| false \| fn \| undefined定时自动重新获取的毫秒间隔refetchOnWindowFocusboolean \| always \| fn \| undefined窗口聚焦时是否重新获取默认trueretryboolean \| number \| fn \| undefined失败重试次数客户端默认3服务端默认0retryDelaynumber \| fn \| undefined重试延迟可配合指数退避select(data: TData) unknown \| undefined对返回数据做转换/选取不影响缓存内容staleTimenumber \| Infinity \| undefined数据过期时间默认0设为Infinity则永不过期structuralSharingboolean \| fn \| undefined查询结果间结构共享默认truenotifyOnChangePropsstring[] \| all \| fn \| undefined控制组件仅在指定属性变化时重渲染placeholderDataTData \| fn \| undefinedpending 状态下的占位数据不写入缓存metaRecordstring, unknown \| undefined附加到查询缓存条目的元信息queryClientQueryClient \| undefined自定义 QueryClient默认取最近上下文底层实现原理从 Composable 到 RPCuseTransaction的源码位于 packages/vue/src/composables/useTransaction.ts其工作流程可以拆解为三层第一层响应式参数处理const params computed(() deepUnref(parameters)) const config useConfig(params) const chainId useChainId({ config })parameters会被deepUnref深度解包因此你可以直接传入Vue 的ref/reactive响应式值如const hash ref(...)当参数变化时查询会自动重新执行这是 Vue 版本与纯核心 API 的关键差异。第二层构建 TanStack Query Optionsconst options computed(() getTransactionQueryOptions(config, { ...params.value, chainId: params.value.chainId ?? chainId.value, }), ) return useQuery(options)未显式传入chainId时会回退到useChainId提供的当前链 ID。getTransactionQueryOptions来自 packages/core/src/query/getTransaction.ts它负责生成queryKey与queryFn。第三层调用核心 Action查询函数内部调用 packages/core/src/actions/getTransaction.ts 中的getTransactionexport function getTransaction(config, parameters) { const { chainId, ...rest } parameters const client config.getClient({ chainId }) const action getAction(client, viem_getTransaction, getTransaction) return action(rest) }核心 Action 通过config.getClient({ chainId })获取对应链的 viem 客户端再委托给 viem 的getTransaction发起 RPC 请求eth_getTransactionByHash等。enabled 自动控制重点在 getTransactionQueryOptions 中enabled由参数组合决定enabled: Boolean( (options.hash || (options.index ! undefined (options.blockHash || options.blockNumber || options.blockTag))) (options.query?.enabled ?? true), )也就是说只有满足hash存在或index存在且同时给出blockHash/blockNumber/blockTag之一时查询才会自动发起否则即使调用也不会请求网络。queryFn内部对同一条件做了兜底校验不满足时抛出hash OR index AND blockHash, blockNumber, blockTag is required错误。queryKey 与缓存getTransactionQueryKey生成形如[transaction, { chainId, hash }]的查询键见 query/getTransaction.ts同一组参数共享缓存天然支持跨组件去重与缓存复用。Return Type返回值解析UseTransactionReturnType定义如下import { type UseTransactionReturnType } from wagmi/vue返回值本质是 TanStack Query 的UseQueryReturnTypeGetTransactionData, GetTransactionErrorType其中GetTransactionData即 viem 的Transaction类型并额外附加chainId字段见 core/actions/getTransaction.ts 中GetTransactionReturnType的映射逻辑。数据字段data交易对象包含hash、blockHash、blockNumber、transactionIndex、from、to、value、gas、gasPrice、input、nonce、type/typeHex、r、s、v、yParity以及 EIP-1559 特有的maxFeePerGas、maxPriorityFeePerGas和accessList等。测试快照中见 packages/vue/src/composables/useTransaction.test.ts展示了完整的返回结构示例可作为字段参考。查询状态字段字段说明data最近一次成功解析的数据默认undefinederror/failureReason错误对象 / 重试失败原因成功时为nullstatuspending \| error \| successfetchStatusfetching \| idle \| paused表示是否正在请求isPending/isError/isSuccess由status派生isFetching/isRefetching是否正在后台请求isLoading等价于isFetching isPending即首次加载中isFetched/isFetchedAfterMount是否已获取挂载后isStale缓存数据是否过期failureCount累计失败次数成功后归零dataUpdatedAt/errorUpdatedAt最近成功 / 失败时间戳refetch手动重新获取函数支持cancelRefetch、throwOnError组合使用与 TanStack Query 工具函数协作useTransaction是基于wagmi/core/query封装的因此你可以直接使用底层查询工具类型与函数同样从wagmi/vue导出见 packages/vue/src/exports/query.tsimport { type GetTransactionData, type GetTransactionOptions, type GetTransactionQueryFnData, type GetTransactionQueryKey, getTransactionQueryKey, getTransactionQueryOptions, } from wagmi/vue/query例如通过getTransactionQueryKey在组件外手动失效缓存import { useQueryClient } from tanstack/vue-query import { getTransactionQueryKey } from wagmi/vue/query const queryClient useQueryClient() // 使某个交易的查询缓存失效 queryClient.invalidateQueries({ queryKey: getTransactionQueryKey({ hash: 0x0fa6…c8cb5 }), })典型应用场景与最佳实践交易详情页以路由参数中的hash作为ref传入配合result.data渲染完整交易信息交易变化时自动重新查询。交易确认回显发送交易后拿到hash用useTransaction轮询设置refetchInterval如 3~5 秒直至data.blockNumber出现即可判断交易已被打包。按区块位置查询结合区块浏览器场景使用blockNumberindex精确定位区块内某笔交易。多链切换通过chainId参数或useChainId联动当前网络切换链时查询键自动变化并重新拉取。注意事项hash与index均为undefined时查询不会发起queryFn/queryKey由 Wagmi 内部管理不可覆盖如需在 SSR 下使用请结合cookieToInitialState等水合方案初始化查询缓存。延伸阅读对应的核心 Action 文档getTransaction其底层委托给 viem 的getTransaction配置方式createConfig 与 WagmiPlugin类型与导入TanStack Query 相关类型见 packages/core/src/query/getTransaction.tsVue 封装见 packages/vue/src/composables/useTransaction.ts测试用例packages/vue/src/composables/useTransaction.test.ts 展示了完整的返回结构快照【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考