Wagmi SolidJS useWriteContractSync 详解执行合约写操作并同步等待确认回执【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本篇指南围绕 Wagmi 的 SolidJS 适配包wagmi/solid中的useWriteContractSync原语展开它是用于执行合约写函数并等待交易被打包进区块的响应式原语成功后返回完整的TransactionReceipt而非单纯的交易哈希。读完本文你将掌握它的导入与完整用法、mutation全部可选参数、返回类型的每一项含义以及它在 Solid 响应式体系下的底层实现链路从原语到wagmi/core的 mutation 选项与 action 实现并能据此在 SolidJS 应用里可靠地发起、确认和回滚合约写操作。一、useWriteContractSync 是什么useWriteContractSync是一个用于在 SolidJS 组件中执行合约写函数的 primitive与useWriteContract的关键区别在于同步语义它会等待交易被包含进区块in-block之后才 resolve返回值不同成功时data是一个TransactionReceipt包含status、blockNumber、gasUsed等完整回执信息而useWriteContract只返回交易哈希。这意味着如果你需要写完立刻知道结果的场景——例如确认 mint 是否成功、读取status判断回滚——useWriteContractSync是更合适的选择。二、导入与基础用法导入import { useWriteContractSync } from wagmi/solid使用示例import { useWriteContractSync } from wagmi/solid import { abi } from ./abi function App() { const writeContractSync useWriteContractSync() const handleMint () { writeContractSync.mutate({ abi, address: 0x6b175474e89094c44da98b954eedeac495271d0f, functionName: mint, }) } // writeContractSync.data contains the TransactionReceipt when successful }配套的WagmiProvider需要一个config参见仓库中的示例 config.tsimport { createConfig, http } from wagmi/solid import { mainnet, sepolia } from wagmi/solid/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })注意mutate的 variables 中abi、address、functionName、args等具体参数的取值规则与校验方式与 core 层的writeContractSyncaction 保持一致abi、functionName、args、value等字段的完整说明见该文档。三、Parameters参数import { useWriteContractSync } from wagmi/solid useWriteContractSync.Parameters useWriteContractSync.SolidParameters参数以getter 函数accessor的形式传入以维持 Solid 的响应式追踪——组件内parameters()依赖的响应式源变化时mutation 选项会被重新计算。configConfig | undefined用于替代从最近的WagmiProvider中获取的Config。mutationTanStack Query mutation 参数。注意Wagmi 不支持传入全部 TanStack Query 参数——mutationFn、mutationKey等由 Wagmi 内部接管内部固定为mutationKey: [writeContractSync]见 writeContractSyncMutationOptions不可覆盖。以下列出的参数均受支持参数类型说明gcTimenumber \| Infinity \| undefined未使用/失活的 mutation 缓存数据在内存中保留的毫秒数缓存失活后超过该时长即被回收多处指定时取最长值设为Infinity可禁用垃圾回收metaRecordstring, unknown \| undefined若设置会在 mutation 缓存条目上附加额外信息可在所有mutate可用处如onError、onSuccess访问networkModeonline \| always \| offlineFirst \| undefined默认online控制 mutation 的网络执行模式onError(error, variables, context?) unknown \| Promiseunknownmutation 出错时触发接收错误对象onMutate(variables) context \| voidmutation 执行前触发适合做乐观更新返回值会传递给onError与onSettled便于回滚onSuccess(data, variables, context?) unknown \| Promiseunknownmutation 成功时触发接收 mutation 结果本例中即TransactionReceiptonSettled(data, error, variables, context?) unknown \| Promiseunknown无论成功还是出错都会触发queryClientQueryClient指定自定义QueryClient否则使用最近上下文中的实例retryboolean \| number \| ((failureCount, error) boolean)默认0false不重试true无限重试数字则重试至失败次数达到该值retryDelaynumber \| ((retryAttempt, error) number)返回下一次重试前的延迟毫秒数可实现指数/线性退避mutate 的 variablesmutate/mutateAsync的第一参对象即WriteContractSyncVariables其类型定义见 WriteContractSyncVariables继承自 core action 的WriteContractSyncParameters见 writeContractSync.ts。除了上述示例中的abi、address、functionName、args外还支持chainId指定目标链默认为当前连接的链connector指定使用哪个 connector 发起交易account指定签名账户local account 时直接走 config 的 clientvalue调用 payable 函数时随交易附带的 ETH 数量。四、Return Type返回类型import { useWriteContractSync } from wagmi/solid useWriteContractSync.ReturnType返回类型的data属性是TransactionReceipt包含已确认交易的完整回执status、blockNumber、blockHash、logs等。其余字段为标准 TanStack Query mutation 结果且均为 Solid 响应式信号可在组件模板中直接绑定成员类型说明mutate(variables, { onSuccess, onSettled, onError }) void触发 mutation可附带一次性回调mutateAsync(variables, { onSuccess, onSettled, onError }) PromiseTData与mutate相同但返回可 await 的 PromisedataTransactionReceipt \| undefined最近一次成功 resolve 的数据默认undefinederrorWriteContractSyncErrorType \| null最近一次错误的对象failureCountnumber失败次数成功时重置为0failureReasonWriteContractSyncErrorType \| null失败原因成功时重置为nullisError/isIdle/isPending/isSuccessboolean由status派生的布尔信号isPausedbooleanmutation 处于paused状态时为truereset() void将 mutation 内部状态重置为初始状态statusidle \| pending \| error \| success当前状态初始 / 执行中 / 上次失败 / 上次成功submittedAtnumber提交时间戳默认0variablesTVariables \| undefined最近一次传给mutate的 variables此外返回对象上还保留了两个已弃用的便捷别名源码中标注deprecated见 useWriteContractSync.tswriteContractSync等价mutate与writeContractSyncAsync等价mutateAsync新代码请统一使用mutate/mutateAsync。五、类型推断当abi设置正确时TypeScript 会针对mutate/mutateAsync自动推断出functionName、args、value的精确类型——例如functionName只能是 ABI 中nonpayable | payable的函数名args会按函数签名给出元组类型。mutate的类型签名定义在 WriteContractSyncMutate其中abi使用了const泛型修饰符以保证字面量 ABI 不被拓宽。更多细节见 Wagmi TypeScript 文档。错误类型同样有完整推断WriteContractSyncErrorType覆盖getConnectorClient()错误、base 错误与 viem 层错误三类见 WriteContractSyncErrorType。六、源码实现链路从 Solid 原语到 viem结合仓库源码可以完整还原这条调用链1. Solid 原语层useWriteContractSync.ts 的实现非常简洁export function useWriteContractSync(parameters () ({})) { const config useConfig(parameters) const mutation useMutation(() writeContractSyncMutationOptions(config(), parameters()), ) return mergeProps(mutation, { /* 弃用别名 writeContractSync / writeContractSyncAsync */ }) }参数默认值是() ({})这样的 accessor配合useConfig(parameters)与writeContractSyncMutationOptions(config(), parameters())使得 config 与 mutation 选项都保持响应式最终通过 Solid 的mergeProps把 mutation 结果铺平成对象返回让调用方拿到一组可直接在模板中使用的响应式属性。2. Core mutation 选项层writeContractSyncMutationOptions 负责组装 TanStack Query 的 mutation 配置return { ...(options.mutation as any), mutationFn(variables) { return writeContractSync(config, variables) }, mutationKey: [writeContractSync], }用户的mutation回调onSuccess、retry等通过展开合并进来而mutationFn与mutationKey被固定为调用 core 的writeContractSyncaction——这也解释了文档中不支持覆盖全部 TanStack Query 参数的说明。3. Core action 层客户端选择与同步等待writeContractSync 是真正执行写操作的 action核心逻辑分三步选择 client若显式传入的account是 local 账户account.type local直接用config.getClient({ chainId })否则走getConnectorClient即要求存在已连接的 connector——这是使用写操作的前提if (typeof account object account?.type local) client config.getClient({ chainId }) else client await getConnectorClient(config, { account, assertChainId: false, chainId, connector })对齐 chain当chainId与 client 链不一致时构造仅含id的最小 chain 对象并设置assertChainId: !!chainId避免跨链断言失败委托 viem通过getAction(client, viem_writeContractSync, writeContractSync)调用 viem 的同名 action。viem 的writeContractSync内部会发送交易后轮询等待回执等待交易被打包因此返回值WriteContractSyncReturnType即TransactionReceiptexport type WriteContractSyncReturnType viem_WriteContractSyncReturnType这正是文档中等待交易被包含进区块后才 resolve返回TransactionReceipt而非交易哈希这一行为差异的底层来源。七、测试用例中的行为验证仓库中的运行时测试 useWriteContractSync.test.ts 完整覆盖了等待回执这一语义connect(config, { connector })建立连接验证写操作依赖连接态renderPrimitive(() useWriteContractSync())渲染原语后调用result.mutate({ abi, address, functionName: mint })testClient.mainnet.mine({ blocks: 1 })主动产出一个区块随后vi.waitUntil(() result.isSuccess)等待成功断言result.data?.status success且result.data?.blockNumber有定义——直接证明了data是完整回执而非哈希。类型层测试 useWriteContractSync.test-d.ts 则逐一锁定了各回调的类型onSuccess的data为TransactionReceipt、onError的error为WriteContractSyncErrorType、onMutate返回的context会正确流转给onError/onSettled与上文参数表的描述一一对应。八、可用的 TanStack Query 类型如需在回调中显式标注类型可从wagmi/solid/query导入该模块由 query 导出 统一提供测试 query.test.ts 确认了writeContractSyncMutationOptions在导出列表中import { type WriteContractSyncData, type WriteContractSyncVariables, type WriteContractSyncMutate, type WriteContractSyncMutateAsync, writeContractSyncMutationOptions, } from wagmi/solid/query九、使用注意事项与适用限制必须已连接非 local 账户场景下交易经由getConnectorClient发起未连接 wallet 时会抛出GetConnectorClientErrorType错误UI 中应先用useConnect/useConnection处理连接状态与useWriteContract的取舍只关心交易已发送用useWriteContract更快返回 hash需要确认执行结果、读取回执日志或status时用useWriteContractSyncretry的谨慎使用写操作天然不幂等retry: true或较大的重试次数可能造成重复提交建议配合onMutate乐观更新 onError回滚的模式管理状态弃用别名writeContractSync/writeContractSyncAsync属性已标记弃用升级代码时替换为mutate/mutateAsync即可。小结useWriteContractSync以 Solid accessor 参数 TanStack Query mutation 的形态把 core 层发送交易并等待回执的能力封装成了响应式原语mutate发起写调用isPending/isSuccess驱动 UI 状态data直接提供可断言的TransactionReceipt。从 solid 原语实现、到 core mutation 选项、再到 core action 的 client 选择与 viem 委托整条链路在仓库源码中均有清晰对应便于按需深入排查连接、跨链或类型推断相关问题。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考