企业官网建设流程全解析

wagmi showCallsStatus 动作详解：请求钱包展示 EIP-5792 调用批次状态

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi

导读

showCallsStatus是@wagmi/core提供的一个核心 Action，用于请求用户钱包在其 UI 中展示某个已通过sendCalls提交的调用批次（call batch）的状态信息。它对应以太坊 EIP-5792 中的wallet_showCallsStatusRPC 方法，是「批量交易提交 → 状态查询 → 钱包内状态展示」这一完整链路中的最后一环。读完本文，你将掌握showCallsStatus的导入方式、参数语义、返回类型、错误处理，以及它与sendCalls、getCallsStatus的配合方式，并了解其在 React 中的 Hook 封装与底层源码实现。

什么是 showCallsStatus

showCallsStatus是一个异步 Action，用于请求钱包显示某一调用批次的状态信息。这里的「调用批次」特指通过sendCalls提交的一组交易——EIP-5792 允许钱包把多笔交易打包成一个批次，返回一个批次标识符（id），而showCallsStatus则把这个 id 交还给钱包，让钱包在自身界面（如浏览器扩展或移动端）中弹出或定位到该批次的执行状态。

import { showCallsStatus } from '@wagmi/core'

与同属 EIP-5792 家族的getCallsStatus不同：getCallsStatus由 dApp 主动轮询、以编程方式获取批次的状态与收据（返回{ status: 'PENDING' | 'CONFIRMED', receipts: TransactionReceipt[] }），而showCallsStatus是把展示动作交给钱包完成，适用于用户希望「打开钱包看交易状态」的场景。

基本用法

最简单的调用方式是传入 config 与批次 id：

import { showCallsStatus } from '@wagmi/core' import { config } from './config' await showCallsStatus(config, { id: '0x1234567890abcdef', })

其中config是由createConfig创建的应用级配置对象，完整示例可参考仓库中的 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(), }, })

id来自sendCalls的返回值。sendCalls返回SendCallsReturnType（即 viem 的SendCallsReturnType），其中包含本次提交的批次标识符。在实际项目中，典型链路是：

import { sendCalls, showCallsStatus } from '@wagmi/core' const { id } = await sendCalls(config, { calls: [ { to: '0x…', value: parseEther('1') }, { to: '0x…', value: parseEther('2') }, ], }) // 稍后请求钱包展示该批次状态 await showCallsStatus(config, { id })

参数说明

showCallsStatus接受两个参数，类型为ShowCallsStatusParameters：

import { type ShowCallsStatusParameters } from '@wagmi/core'

connector

• 类型：Connector | undefined
• 含义：指定用于展示调用状态的钱包连接器（Connector）。

省略该参数时，Action 会使用当前活动的连接（config.state.connections中的当前连接）。当存在多个连接、需要明确指定时，可通过getConnections获取连接列表后取出目标 connector：

import { getConnections, showCallsStatus } from '@wagmi/core' import { config } from './config' const connections = getConnections(config) await showCallsStatus(config, { connector: connections[0]?.connector, id: '0x1234567890abcdef', })

从源码看，ShowCallsStatusParameters是 viem 同名参数类型与ConnectorParameter的交叉类型（见 showCallsStatus.ts），ConnectorParameter即该可选connector字段，因此它与 wagmi 其余 Action 的参数风格保持一致。

id

• 类型：string
• 含义：要展示状态的调用批次标识符，即sendCalls返回的id。

import { showCallsStatus } from '@wagmi/core' import { config } from './config' await showCallsStatus(config, { id: '0x1234567890abcdef', })

返回类型

showCallsStatus的返回类型为ShowCallsStatusReturnType：

import { type ShowCallsStatusReturnType } from '@wagmi/core'

类型为bigint，表示最近观察到的区块号（Most recent block number seen）。该返回类型直接继承自 viem 的ShowCallsStatusReturnType（见 showCallsStatus.ts），意味着调用成功后你可以拿到一个区块高度作为确认参照。

错误处理

showCallsStatus的错误类型为ShowCallsStatusErrorType：

import { type ShowCallsStatusErrorType } from '@wagmi/core'

该类型同样继承自 viem 的ShowCallsStatusErrorType（见 showCallsStatus.ts），涵盖底层wallet_showCallsStatus可能抛出的各类错误。此外，由于该 Action 在调用前需要先获取连接器客户端（见下文「底层实现」），它同样可能抛出与连接状态相关的错误，包括：

• ConnectorNotConnectedError：未找到活动连接（未连接钱包）；
• ConnectorChainMismatchError：连接器的链 ID 与预期链不一致；
• ConnectorAccountNotFoundError：指定的账户不存在于连接器上；
• ConnectorUnavailableReconnectingError：处于reconnecting状态且连接器不支持读取账户/链信息时抛出。

这些错误定义与抛出时机可在 getConnectorClient.ts 及其上游 config.ts 错误模块 中查看。生产环境建议用try/catch包裹调用并据此给用户友好提示。

底层实现与调用链

从源码结构看，showCallsStatus的实现非常精简（showCallsStatus.ts）：

export async function showCallsStatus<config extends Config>( config: config, parameters: ShowCallsStatusParameters, ): Promise<ShowCallsStatusReturnType> { const { connector, id } = parameters const client = await getConnectorClient(config, { connector }) return viem_showCallsStatus(client, { id }) }

其内部调用链可以归纳为两步：

1. 获取连接器客户端：getConnectorClient(config, { connector })会从当前连接中取出账户、链信息与 provider。若显式传入connector，则会调用该连接器的getAccounts()与getChainId()建立临时连接；否则使用config.state.connections中的当前连接。若连接器实现了自定义getClient，则直接复用；否则用custom(provider)transport 创建一个以「Connector Client」命名的 viem 客户端（详见 getConnectorClient.ts）。

2. 委托给 viem：将客户端与{ id }转发给 viem 的showCallsStatus，由 viem 负责组装并发送 EIP-5792 的wallet_showCallsStatusRPC 请求。

这也是 wagmi 核心 Action 的典型设计：薄封装 + 复用 viem，保证类型与行为与 viem 完全对齐。

与 sendCalls / getCallsStatus 的组合实战

showCallsStatus通常与 EIP-5792 的其他 Action 搭配使用，形成完整流程。仓库中的测试用例（showCallsStatus.test.ts）完整演示了这一链路：

import { accounts, config, testClient } from '@wagmi/test' import { parseEther } from 'viem' const connector = config.connectors[0]! await connect(config, { connector }) const { id } = await sendCalls(config, { calls: [ { data: '0xdeadbeef', to: accounts[1], value: parseEther('1') }, { to: accounts[2], value: parseEther('2') }, { to: accounts[3], value: parseEther('3') }, ], }) await testClient.mainnet.mine({ blocks: 1 }) await showCallsStatus(config, { id }) await disconnect(config, { connector })

可以看到：connect建立连接 →sendCalls返回批次id→ 出块后showCallsStatus请求钱包展示状态。这也印证了showCallsStatus的使用前提：必须先通过sendCalls提交批次并拿到id。

若需要以编程方式轮询批次结果而非依赖钱包展示，则应改用getCallsStatus(config, { id })，它返回{ status: 'PENDING' | 'CONFIRMED', receipts: TransactionReceipt[] }，可与showCallsStatus搭配：先查询确认，再引导用户到钱包查看详情。

React 中的 useShowCallsStatus Hook

在@wagmi/react中，该 Action 被封装为useShowCallsStatusHook（useShowCallsStatus.ts），底层基于 TanStack Query 的useMutation实现，适合在组件中触发：

import { useShowCallsStatus } from 'wagmi' function ShowStatusButton({ id }: { id: string }) { const { mutate, isPending } = useShowCallsStatus() return ( <button disabled={isPending} onClick={() => mutate({ id })}> 在钱包中查看状态 </button> ) }

Hook 返回标准的 mutation 对象（mutate、mutateAsync、isPending、error等），并额外暴露了已废弃的showCallsStatus/showCallsStatusAsync别名（源码注释标记为@deprecated，建议改用mutate/mutateAsync）。其底层通过 showCallsStatusMutationOptions 生成 mutation 配置，mutationKey为['showCallsStatus']，mutationFn直接调用 core 的showCallsStatus。core 包亦从@wagmi/core/query导出该配置函数（见 query 导出），供其他框架（Vue、Solid）或自定义封装复用。

常见问题与注意事项

• 必须已连接钱包：showCallsStatus需要基于连接器客户端发起请求，未连接或当前连接失效时会抛出ConnectorNotConnectedError。
• id 必须真实有效：id必须来自sendCalls的返回，伪造或过期的 id 会导致钱包无法定位批次，最终由底层 RPC 返回错误。
• 依赖钱包支持 EIP-5792：wallet_showCallsStatus是 EIP-5792 定义的可选方法，只有实现了该标准的钱包才能响应展示请求；对不支持的钱包，调用会以错误结束，建议先通过getCapabilities检测钱包能力再决定是否展示。
• 返回值为区块号：成功后返回最近观察到的区块号（bigint），可作为展示成功与否的判定依据。

总结

showCallsStatus是 EIP-5792 批量交易体系中的「展示」动作：它接收sendCalls返回的批次id，通过当前或指定 connector 的 viem 客户端，向钱包发起wallet_showCallsStatus请求，让钱包在自己的界面中呈现该批次的状态。它的参数仅有两个——connector（可选）与id，返回类型继承自 viem（bigint区块号），错误类型同样与 viem 对齐。配合sendCalls、getCallsStatus以及 React 侧的useShowCallsStatus，即可在 dApp 中构建完整的批量交易提交与状态展示体验。

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi