wagmi Vue 合约读取实战用 useReadContract 读取智能合约只读数据【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseReadContract是 wagmi 为 Vue 应用提供的核心 Composable用于调用智能合约中view/pure修饰的只读函数并获取返回结果。本文基于 read-from-contract.md 指南结合 useReadContract 源码 与 查询层实现系统讲解只读调用的原理、完整用法、依赖控制、加载与错误状态处理帮助你在 Vue 3 项目中安全高效地读取链上数据。概览只读函数为什么无需 Gas在 Solidity 中view与pure修饰的函数只能读取合约状态view可读、pure连读都不可写且不读状态无法对链上状态做任何修改。由于它们不改变合约状态因此执行不需要消耗 Gas任何用户都可以免费调用无需支付交易费用。useReadContract封装了这层能力让 Vue 组件可以通过声明式参数直接发起对合约的只读调用并自动获得 TanStack Query 提供的缓存、重试、窗口聚焦刷新等能力Vue 包内部通过 query.ts 桥接 TanStack Query。基础用法读取 ERC-20 余额以下组件从 Wagmi 示例合约0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2读取指定地址的代币余额script setup langts import { useReadContract } from wagmi import { wagmiContractConfig } from ./contracts const { data: balance } useReadContract({ ...wagmiContractConfig, functionName: balanceOf, args: [0x03A71968491d55603FFe1b11A9e23eF013f75bCF], }) /script template divBalance: {{ balance?.toString() }}/div /template其中wagmiContractConfig定义了合约地址与 ABI使用as const断言以获得最强类型推断export const wagmiContractConfig { address: 0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2, abi: [ { type: function, name: balanceOf, stateMutability: view, inputs: [{ name: account, type: address }], outputs: [{ type: uint256 }], }, { type: function, name: totalSupply, stateMutability: view, inputs: [], outputs: [{ name: supply, type: uint256 }], }, ], } as const从源码看调用链useReadContract.ts 的实现非常简洁参数通过deepUnref深度解包 Vue 响应式引用随后从useConfig取全局配置、从useChainId取当前链 ID最后调用readContractQueryOptions生成查询选项并交给useQuery。真正的 RPC 请求发生在 readContract.ts 的queryFn中它从查询键中剥离scopeKey后将剩余参数透传给 core 包的readContractaction完成对链的只读调用。参数详解useReadContract的核心参数详见 useReadContract API 文档参数类型说明abiAbi必填合约 ABI建议使用as const断言以启用完整类型推断addressAddress必填合约地址functionName由 ABI 推断要调用的函数名仅允许pure/view函数args由 ABI 与函数名推断传给函数的参数数组accountAccount \| undefined调用时使用的账户即msg.senderchainIdnumber \| undefined指定读取数据的链 ID缺省时使用当前链blockNumberbigint \| undefined在指定区块高度读取blockTaglatest \| earliest \| pending \| safe \| finalized \| undefined在指定区块标签读取默认latestcodeHex \| undefined合约字节码用于**未部署deployless**读取scopeKeystring \| undefined将缓存限定在特定上下文相同上下文的 Composable 共享同一缓存configConfig \| undefined覆盖从 WagmiPlugin 获取的全局配置queryTanStack Query 参数见下文「query 选项」Vue 响应式特性与 React 版本不同Vue 版本的useReadContract接受MaybeRef与DeepMaybeRef参数abi、address、functionName、args等既可以是普通值也可以是ref或computed。测试用例 useReadContract.test.ts 验证了「参数为 ref 且未就绪时查询保持 idle就绪后自动发起请求」的行为useReadContract.test-d.ts 则验证了computedargs 的类型推断。这让「依赖异步数据的读取」可以完全以响应式方式编写。依赖控制等数据就绪再发起查询如果useReadContract依赖另一个值例如下方示例中的address可以使用query.enabled选项阻止查询在依赖就绪前运行const { data: balance } useReadContract({ ...wagmiContractConfig, functionName: balanceOf, args: [address], query: { enabled: !!address, }, })在 readContractQueryOptions 中可以看到enabled的完整判定逻辑只有address或code、abi、functionName齐备且用户未显式关闭时查询才会启用。这保证了address、abi等 ref 尚未赋值时不会产生无意义的 RPC 请求一旦依赖变为可用查询自动触发。测试 useReadContract.test.ts 正好印证了这一行为addressRef、abiRef、functionNameRef逐步赋值的过程中fetchStatus一直保持idle直到全部就绪后才返回bigint类型的结果。query 选项速查query对象支持绝大多数 TanStack Query v5 选项queryFn与queryKey由 wagmi 内部使用、不可覆盖详见 query-options.md常用项包括enabledboolean设为false可禁用自动执行用于依赖查询staleTimenumber | Infinity默认0数据在此毫秒数内不被视为过期设为Infinity则永不过期gcTimenumber | Infinity默认 5 分钟控制不活跃缓存数据的回收时长refetchInterval/refetchIntervalInBackground定时轮询刷新refetchOnWindowFocus窗口聚焦时是否刷新默认trueretry失败重试次数客户端默认3服务端默认0retryDelay重试延迟支持指数退避如attempt Math.min(attempt 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)select对返回的data做转换不影响缓存中存储的数据initialData初始数据用于 SSR 或首屏渲染视为 stale除非设置了staleTimeplaceholderDatapending 阶段的占位数据不写入缓存networkMode网络模式默认onlinestructuralSharing默认true开启查询结果结构共享以优化性能。加载与错误状态useReadContract会返回加载与错误状态可用于展示加载指示器或在合约执行回退revert时显示错误信息script setup langts import { useReadContract } from wagmi const { data: balance, error, isPending } useReadContract({ ...wagmiContractConfig, functionName: balanceOf, args: [0x03A71968491d55603FFe1b11A9e23eF013f75bCF], }) /script template div v-ifisPendingLoading.../div div v-else-iferror Error: {{ (error as BaseError).shortMessage || error.message }} /div div v-elseBalance: {{ balance?.toString() }}/div /template返回类型说明useReadContract返回的是 TanStack Query 风格的响应式结果完整字段见 query-result.mddata最近一次成功解析的数据默认undefined类型由abifunctionNameargs自动推断源码中的UseReadContractReturnTypeisPending/isError/isSuccess由statuspending | error | success派生的布尔量isLoading首次请求进行中等价于isFetching isPendingisFetching/isRefetching是否正在后台请求error错误对象null表示无错误refetch手动重新请求的函数支持cancelRefetch与throwOnError选项status/fetchStatus查询状态与抓取状态failureCount/failureReason失败次数与原因成功时重置。错误对象通常带有shortMessage人类可读的短消息与message模板中优先展示shortMessage可得到更清晰的回退原因。类型安全与部署前读取Deployless Read完整类型推断当abi使用as const断言后functionName、args及返回的data都会获得精确推断balanceOf的args必须是address返回值为bigint | undefined。类型测试 useReadContract.test-d.ts 直接断言了这些推断结果例如UseReadContractParameterstypeof abi.erc20, balanceOf的args被约束为readonly [Address]。未部署合约读取useReadContract还支持未部署deployless读取不传address改为传入code合约字节码wagmi 会先在本地模拟部署再调用functionName。这一能力被 readContractQueryOptions 的enabled逻辑显式支持options.address || (code in options options.code)并且有对应的单元测试useReadContract.test.ts与类型测试useReadContract.test-d.ts佐证const { data: name } useReadContract({ abi: wagmiMintExampleAbi, functionName: name, code: wagmiMintExampleBytecode, })深入底层 readContract action 与查询键在 Vue Composable 之下一切最终落到 core 包的readContractaction对应文档 readContract。查询键由 readContractQueryKey 生成形如[readContract, { address, args, chainId, functionName, ... }]测试快照useReadContract.test.ts展示了其实际形态[ readContract, { address: 0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2, args: [0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC], chainId: 1, functionName: balanceOf } ]查询键中会包含chainId这意味着不同链上的相同调用不会互相污染缓存。若需要在多个组件间复用相同读取可结合scopeKey控制缓存共享范围若需在组件外手动失效或操作该查询可参考 readContractQueryKey 构造一致的查询键。进一步探索需要批量读取多个合约函数时可使用useReadContracts仓库中对应 useReadContracts 相关实现 目录内的相关 Composable在一次调用中完成多个只读请求避免状态管理膨胀若需按区块间隔自动刷新可组合useBlockNumber与refetch/queryClient.invalidateQueries实现定时失效相关思路在 useBlockNumber.ts 与 query 工具 中可找到依据完整的参数与返回值说明见 useReadContract API 文档 与 query-options.md、query-result.md想体验完整项目可参考 Vue 快速上手 与 WagmiPlugin、createConfig 配置你的 Vue 应用。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
wagmi Vue 合约读取实战：用 useReadContract 读取智能合约只读数据
wagmi Vue 合约读取实战用 useReadContract 读取智能合约只读数据【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseReadContract是 wagmi 为 Vue 应用提供的核心 Composable用于调用智能合约中view/pure修饰的只读函数并获取返回结果。本文基于 read-from-contract.md 指南结合 useReadContract 源码 与 查询层实现系统讲解只读调用的原理、完整用法、依赖控制、加载与错误状态处理帮助你在 Vue 3 项目中安全高效地读取链上数据。概览只读函数为什么无需 Gas在 Solidity 中view与pure修饰的函数只能读取合约状态view可读、pure连读都不可写且不读状态无法对链上状态做任何修改。由于它们不改变合约状态因此执行不需要消耗 Gas任何用户都可以免费调用无需支付交易费用。useReadContract封装了这层能力让 Vue 组件可以通过声明式参数直接发起对合约的只读调用并自动获得 TanStack Query 提供的缓存、重试、窗口聚焦刷新等能力Vue 包内部通过 query.ts 桥接 TanStack Query。基础用法读取 ERC-20 余额以下组件从 Wagmi 示例合约0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2读取指定地址的代币余额script setup langts import { useReadContract } from wagmi import { wagmiContractConfig } from ./contracts const { data: balance } useReadContract({ ...wagmiContractConfig, functionName: balanceOf, args: [0x03A71968491d55603FFe1b11A9e23eF013f75bCF], }) /script template divBalance: {{ balance?.toString() }}/div /template其中wagmiContractConfig定义了合约地址与 ABI使用as const断言以获得最强类型推断export const wagmiContractConfig { address: 0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2, abi: [ { type: function, name: balanceOf, stateMutability: view, inputs: [{ name: account, type: address }], outputs: [{ type: uint256 }], }, { type: function, name: totalSupply, stateMutability: view, inputs: [], outputs: [{ name: supply, type: uint256 }], }, ], } as const从源码看调用链useReadContract.ts 的实现非常简洁参数通过deepUnref深度解包 Vue 响应式引用随后从useConfig取全局配置、从useChainId取当前链 ID最后调用readContractQueryOptions生成查询选项并交给useQuery。真正的 RPC 请求发生在 readContract.ts 的queryFn中它从查询键中剥离scopeKey后将剩余参数透传给 core 包的readContractaction完成对链的只读调用。参数详解useReadContract的核心参数详见 useReadContract API 文档参数类型说明abiAbi必填合约 ABI建议使用as const断言以启用完整类型推断addressAddress必填合约地址functionName由 ABI 推断要调用的函数名仅允许pure/view函数args由 ABI 与函数名推断传给函数的参数数组accountAccount \| undefined调用时使用的账户即msg.senderchainIdnumber \| undefined指定读取数据的链 ID缺省时使用当前链blockNumberbigint \| undefined在指定区块高度读取blockTaglatest \| earliest \| pending \| safe \| finalized \| undefined在指定区块标签读取默认latestcodeHex \| undefined合约字节码用于**未部署deployless**读取scopeKeystring \| undefined将缓存限定在特定上下文相同上下文的 Composable 共享同一缓存configConfig \| undefined覆盖从 WagmiPlugin 获取的全局配置queryTanStack Query 参数见下文「query 选项」Vue 响应式特性与 React 版本不同Vue 版本的useReadContract接受MaybeRef与DeepMaybeRef参数abi、address、functionName、args等既可以是普通值也可以是ref或computed。测试用例 useReadContract.test.ts 验证了「参数为 ref 且未就绪时查询保持 idle就绪后自动发起请求」的行为useReadContract.test-d.ts 则验证了computedargs 的类型推断。这让「依赖异步数据的读取」可以完全以响应式方式编写。依赖控制等数据就绪再发起查询如果useReadContract依赖另一个值例如下方示例中的address可以使用query.enabled选项阻止查询在依赖就绪前运行const { data: balance } useReadContract({ ...wagmiContractConfig, functionName: balanceOf, args: [address], query: { enabled: !!address, }, })在 readContractQueryOptions 中可以看到enabled的完整判定逻辑只有address或code、abi、functionName齐备且用户未显式关闭时查询才会启用。这保证了address、abi等 ref 尚未赋值时不会产生无意义的 RPC 请求一旦依赖变为可用查询自动触发。测试 useReadContract.test.ts 正好印证了这一行为addressRef、abiRef、functionNameRef逐步赋值的过程中fetchStatus一直保持idle直到全部就绪后才返回bigint类型的结果。query 选项速查query对象支持绝大多数 TanStack Query v5 选项queryFn与queryKey由 wagmi 内部使用、不可覆盖详见 query-options.md常用项包括enabledboolean设为false可禁用自动执行用于依赖查询staleTimenumber | Infinity默认0数据在此毫秒数内不被视为过期设为Infinity则永不过期gcTimenumber | Infinity默认 5 分钟控制不活跃缓存数据的回收时长refetchInterval/refetchIntervalInBackground定时轮询刷新refetchOnWindowFocus窗口聚焦时是否刷新默认trueretry失败重试次数客户端默认3服务端默认0retryDelay重试延迟支持指数退避如attempt Math.min(attempt 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)select对返回的data做转换不影响缓存中存储的数据initialData初始数据用于 SSR 或首屏渲染视为 stale除非设置了staleTimeplaceholderDatapending 阶段的占位数据不写入缓存networkMode网络模式默认onlinestructuralSharing默认true开启查询结果结构共享以优化性能。加载与错误状态useReadContract会返回加载与错误状态可用于展示加载指示器或在合约执行回退revert时显示错误信息script setup langts import { useReadContract } from wagmi const { data: balance, error, isPending } useReadContract({ ...wagmiContractConfig, functionName: balanceOf, args: [0x03A71968491d55603FFe1b11A9e23eF013f75bCF], }) /script template div v-ifisPendingLoading.../div div v-else-iferror Error: {{ (error as BaseError).shortMessage || error.message }} /div div v-elseBalance: {{ balance?.toString() }}/div /template返回类型说明useReadContract返回的是 TanStack Query 风格的响应式结果完整字段见 query-result.mddata最近一次成功解析的数据默认undefined类型由abifunctionNameargs自动推断源码中的UseReadContractReturnTypeisPending/isError/isSuccess由statuspending | error | success派生的布尔量isLoading首次请求进行中等价于isFetching isPendingisFetching/isRefetching是否正在后台请求error错误对象null表示无错误refetch手动重新请求的函数支持cancelRefetch与throwOnError选项status/fetchStatus查询状态与抓取状态failureCount/failureReason失败次数与原因成功时重置。错误对象通常带有shortMessage人类可读的短消息与message模板中优先展示shortMessage可得到更清晰的回退原因。类型安全与部署前读取Deployless Read完整类型推断当abi使用as const断言后functionName、args及返回的data都会获得精确推断balanceOf的args必须是address返回值为bigint | undefined。类型测试 useReadContract.test-d.ts 直接断言了这些推断结果例如UseReadContractParameterstypeof abi.erc20, balanceOf的args被约束为readonly [Address]。未部署合约读取useReadContract还支持未部署deployless读取不传address改为传入code合约字节码wagmi 会先在本地模拟部署再调用functionName。这一能力被 readContractQueryOptions 的enabled逻辑显式支持options.address || (code in options options.code)并且有对应的单元测试useReadContract.test.ts与类型测试useReadContract.test-d.ts佐证const { data: name } useReadContract({ abi: wagmiMintExampleAbi, functionName: name, code: wagmiMintExampleBytecode, })深入底层 readContract action 与查询键在 Vue Composable 之下一切最终落到 core 包的readContractaction对应文档 readContract。查询键由 readContractQueryKey 生成形如[readContract, { address, args, chainId, functionName, ... }]测试快照useReadContract.test.ts展示了其实际形态[ readContract, { address: 0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2, args: [0xa5cc3c03994DB5b0d9A5eEdD10CabaB0813678AC], chainId: 1, functionName: balanceOf } ]查询键中会包含chainId这意味着不同链上的相同调用不会互相污染缓存。若需要在多个组件间复用相同读取可结合scopeKey控制缓存共享范围若需在组件外手动失效或操作该查询可参考 readContractQueryKey 构造一致的查询键。进一步探索需要批量读取多个合约函数时可使用useReadContracts仓库中对应 useReadContracts 相关实现 目录内的相关 Composable在一次调用中完成多个只读请求避免状态管理膨胀若需按区块间隔自动刷新可组合useBlockNumber与refetch/queryClient.invalidateQueries实现定时失效相关思路在 useBlockNumber.ts 与 query 工具 中可找到依据完整的参数与返回值说明见 useReadContract API 文档 与 query-options.md、query-result.md想体验完整项目可参考 Vue 快速上手 与 WagmiPlugin、createConfig 配置你的 Vue 应用。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
