wagmi 的 useChains Hook 完全指南获取与响应式订阅已配置的链【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseChains是 wagmi React 包中用于读取「已配置链configured chains」的 Hook返回值直接来自createConfig的chains配置项并以内置的响应式订阅方式保证配置变化时组件自动重渲染。本文以 useChains 官方文档 为主体结合仓库源码深入讲解其导入方式、参数、返回类型与底层实现帮助你在实际 DApp 中正确读取链列表并理解其响应式原理。Import 导入方式useChains从wagmi包顶层导出无需从子路径引入import { useChains } from wagmi从源码结构看该导出定义于 packages/react/src/hooks/useChains.ts同时被 packages/react/src/exports/index.ts 聚合导出因此import { useChains } from wagmi即可直接使用。该文件首行为use client指令表明这是一个客户端专用 Hook适用于 React含 Next.js App Router 等环境。Usage 基本用法useChains是一个零参数即可调用的 Hook参数可选见下文。最基础的用法如下import { useChains } from wagmi function App() { const chains useChains() }在典型应用中你需要在组件树根部通过WagmiProvider注入配置使useChains能自动从最近的 Context 中解析到config详见 WagmiProvider 文档import { WagmiProvider } from wagmi import { config } from ./config function App() { return ( WagmiProvider config{config} {/** ... */} /WagmiProvider ) }配套的配置文件可参考 site/snippets/react/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(), }, })此时useChains()将返回[mainnet, sepolia]两个 viemChain对象。由于返回值是链对象数组你可以结合 viem 链属性如chain.id、chain.name、chain.nativeCurrency直接驱动 UI例如渲染链选择器function ChainSwitcher() { const chains useChains() return ( select {chains.map((chain) ( option key{chain.id} value{chain.id} {chain.name} /option ))} /select ) }Parameters 参数import { type UseChainsParameters } from wagmiUseChainsParameters在源码中定义为ConfigParameterconfig见 packages/react/src/hooks/useChains.ts即仅包含一个可选参数。config类型Config | undefined作用指定要使用的Config覆盖从最近的WagmiProvider自动获取的配置。当你的应用在同一组件树中存在多个配置、或需要在 Provider 之外独立使用某个配置时可以显式传入::: code-groupimport { useChains } from wagmi import { config } from ./config // [!code focus] function App() { const chains useChains({ config, // [!code focus] }) }:::关于config参数的解析逻辑可以参见 packages/react/src/hooks/useConfig.ts 的实现parameters.config ?? useContext(WagmiContext)——即优先使用显式传入的config否则回退到WagmiContext若两者都不存在则抛出WagmiProviderNotFoundError。这也解释了为什么useChains默认必须在WagmiProvider内部调用。Return Type 返回类型import { type UseChainsReturnType } from wagmi类型readonly [Chain, ...Chain[]]含义来自config.chains的链列表是一个非空只读元组。UseChainsReturnType在源码中直接复用 core 层的GetChainsReturnTypeconfig即config[chains]见 packages/core/src/actions/getChains.ts。因为createConfig的泛型约束要求chains必须是readonly [Chain, ...Chain[]]非空元组见 packages/core/src/createConfig.ts所以返回类型天然保证至少包含一个链类型系统层面杜绝了空数组的解构问题。Action 底层动作getChainscore 层动作useChains并非独立实现链读取逻辑而是薄封装了 core 层的getChains动作与watchChains订阅详见 packages/react/src/hooks/useChains.tsreturn useSyncExternalStore( (onChange) watchChains(config, { onChange }), () getChains(config), () getChains(config), )下面从源码层面拆解这条链路。getChains同步读取packages/core/src/actions/getChains.ts 的核心实现非常简洁直接返回config.chains即createConfig内部 store 的状态并通过deepEqual做缓存优化——若与上次读取的链列表深度相等则复用上一次的引用避免不必要的新对象分配进而减少下游组件的重渲染let previousChains: readonly Chain[] [] export function getChainsconfig extends Config( config: config, ): GetChainsReturnTypeconfig { const chains config.chains if (deepEqual(previousChains, chains)) return previousChains as GetChainsReturnTypeconfig previousChains chains return chains as unknown as GetChainsReturnTypeconfig }在createConfig内部config.chains对应chains.getState()的快照见 packages/core/src/createConfig.ts因此getChains永远返回当前已配置链的准确值。watchChains响应式订阅packages/core/src/actions/watchChains.ts 被标记为internal它通过config._internal.chains.subscribe订阅链状态变化一旦链列表变更即回调onChange(chains, prevChains)export function watchChainsconfig extends Config( config: config, parameters: WatchChainsParametersconfig, ): WatchChainsReturnType { const { onChange } parameters return config._internal.chains.subscribe((chains, prevChains) { onChange( chains as unknown as GetChainsReturnTypeconfig, prevChains as unknown as GetChainsReturnTypeconfig, ) }) }代码注释明确说明从使用者视角看config.chains在运行时通常不可变通过config._internal.chains.setState(...)在运行时动态修改链列表属于极其高级的用法官方暂不将其纳入公开 API 文档。而useChains借助 React 的useSyncExternalStore将watchChains的订阅与getChains的快照读取桥接到组件渲染上实现链配置变更时的自动更新这也与源码注释中的设计意图一致。响应式行为验证packages/react/src/hooks/useChains.test.ts 中的测试直接验证了上述响应式行为default测试在默认测试配置下useChains()返回id为1Ethereum、456、10OP Mainnet的链序列parameters: config测试显式传入config参数时结果一致behavior: chains updates测试通过config._internal.chains.setState([chain.mainnet, chain.mainnet2])动态更新链列表后useChains的返回值随之变为两个链再调用setState恢复原值后返回值又回到三个链——完整证明了 Hook 的响应式更新能力。典型使用场景结合上述特性useChains的典型应用场景包括链选择器 UI渲染所有已配置链供用户切换常与useSwitchChain配合参见 packages/react/src/hooks/useSwitchChain.ts 中对useChains的引用读取当前链配置信息如原生货币、区块浏览器地址、RPC URL 等 viemChain属性校验用户当前网络将useAccount返回的chainId与useChains()返回的链id集合比对判断是否需要引导切换网络。小结useChains是 wagmi 中结构最简单、但极具代表性的 Hook它展示了「core 动作 React 响应式桥接」这一 wagmi 的通用架构模式。掌握它也就同时理解了getChains的读取语义、watchChains的订阅机制以及useSyncExternalStore在 wagmi 中的应用方式可为阅读其他 wagmi Hook 源码打下基础。如需了解chains配置项的完整定义与createConfig的其他选项可继续阅读 createConfig 文档 与 core 层 getChains 文档。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考