wagmi Vue useClient 组合式函数完全指南获取与响应式监听 Viem Client【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseClient 是wagmi/vue提供的组合式函数Composable用于在 Vue 组件中获取 Viem 的Client实例并在链或配置变化时自动响应式更新。本文围绕 useClient 官方文档 展开结合wagmi/vue与wagmi/core的源码与测试实现完整讲解其导入方式、用法、参数与返回值类型帮助读者在自己的 Vue 应用中正确、高效地拿到链上客户端用于签名、发送交易或调用合约。背景Viem Client 与 useClient 的角色在 wagmi 生态中Viem 的Client中管理而useClient就是 Vue 组件与 ViemClient之间的桥梁它从 WagmiPlugin 提供的全局配置中读取链状态它返回一个 Vue 的RefClient | undefined当链切换switchChain或配置初始化完成后client.value会随之更新组件卸载时自动清理订阅无需手动调用unwatch。也就是说useClient并不是简单的一次性取值而是一个响应式的客户端访问入口。导入方式与wagmi/vue其他组合式函数一致直接从包入口导入即可import { useClient } from wagmi/vue对应的类型UseClientParameters与UseClientReturnType同样从wagmi/vue导出供需要显式标注类型的场景使用import { type UseClientParameters } from wagmi/vue import { type UseClientReturnType } from wagmi/vue基础用法在script setup中调用useClient()即可拿到当前链对应的 Viem Clientscript setup langts import { useClient } from wagmi/vue const client useClient() /script该组合式函数需要配合已安装的WagmiPlugin使用——插件通过app.provide(configKey, config)将 Config 注入到组件树中见 packages/vue/src/plugin.tsuseClient内部再通过inject取出。示例中./config对应的配置文件如下见 site/snippets/vue/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(), }, })默认不传任何参数时useClient返回当前激活链对应的 Client若当前激活链为主网则返回连接 mainnet 的 Client。一个完整的组件示例下面是一个可直接运行的组合示例先安装插件再在组件中读取 Client 并展示其链信息// main.ts import { createApp } from vue import { WagmiPlugin } from wagmi/vue import { config } from ./config const app createApp(App) app.use(WagmiPlugin, { config }) app.mount(#app)!-- App.vue -- script setup langts import { useClient } from wagmi/vue const client useClient() /script template div v-ifclient p当前链 ID{{ client.chain.id }}/p pTransport 类型{{ client.transport.type }}/p /div p v-elseClient 尚未就绪或当前链未配置/p /template参数详解useClient接受一个可选的UseClientParameters对象。从源码看packages/vue/src/composables/useClient.ts其类型为DeepMaybeRefGetClientParametersconfig, chainId ConfigParameterconfig其中DeepMaybeRef意味着参数既可以是普通值也可以是 Vue 的 ref从而支持响应式传参。可配置的参数共有两个。chainId类型config[chains][number][id] | undefined作用指定要获取 Client 的链 ID。不传时使用当前激活链。典型用法是明确指定某条链script setup langts import { useClient } from wagmi/vue import { mainnet } from wagmi/vue/chains // [!code focus] import { config } from ./config const client useClient({ chainId: mainnet.id, // [!code focus] }) /script几点重要的行为细节均有源码或测试佐证响应式参数chainId可以传入一个ref改变 ref 的值会触发 Client 更新。测试 packages/vue/src/composables/useClient.test.ts 中chainId从ref(456)变为1后等待断言client?.chain.id 1通过验证了这一行为。未配置的链返回 undefined若传入的chainId不在config的chains列表中返回值是undefined而非抛错。测试behavior: unconfigured chain同文件第 38-40 行以chainId: 123456验证了这一点底层原因在于getClient内部用try/catch包裹config.getClient(parameters)失败时返回undefined见 packages/core/src/actions/getClient.ts。类型层面的约束在类型测试 packages/vue/src/composables/useClient.test-d.ts 中向已配置的config传入chainId: 123456会触发ts-expect-error即 TS 会在编译期阻止你访问未配置链的 Client 类型而省略config参数时未配置链只会收窄为undefined代码需先做空值判断才能访问client.value.chain。config类型Config | undefined作用显式传入 Config以替代从WagmiPlugin注入的全局配置。适用于测试、多配置实例或希望在组件树之外使用useClient的场景。script setup langts import { useClient } from wagmi/vue import { config } from ./config // [!code focus] const client useClient({ config, // [!code focus] }) /script从实现看useClient内部先调用useConfig(params)packages/vue/src/composables/useConfig.ts若显式传入了config则直接透传使用否则检查是否存在注入上下文并inject全局配置未安装WagmiPlugin时会抛出WagmiPluginNotFoundError。因此config参数既是覆盖手段也是脱离插件依赖时的逃生通道。返回值类型useClient的返回类型为import { type UseClientReturnType } from wagmi/vue类型RefClient | undefined含义一个 Vue 响应式引用其值为 Viem 的Client实例或undefined。关于返回值的三个关键点可能是 undefined链未配置、配置尚未就绪或当前链没有可用 transport 时client.value为undefined。在模板中应使用v-ifclient之类的守卫或在使用前做空值判断。只读 Ref源码最后返回readonly(client)见 packages/vue/src/composables/useClient.ts即外部无法直接改写返回值客户端实例始终由 wagmi 内部状态驱动避免出现状态漂移。类型随参数收窄通过config与chainId泛型推导TypeScript 能精确推断出client.value.chain与client.value.transport.type的具体类型见 packages/vue/src/composables/useClient.test-d.ts为链 ID、transport 类型等提供编译期校验。响应式更新机制与底层 ActionuseClient的响应式能力建立在两个核心 Action 之上这也是文档末尾 Action 一节列出的内容getClient同步获取 Client 实例。核心实现为config.getClient(parameters)失败时捕获异常并返回undefined见 packages/core/src/actions/getClient.ts。watchClient订阅 Client 的变化。它通过config.subscribe注册监听并用a?.uid b?.uid作为相等性判断见 packages/core/src/actions/watchClient.ts——只要 Client 实例的uid未变就认为没有变化避免无意义的重复触发。结合 packages/vue/src/composables/useClient.ts 的实现useClient的完整工作流程如下const params computed(() deepUnref(parameters))把参数中的 ref 全部解包得到稳定的纯对象deepUnref的实现见 packages/vue/src/utils/cloneDeep.tsconst config useConfig(params)按上文规则解析配置const client ref(getClient(config, params.value))初始同步取值watchEffect(() { client.value getClient(...) })当参数如chainIdref变化时重新取值watchClient(config, { onChange })订阅全局 Client 变化如调用switchChain切换链仅在uid变化时更新本地 ref组件卸载时通过onScopeDispose(() unsubscribe())自动清理订阅。这一设计保证了无论用户手动switchChain切换链还是配置在运行时被更新client.value都会保持与全局状态一致。典型使用场景发送交易与合约调用将useClient()返回的 Client 传给viem的writeContract、sendTransaction等函数用于签名与广播交易。读取链上数据结合readContract、getBalance等读取操作并在链切换后自动使用新链的 Client。展示当前网络状态在 UI 中展示client.chain.id、client.transport.type等信息切换网络时界面自动刷新。多链场景按需取客户端通过chainId参数固定获取某条链的 Client而不受当前激活链影响。常见问题与注意事项没有安装 WagmiPlugin 会怎样未传config参数且未安装插件时useConfig会抛出WagmiPluginNotFoundError若连注入上下文都不存在如在非组件环境中调用则抛出WagmiInjectionContextError。解决方式是安装插件或显式传入config。client 为 undefined 时不要直接解构useClient返回值可能为undefined直接访问client.value.chain会报错建议先用v-if或if守卫。chainId 未配置时不会报错但会静默返回 undefined这便于实现“可用则用、不可用则降级”的逻辑但也要求开发者对未配置链做显式处理。订阅自动清理useClient借助 Vue 的onScopeDispose在组件卸载时取消watchClient订阅因此无需在onUnmounted中手动清理。小结useClient是wagmi/vue中连接 Vue 响应式系统与 ViemClient的核心组合式函数它从 WagmiPlugin 提供的全局配置解析链状态支持通过chainId指定目标链、通过config覆盖全局配置内部依托getClient与watchClient两个 Action 实现同步取值与响应式监听。理解其参数语义、返回类型及底层订阅机制有助于在多链、动态切换网络的 Vue dApp 中写出类型安全且状态一致的客户端访问代码。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考