wagmi Vue 开发指南useBalance 组合式函数实现原生代币余额查询【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi本篇技术指南聚焦wagmi/vue包中的useBalance组合式函数Composable它是基于 TanStack Query 封装的响应式查询工具用于在 Vue 应用中获取链上地址的原生币Native Currency如 ETH余额。读完本文你将掌握useBalance的完整参数体系地址、区块号、区块标签、链 ID、作用域键等、查询配置与返回结构并能从源码层面理解它如何与wagmi/core的getBalanceaction 协作最终在真实 Vue 应用中写出可复用的余额查询逻辑。useBalance 是什么useBalance是wagmi/vue提供的用于获取原生货币余额native currency balance的组合式函数。所谓原生货币即链上的基础代币——以太坊主网的 ETH、测试网的测试币、以及任何 EVM 链的 native gas 代币而非 ERC-20 合约代币后者应使用useReadContract配合 ERC-20 ABI 查询。在 useBalance.ts 源码中其返回类型定义如下export type UseBalanceReturnTypeselectData GetBalanceData UseQueryReturnTypeselectData, GetBalanceErrorType其中GetBalanceData的结构在wagmi/core的 getBalance action 中定义export type GetBalanceReturnType { decimals: number symbol: string value: bigint }即每次查询成功后会得到一个包含**小数位数decimals、代币符号symbol、余额数值value以 bigint 表示的最小单位数量**的对象。以测试用例 useBalance.test.ts 中的断言为例当查询chain.mainnet2链上某账户余额时返回{ decimals: 18, symbol: WAG, value: 69000000000000000000n }这正是parseEther(69)对应的最小单位数值——value是原始 wei 值展示时需要结合decimals自行格式化。安装与导入useBalance由wagmi/vue包导出导入方式如下import { useBalance } from wagmi/vue该导出在 exports/index.ts 中登记第 28 行useBalance,同时也提供了配套的类型导出import { type UseBalanceParameters } from wagmi/vue import { type UseBalanceReturnType } from wagmi/vue在 Nuxt 等框架集成场景下useBalance同样被 Nuxt 模块自动桥接导出见 nuxt/module.ts可无缝配合自动导入使用。快速上手查询一个地址的余额useBalance最基本的用法是传入一个address组合式函数会自动从最近的WagmiPlugin提供上下文中取出 Config并使用当前激活链发起查询!-- index.vue -- script setup langts import { useBalance } from wagmi/vue const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, }) /script上面的示例依赖一个已经通过WagmiPlugin注册的 wagmi 配置配置示例参见 config.tsimport { createConfig, http } from wagmi/vue import { mainnet, sepolia } from wagmi/vue/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })result是一个响应式查询对象你可以在模板中这样渲染余额template div v-ifresult.isSuccess {{ result.data?.value }} ({{ result.data?.symbol }}) /div div v-else-ifresult.isPending加载中…/div div v-else-ifresult.isError{{ result.error?.message }}/div /template参数详解useBalance的参数类型为UseBalanceParameters它由wagmi/core的GetBalanceOptions与ConfigParameter组合而来并且通过DeepMaybeRef支持深度响应式参数——这意味着你可以传入ref()包裹的值组合式函数内部会用deepUnref自动解包见 useBalance.ts 第 32 行const params computed(() deepUnref(parameters))。各参数说明如下。address类型Address | undefined说明要查询余额的地址必填。当address为undefined时查询的enabled会被置为false即查询不会自动执行。script setup langts import { useBalance } from wagmi/vue import { mainnet } from wagmi/vue/chains const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, }) /script这一禁用逻辑在wagmi/core的 getBalance.ts 查询选项中实现enabled: Boolean(options.address (options.query?.enabled ?? true)),也正因如此address是支持响应式从无到有的先传入undefined挂起查询待地址可用如用户连接钱包后再更新查询会自动启用。测试behavior: address: undefined - defineduseBalance.test.ts验证了这一点初始时fetchStatus为idle设置地址后自动发起查询并成功返回数据。blockNumber类型bigint | undefined说明查询指定区块高度处的余额用于历史快照场景。script setup langts import { useBalance } from wagmi/vue const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, blockNumber: 17829139n, }) /script注意blockNumber与blockTag互斥在 getBalance action 中二者通过三元表达式分别透传给 viemconst value await action( blockNumber ! undefined ? { address, blockNumber } : { address, blockTag }, )即指定了blockNumber就按该区块高度查询否则按blockTag查询。blockTag类型latest | earliest | pending | safe | finalized | undefined说明查询指定区块标签处的余额。默认由 viem 使用latestsafe与finalized仅在支持相应 RPC 方法的链上可用如以太坊 PoS 后的合并相关标签。script setup langts import { useBalance } from wagmi/vue const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, blockTag: latest, }) /scriptchainId类型config[chains][number][id] | undefined说明指定查询目标链的 ID。默认使用useChainId提供的当前激活链显式传入chainId可以查询与当前链不同的其他链上的余额。script setup langts import { useBalance } from wagmi/vue import { mainnet } from wagmi/vue/chains const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, chainId: mainnet.id, }) /script在实现层面useBalance.ts 第 34-40 行组合式函数通过useChainId获得当前链 ID并在组装查询选项时执行chainId: params.value.chainId ?? chainId.value实现未指定则回退到当前链的语义。测试parameters: chainId验证了跨链查询传入chain.mainnet2.id后得到该测试链上的symbol: WAG与余额值。config类型Config | undefined说明显式传入Config以替代从最近的WagmiPlugin上下文自动获取的配置。适用于脱离插件上下文、手动管理配置的场景如测试、库开发。script setup langts import { useBalance } from wagmi/vue import { config } from ./config const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, config, }) /scriptscopeKey类型string | undefined说明将查询缓存限定到指定上下文。具有相同 context含相同scopeKey及其他参数的 Hook 会共享同一份缓存适用于多个组件查询相同数据时避免重复请求或为不同业务场景隔离缓存。script setup langts import { useBalance } from wagmi/vue const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, scopeKey: foo, }) /scriptquery 选项useBalance还支持在query字段中传入 TanStack Query v5 的查询参数完整列表见 query-options.md 的共享文档常用的包括选项类型说明enabledboolean \| undefined设为false可禁用查询自动运行可用于依赖查询场景gcTimenumber \| Infinity \| undefined未使用/非活跃缓存数据的保留时间默认5 * 60 * 10005 分钟SSR 期间为Infinity设为Infinity禁用垃圾回收staleTimenumber \| Infinity \| undefined数据被视为过期的毫秒数默认0设为Infinity则永不过期refetchIntervalnumber \| false \| function定时轮询间隔毫秒可用于余额自动刷新refetchOnWindowFocusboolean \| always \| function窗口聚焦时是否重新拉取默认trueretryboolean \| number \| function失败重试策略客户端默认3次服务端默认0次retryDelaynumber \| function重试延迟可传指数退避函数attempt Math.min(attempt 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)initialDataTData \| (() TData) \| undefined初始缓存数据会被持久化到缓存默认视为过期除非设置了staleTimeplaceholderDataTData \| function \| undefined挂起状态下的占位数据不会持久化到缓存select(data: TData) unknown转换/挑选返回数据只影响组件拿到的data不影响缓存内容notifyOnChangePropsstring[] \| all \| function控制组件仅在指定属性变化时重新渲染networkModeonline \| always \| offlineFirst \| undefined网络模式默认onlinequeryClientQueryClient \| undefined使用自定义 QueryClient否则使用最近上下文中的实例metaRecordstring, unknown \| undefined附加到缓存条目的元信息可在queryFn的上下文中访问注意queryFn与queryKey由 wagmi 内部使用不可覆盖其余 TanStack Query 参数均可用。例如实现每 15 秒自动刷新余额script setup langts import { useBalance } from wagmi/vue const result useBalance({ address: 0x4557B18E779944BFE9d78A672452331C186a9f48, query: { refetchInterval: 15_000, }, }) /scriptselect 转换数据通过query.select可以直接从查询结果中提取你关心的字段其类型会随之收窄。类型测试 useBalance.test-d.ts 演示了这一点const result useBalance({ query: { select(data) { return data?.value }, }, }) // result.data 的类型被推断为 Refbigint | Refundefined返回类型useBalance的返回值UseBalanceReturnType是 TanStack Query 的响应式结果UseQueryReturnType核心字段完整说明见 query-result.md如下字段类型说明data{ decimals: number; symbol: string; value: bigint } \| undefined最近一次成功解析的数据默认undefinederrornull \| GetBalanceErrorType查询抛出的错误对象默认nullstatuserror \| pending \| success查询状态pending无缓存且未完成、error失败、success成功fetchStatusfetching \| idle \| paused是否正在拉取fetching表示queryFn执行中idle表示未拉取isPending/isError/isSuccessboolean由status派生的布尔标识isLoadingboolean首次拉取进行中等价于isFetching isPendingisFetching/isRefetchingboolean是否正在拉取 / 是否在后台重新拉取isStaleboolean缓存数据是否已失效或超出staleTimerefetchfunction手动重新拉取可传{ cancelRefetch, throwOnError }failureCount/failureReasonnumber/null \| error失败次数与失败原因dataUpdatedAt/errorUpdatedAtnumber数据/错误最近更新时间戳注意data.value是 bigint 类型的最小单位数值若要显示为带小数的可读金额需要结合decimals自行格式化如使用 viem 的formatUnits。底层实现原理理解useBalance的内部工作方式有助于排查缓存、链切换与响应式更新等问题。其实现useBalance.ts可分为三层第一层Vue 响应式封装。useBalance将入参包在computed(() deepUnref(parameters))中从而把ref、嵌套响应式对象等深度解包为普通值随后通过useConfig(params)获取 Config若参数中未显式传入config则从WagmiPlugin上下文获取通过useChainId({ config })订阅当前链 ID 的变化见 useChainId.ts它内部用watchChainId监听链切换并在组件作用域销毁时自动取消订阅。第二层查询选项组装。组合式函数调用getBalanceQueryOptions(config, { ...params, chainId: params.chainId ?? chainId.value })生成 TanStack Query 选项query/getBalance.ts。该函数做了两件关键事计算enabledBoolean(options.address (options.query?.enabled ?? true))地址缺失时整条查询静默禁用生成查询键[balance, filterQueryOptions(options)]参数变化会改变查询键从而触发自动重新请求。第三层底层 action 调用。真正发请求的是wagmi/core的getBalanceactionactions/getBalance.ts。它通过config.getClient({ chainId })按链 ID 获取 viem 客户端再用getAction(client, viem_getBalance, getBalance)调用 viem 的getBalance最后从config.chains或client.chain中取出该链的nativeCurrency元数据将 viem 返回的裸数值补充为{ decimals, symbol, value }结构。这也解释了为什么返回值中的symbol与decimals来自链配置而非 RPC 响应。此外wagmi/core/query还导出了配套的getBalanceQueryKey、getBalanceQueryOptions、GetBalanceData、GetBalanceOptions等类型与工具详见 query-imports.md供需要在 query 层面做更精细控制的进阶场景使用import { type GetBalanceData, type GetBalanceOptions, type GetBalanceQueryFnData, type GetBalanceQueryKey, getBalanceQueryKey, getBalanceQueryOptions, } from wagmi/vue/query测试验证与边界行为仓库测试useBalance.test.ts覆盖了该组合式函数的几个关键行为可作为使用时的行为参考默认查询传入address后查询成功返回结构包含decimals、symbol、value三个字段。链参数显式传入chainId可查询指定链的余额返回该链的原生币符号与精确数值。地址从无到有address初始为undefined时查询处于idle挂起状态地址变为有效值后自动启用并成功返回——这正是钱包连接后余额自动加载的典型交互模式。缺少必要属性时禁用仅传地址、缺少其他条件时查询保持idle不会发起无效请求。更多资源底层 action 文档getBalance配置对象说明createConfig与WagmiPluginVue 组合式函数总览composables参考实现源码useBalance.ts、getBalance.ts、getBalance.ts【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考