wagmi React useConnect Hook 完全指南通过 Connectors 连接账户的实战与源码解析【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseConnect是 wagmi React 框架适配层中负责连接账户connecting accounts的核心 Hook。它以 React Mutation 的形式封装了底层connect动作允许开发者通过 MetaMask、WalletConnect、Injected 等 Connector 建立钱包连接并获取连接后的账户地址与链 ID。读完本文你将掌握useConnect的导入方式、参数与返回值语义、结合createConfig的完整接入流程以及它背后的 TanStack Query Mutation 与wagmi/core动作层调用链。认识 useConnectReact 中的连接动作封装在 wagmi 的架构中wagmi/core提供与框架无关的核心动作Action而wagmiReact 包将这些动作封装为 Hooks供 React 组件以声明式、响应式的方式使用。useConnect正是对核心动作connect的 Hook 封装其职责是接收一个 Connector既可以是预先通过createConfig注册的实例也可以是即时创建的CreateConnectorFn触发连接流程并在成功后将连接状态写入全局Config包括connections、current、status返回完整的 Mutation 状态机idle/pending/error/success方便在 UI 中渲染加载、错误、成功等状态。从源码看useConnect位于 packages/react/src/hooks/useConnect.ts其实现通过useConfig获取全局配置、通过connectMutationOptions构建 TanStack Query 的 mutation 选项再由useMutation驱动执行。导入 useConnectuseConnect从wagmi包顶层导出import { useConnect } from wagmi此外若需要自定义 TanStack Query 集成如构建connectMutationOptions或在组件外调用可以从wagmi/query导入相关类型与工具import { type ConnectData, type ConnectVariables, type ConnectMutate, type ConnectMutateAsync, connectMutationOptions, } from wagmi/query这些导出由 packages/core/src/query/connect.ts 中的类型定义支撑ConnectData即ConnectReturnTypeConnectVariables即ConnectParameters而connectMutationOptions则负责把核心动作包装成 mutation 函数mutationFn: (variables) connect(config, variables)并固定mutationKey: [connect]。基础用法一键连接 Injected 钱包最直接的用法是在组件内调用useConnect()并把连接动作绑定到按钮点击事件上。以下示例通过injected()即时创建 Connector 并完成连接// index.tsx import { useConnect } from wagmi import { injected } from wagmi/connectors function App() { const connect useConnect() return ( button onClick{() connect.mutate({ connector: injected() })} Connect /button ) }需要说明的是connector参数既可以传CreateConnectorFn如上面的injected()也可以传一个已经创建的Connector实例。核心动作层packages/core/src/actions/connect.ts会判断若传入的是函数则通过config._internal.connectors.setup(parameters.connector)将其注册为正式 Connector若传入的是实例则直接使用。示例中引用的config来自config.ts它通过createConfig同时注册了mainnet与sepolia两条链// config.ts import { createConfig, http } from wagmi import { mainnet, sepolia } from wagmi/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })完整示例可参考仓库中的 site/snippets/react/config.ts。参数ParametersuseConnect的参数类型为UseConnectParameters定义为ConfigParameterconfig ConnectOptionsconfig, context见 packages/react/src/hooks/useConnect.ts。它包含两部分config与 TanStack Query 的 mutation 选项。config类型Config | undefined指定要使用的Config默认情况下从最近的WagmiProvider中获取。若你的应用存在多个配置或需要在 Provider 之外使用可以显式传入// index.tsx import { useConnect } from wagmi import { config } from ./config // [!code focus] function App() { const connect useConnect({ config, // [!code focus] }) }底层实现中useConfig(parameters)会优先使用参数里的config否则回退到 React Context 中的全局配置。mutationTanStack Query 参数useConnect支持传入以下 TanStack Query Mutation 参数。需要注意的是并非所有 TanStack Query 参数都被支持——像mutationFn、mutationKey这类参数被 wagmi 内部占用用于保证 Hook 正常工作用户不能覆盖下方列出的参数均可直接使用。参数类型说明gcTimenumber \| Infinity \| undefined未使用/非活动缓存数据在内存中保留的毫秒数设为Infinity可禁用垃圾回收。指定多个不同缓存时间时取最长者metaRecordstring, unknown \| undefined附加到 mutation 缓存条目上的额外信息可在onError、onSuccess等回调中访问networkModeonline \| always \| offlineFirst \| undefined网络模式默认onlineonError((error: ConnectErrorType, variables, context?) Promiseunknown \| unknown) \| undefinedmutation 失败时触发接收错误对象onMutate((variables) Promisecontext \| void \| context \| void) \| undefined在 mutation 函数执行前触发可用于乐观更新返回值会传递给onError与onSettledonSuccess((data, variables, context?) Promiseunknown \| unknown) \| undefinedmutation 成功时触发接收结果数据onSettled((data, error, variables, context?) Promiseunknown \| unknown) \| undefined无论成功或失败都会触发接收 data 或 errorqueryClientQueryClient使用自定义QueryClient否则使用最近上下文中的实例retryboolean \| number \| ((failureCount, error) boolean) \| undefined默认0false不重试true无限重试数字表示最大重试次数retryDelaynumber \| ((retryAttempt, error) number) \| undefined每次重试前的延迟毫秒数可传函数实现指数退避如attempt Math.min(attempt 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)或线性退避返回值Return TypeuseConnect的返回类型为UseConnectReturnType本质是 TanStack Query 的UseMutationReturnType与若干附加字段的组合见 packages/react/src/hooks/useConnect.ts。connectors类型readonly Connector[]已废弃deprecated建议改用useConnectors。迁移细节见 migrate-from-v2-to-v3 中 RemoveduseConnect.connectors/useReconnect.connectors 一节。返回通过createConfig全局配置的 Connector 列表适合用于渲染可选择的连接按钮列表// index.tsx import { useConnect } from wagmi function App() { const connect useConnect() return ( div {connect.connectors.map((connector) ( button key{connector.id} onClick{() connect.mutate({ connector })} {connector.name} /button ))} /div ) }在实现上connectors字段实际委托给了useConnectors({ config })见 packages/react/src/hooks/useConnect.ts。源码中的connect与connectAsync字段也已标记为废弃分别对应mutate与mutateAsync。mutate(variables: ConnectVariables, { onSuccess, onSettled, onError }) void触发连接的 mutation 函数调用时传入变量对象至少包含connector并可附带onSuccess、onError、onSettled回调variables传给connect动作的参数对象类型为ConnectVariables核心字段是connectorConnector | CreateConnectorFn与可选的chainId、withCapabilitiesonSuccess(data, variables, context) void成功后触发onError(error, variables, context) void失败后触发onSettled(data | undefined, error | null, variables, context) voidsettled 时触发若连续发起多次请求onSuccess只在最近一次调用成功后触发。mutateAsync(variables: ConnectVariables, { onSuccess, onSettled, onError }) PromiseConnectData与mutate类似但返回 Promise可被await适合在异步流程如表单提交、页面跳转前中使用。data类型ConnectData | undefined最近一次成功连接的结果默认undefined。其结构为{ accounts: readonly [Address, ...Address[]] chainId: number }其中accounts是至少包含一个地址的非空元组Address为0x开头的 40 位十六进制地址。若以withCapabilities: true发起连接accounts中的元素将扩展为{ address, capabilities }对象形态详见下文底层原理。error类型ConnectErrorType | nullmutation 遇到的错误对象若无错误则为null。ConnectErrorType涵盖ConnectorAlreadyConnectedError、用户拒绝请求错误UserRejectedRequestError、资源不可用 RPC 错误ResourceUnavailableRpcError以及基础错误类型见 packages/core/src/actions/connect.ts。状态类字段字段类型说明statusidle \| pending \| error \| successidle为初始状态pending表示正在执行error表示最近一次尝试失败success表示成功isIdle/isPending/isError/isSuccessboolean由status派生出的便捷布尔变量isPausedbooleanmutation 被暂停时为true与网络模式相关failureCountnumber失败次数每次失败递增成功后重置为0failureReasonConnectErrorType \| null重试的失败原因成功后重置为nullsubmittedAtnumbermutation 提交时的时间戳默认0variablesConnectVariables \| undefined传给mutate的变量对象默认undefinedreset() void将 mutation 内部状态重置为初始状态值得一提的实现细节useConnect在 Hook 内部订阅了全局Config的状态变化当连接状态从connected变为disconnected即用户断开连接时会自动调用mutation.reset()把 mutation 重置回idle状态见 packages/react/src/hooks/useConnect.ts从而避免旧的连接数据污染后续交互。底层原理一次连接请求的完整调用链从源码层面梳理调用connect.mutate({ connector })后的完整链路如下Hook 层useConnect内部的mutation.mutate被调用connect字段是它的别名。Query 适配层connectMutationOptions中固定的mutationFn被触发执行connect(config, variables)见 packages/core/src/query/connect.ts。动作层核心动作connect执行packages/core/src/actions/connect.ts关键步骤包括若connector是函数先通过config._internal.connectors.setup()注册检查是否重复连接若connector.uid config.state.current直接抛出ConnectorAlreadyConnectedError将全局状态置为status: connecting并向 connector 的 emitter 发送{ type: connecting }消息调用connector.connect(rest)真正发起钱包连接rest中剥离了connector本身保留chainId、withCapabilities等参数连接成功后绑定change/disconnect事件监听并把recentConnectorId写入 storage便于useReconnect恢复会话更新全局状态写入connections以connector.uid为键记录accounts、chainId、connector、current与status: connected返回{ accounts, chainId }。异常处理若连接失败会把状态恢复为之前的connected若已有连接或disconnected并抛出错误由 mutation 的error/status字段承载。关于withCapabilities的兼容处理connect动作对withCapabilities做了兼容处理见 packages/core/src/actions/connect.ts当withCapabilities: true时accounts返回{ address, capabilities }对象数组否则返回纯地址数组。源码中的注释表明这是为了向下游 connector 提供向后兼容的适配未来版本v3会移除默认行为。关于 chainId 的重要提示::: tip 并非所有 Connector 都支持直接连接指定chainId例如它们不支持编程式切换链。在这种情况下Connector 会连接到其底层 Provider如钱包当前所连接的链。 :::因此在发起带chainId的连接前应了解目标 Connector 的能力可通过getCapabilities等动作探测并在onError中妥善处理链切换不支持导致的错误。完整实战示例连接按钮 状态渲染 错误处理综合以上知识一个生产级的最小连接组件可以这样编写// index.tsx import { useConnect } from wagmi import { injected } from wagmi/connectors function App() { const { mutate, status, error, isPending } useConnect() const handleConnect () { mutate( { connector: injected() }, { onSuccess: (data) { console.log(Connected accounts:, data.accounts) console.log(Connected chainId:, data.chainId) }, onError: (err) { console.error(Connection failed:, err) }, }, ) } return ( div button onClick{handleConnect} disabled{isPending} {isPending ? Connecting... : Connect Wallet} /button {status success pConnected!/p} {error p style{{ color: red }}{error.message}/p} /div ) }若希望渲染多个钱包选项可将useConnect().connectors或推荐使用useConnectors与mutate({ connector })结合遍历渲染每个 Connector 的name与id。参考与延伸Connector 的完整概念与列表connectors 文档全局配置的创建方式createConfig 文档Provider 的接入方式WagmiProvider 文档底层核心动作connect 动作文档v2 → v3 迁移含useConnect.connectors废弃说明migrate-from-v2-to-v3相关源码useConnect Hook 实现、connect 核心动作、TanStack Query 适配层【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考