wagmi 的 useConnectors Hook 完全指南读取与响应式订阅已配置的连接器【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseConnectors是 wagmi React 包中用于获取已配置连接器Connectors的核心 Hook。本文围绕 useConnectors.md 文档展开结合 wagmi 仓库源码React Hook 实现、core 层 Action 与测试用例系统讲解其导入方式、基本用法、返回类型、底层响应式原理以及在钱包连接 UI 中的实战应用帮助读者在 React 应用中准确获取并实时跟踪连接器列表的变化。什么是 useConnectors在 wagmi 中连接器Connector是应用与钱包如 MetaMask、WalletConnect、Coinbase Wallet 等之间的桥梁负责建立连接、管理账户状态与链上交互。这些连接器由createConfig在创建配置时统一注册useConnectors则负责在 React 组件中读取这份注册表。useConnectors是面向 React 的 Hook它本质上是对 core 层getConnectorsAction 的 React 封装内部通过useSyncExternalStore订阅连接器存储store一旦连接器集合发生变化例如动态添加了新的连接器组件会自动重新渲染并拿到最新列表。对应文档site/react/api/hooks/useConnectors.mdImport如何导入 useConnectors与 wagmi 的其他 React Hooks 一样useConnectors直接从wagmi包导入import { useConnectors } from wagmiHook 源码位于 packages/react/src/hooks/useConnectors.ts文件首行声明了use client表明它只能在客户端组件环境中使用——这一点在使用 Next.js App Router 等 SSR 框架时需要特别注意避免在服务端渲染阶段调用。如果你使用的是框架适配包Solid / Vue对应的实现分别为 packages/solid/src/primitives/useConnectors.ts 与 packages/vue/src/composables/useConnectors.tsAPI 语义保持一致。Usage在组件中获取连接器列表最基本的使用方式是在任意组件内调用 Hook直接获得connectors数组import { useConnectors } from wagmi function App() { const connectors useConnectors() // connectors 为 readonly Connector[]可遍历渲染钱包列表 return ( ul {connectors.map((connector) ( li key{connector.uid}{connector.name}/li ))} /ul ) }注意useConnectors只是读取已配置的连接器它不会触发任何连接动作。典型的场景是把返回结果交给useConnect的connectors参数从而渲染出一个钱包选择列表用户点击某个钱包后再真正发起连接。参考 React 指南 connect-wallet.md。使用该 Hook 需要先通过createConfig建立配置并提供给WagmiProvider。一个最小可用的配置如下对应 config.tsimport { createConfig, http } from wagmi import { mainnet, sepolia } from wagmi/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })在上面的配置中未显式传入connectors此时 wagmi 会使用默认的injected连接器即浏览器内置钱包如 MetaMask 扩展。若要注册多个钱包可在createConfig中通过connectors选项传入连接器工厂函数数组例如import { createConfig, http } from wagmi import { mainnet } from wagmi/chains import { injected } from wagmi/connectors import { metaMask } from wagmi/connectors import { walletConnect } from wagmi/connectors export const config createConfig({ chains: [mainnet], connectors: [ injected(), metaMask(), walletConnect({ projectId: YOUR_PROJECT_ID }), ], transports: { [mainnet.id]: http(), }, })此时useConnectors()返回的数组将包含这三个连接器实例。在 packages/core/src/createConfig.ts 中可以看到createConfig会遍历rest.connectors中每个工厂函数并调用它们将生成的连接器实例统一存入内部的 connector store。Return Type返回类型详解文档中给出的返回类型声明为import { type UseConnectorsReturnType } from wagmi其实际类型为readonly Connector[]即只读的连接器数组元素是Connector实例数据来源是config.connectorscreateConfig内部 connector store 的状态。从源码 packages/react/src/hooks/useConnectors.ts 可以看到React 层直接复用了 core 的类型export type UseConnectorsParametersconfig extends Config Config ConfigParameterconfig export type UseConnectorsReturnTypeconfig extends Config Config GetConnectorsReturnTypeconfig而GetConnectorsReturnType在 packages/core/src/actions/getConnectors.ts 中定义为export type GetConnectorsReturnTypeconfig extends Config Config config[connectors]也就是说Hook 的返回类型与createConfig的泛型配置强关联config[connectors]本身就是readonly Connector[]形态TypeScript 可以根据配置自动推导出精确的数组类型无需手动标注。可选参数configuseConnectors接受一个可选的参数对象{ config }用于在未包裹WagmiProvider的场景下显式传入配置实例。源码中的useConfig(parameters)会优先取参数里的config否则从 Context 中读取。测试用例 useConnectors.test.ts 验证了这一点test(parameters: config, async () { const { result } await renderHook(() useConnectors({ config }), { wrapper: ({ children }) createElement(Fragment, { children }), }) expect(result.current).toBeDefined() })该测试使用Fragment作为 wrapper即不提供WagmiProvider证实了通过{ config }参数传入配置时 Hook 同样可以正常工作。Action底层对应的 getConnectorsuseConnectors对应的底层 Action 是getConnectors它属于 core 包可从wagmi/core导入import { getConnectors } from wagmi/core import { config } from ./config const connectors getConnectors(config)对应文档site/core/api/actions/getConnectors.md。两者的返回类型完全一致readonly Connector[]差别仅在于getConnectors是一次性读取而useConnectors额外提供了响应式订阅能力。引用缓存Reference Caching优化值得注意的细节是getConnectors.ts 对返回值做了引用级缓存let previousConnectors: readonly Connector[] [] export function getConnectorsconfig extends Config( config: config, ): GetConnectorsReturnTypeconfig { const connectors config.connectors if ( previousConnectors.length connectors.length previousConnectors.every( (connector, index) connector connectors[index], ) ) return previousConnectors previousConnectors connectors return connectors }只要连接器数组的长度不变、且每个元素引用一致就复用上一次的数组引用。这一优化对 React 的渲染性能很重要它保证在连接器未发生变化时useConnectors每次返回的是同一引用从而避免触发无关组件的无意义重渲染。核心测试 getConnectors.test.ts 连续两次调用并断言结果与config.connectors相等验证了返回值的一致性。响应式原理useSyncExternalStore watchConnectorsuseConnectors之所以能实时反映连接器变化是因为它结合了 React 18 的useSyncExternalStore与 core 层的watchConnectorsAction。完整实现如下useConnectors.tsreturn useSyncExternalStore( (onChange) watchConnectors(config, { onChange }), () getConnectors(config), () getConnectors(config), )其中useSyncExternalStore的三个参数分别是订阅函数subscribe、读取快照函数getSnapshot与服务端渲染快照函数getServerSnapshot。这里订阅与快照读取均复用了 SSR 安全的实现意味着该 Hook 天然兼容服务端渲染场景。订阅的核心在 core 层的 watchConnectors.tsexport function watchConnectorsconfig extends Config( config: config, parameters: WatchConnectorsParametersconfig, ): WatchConnectorsReturnType { const { onChange } parameters return config._internal.connectors.subscribe((connectors, prevConnectors) { onChange(Object.values(connectors), prevConnectors) }) }可以看到watchConnectors直接订阅了config._internal.connectors这个内部 store其实现位于 createConfig.ts暴露了setState与subscribe接口。一旦有人通过setState更新连接器集合订阅回调就会被触发进而驱动 React 重新渲染。动态连接器的场景尽管大多数应用中连接器列表在创建配置后就固定不变但 wagmi 的 store 设计允许在运行时动态追加连接器。测试用例 useConnectors.test.ts 演示了这一场景test(default, async () { const { result, rerender } await renderHook(() useConnectors()) const count config.connectors.length expect(result.current.length).toBe(count) expect(result.current).toEqual(config.connectors) config._internal.connectors.setState(() [ ...config.connectors, config._internal.connectors.setup(mock({ accounts })), ]) rerender() expect(result.current.length).toBe(count 1) })该测试先断言初始返回的连接器数量与config.connectors一致随后向内部 store 追加一个 mock 连接器并触发重渲染最终断言useConnectors返回的数组长度增加了 1。这从侧面验证了 Hook 的响应式更新链路store 状态变更 → watchConnectors 订阅回调 → useSyncExternalStore 触发重渲染 → 返回新连接器数组。实战结合 useConnect 渲染钱包选择器useConnectors最常见的实战形态是与useConnect搭配渲染一个钱包选择列表。示例import { useConnect, useConnectors } from wagmi function WalletList() { const connectors useConnectors() const { connect, status } useConnect() return ( ul {connectors.map((connector) ( li key{connector.uid} button disabled{status pending} onClick{() connect({ connector })} {connector.name} /button /li ))} /ul ) }几点实操提示key 的选择优先使用connector.uid作为列表key它是每个连接器实例的唯一标识若连接器可能重复注册使用uid比name更安全。只读数组返回类型为readonly Connector[]不能直接对数组进行push/splice等修改操作若需要派生新数组请先浅拷贝如[...connectors]。SSR 环境Hook 声明为use client在 Next.js 等框架中请将其放在客户端组件中调用其内部同时提供getServerSnapshot可在服务端渲染时安全地输出快照。连接器属性每个Connector实例上可通过connector.name、connector.id等元数据渲染钱包品牌信息但具体展示效果取决于连接器实现。小结useConnectors是 wagmi React 体系中读取已配置连接器的标准入口核心要点可总结为维度说明导入import { useConnectors } from wagmi返回类型readonly Connector[]即UseConnectorsReturnType数据来源createConfig中注册的config.connectors底层 ActiongetConnectors一次性读取含引用缓存响应式机制useSyncExternalStorewatchConnectors订阅内部 store常用搭配与useConnect结合渲染钱包选择列表框架适配同语义实现见 packages/solid/src/primitives/useConnectors.ts 与 packages/vue/src/composables/useConnectors.ts阅读完本文后你可以通过查看 packages/react/src/hooks/useConnectors.ts、packages/core/src/actions/getConnectors.ts、packages/core/src/actions/watchConnectors.ts 及其对应测试文件深入理解该 Hook 的完整实现链路。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考