wagmi Solid useSwitchConnection 完整指南在多钱包连接之间切换的活动源【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmiuseSwitchConnection是wagmi/solid提供的一个 mutation 原语用于在多个钱包同时连接时切换当前生效的连接。本篇基于仓库中的 API 文档与源码实现完整覆盖该原语的导入方式、用法示例、全部参数config 与 TanStack Query mutation 选项、返回类型各字段并深入到wagmi/core底层switchConnectionaction 的状态变更逻辑读完后可在多钱包场景中实现可切换的连接 UI 并理解其底层原理。导入与定位useSwitchConnection从wagmi/solid包直接导出是一个 mutation 类型的原语区别于 query 原语它触发写操作并带有 pending/success/error 状态机import { useSwitchConnection } from wagmi/solid它对应的核心 action 是switchConnection。在 Solid 生态中该原语的实现位于 packages/solid/src/primitives/useSwitchConnection.ts。用法示例典型场景是用户先后连接了多个钱包例如 MetaMask 与 WalletConnectUI 上列出所有活跃连接点击按钮将指定连接器切换为当前连接。文档中的完整示例如下// index.tsx import { useConnections, useSwitchConnection } from wagmi/solid import { For } from solid-js function App() { const connections useConnections() const switchConnection useSwitchConnection() return ( div For each{connections()} {(connection) ( button onClick{() switchConnection.mutate({ connector: connection.connector })} Switch to {connection.connector.name} /button )} /For /div ) }// config.ts import { createConfig, http } from wagmi/solid import { mainnet, sepolia } from wagmi/solid/chains export const config createConfig({ chains: [mainnet, sepolia], transports: { [mainnet.id]: http(), [sepolia.id]: http(), }, })配套的 配置示例文件 展示了createConfig的基本形态。这里有两个要点值得结合源码说明useConnections是响应式列表。从 useConnections.ts 的源码可以看到它内部通过createSignalcreateEffect订阅了watchConnections任何连接增减都会自动刷新列表因此上面的For循环无需手动刷新。切换动作本身不改变连接集合。switchConnection只改变config.state中的current指针当前生效的连接器 uid因此切换前后useConnections()返回的列表不变变化的是useConnection()读取到的地址与链——这一点被 单元测试 精确验证依次连接 connector2 和 connector1 后mutate({ connector: connector2 })会使useConnection().address变为 connector2 的地址再切回 connector1 后地址与初始值一致。参数useSwitchConnection接受一个参数对象类型为useSwitchConnection.ParametersSolid 变体为useSwitchConnection.SolidParameters。与 React 版本不同Solid 的参数以 getter 函数Accessor形式传入以维持 Solid 的响应性import { useSwitchConnection } from wagmi/solid useSwitchConnection(() ({ config, // mutation options... }))从 源码签名 可以确认参数类型为AccessorSolidParametersconfig, context且默认值为() ({})——即不传任何参数也合法配置会从最近的WagmiProvider上下文获取。configConfig | undefined要使用的Config用于替代从最近的WagmiProvider中获取的配置。若省略则使用 Provider 注入的 config。mutation 选项以下参数对应 TanStack Query 的 mutation 参数。注意Wagmi 不支持传入全部 TanStack Query 参数——mutationFn、mutationKey等已被内部占用不可覆盖下列参数是受支持的子集。gcTimenumber | Infinity | undefined。未使用/非活动缓存数据在内存中保留的毫秒时长缓存变为非活动后经过该时长即被垃圾回收多处指定不同时长时取最长者设为Infinity则禁用垃圾回收。metaRecordstring, unknown | undefined。附加到 mutation 缓存条目上的额外信息可在mutate可用的任意位置如onError、onSuccess回调中访问。networkModeonline | always | offlineFirst | undefined默认online。控制离线时的行为参见 TanStack Query 的 Network Mode 文档。onError(error: SwitchConnectionErrorType, variables: { connector: Connector }, context?: context) Promiseunknown | unknown。mutation 出错时触发。onMutate(variables: { connector: Connector }) Promisecontext | void | context | void。在 mutation 执行前触发接收与 mutation 函数相同的变量适合做乐观更新返回值会传入失败时的onError与onSettled可用于回滚。onSuccess(data: void, variables, context?) Promiseunknown | unknown。mutation 成功时触发。onSettled(data, error, variables, context?) Promiseunknown | unknown。无论成功或失败都会触发。queryClientQueryClient。使用自定义QueryClient否则使用最近上下文中的实例。retryboolean | number | ((failureCount: number, error: SwitchConnectionErrorType) boolean)默认0。false不重试true无限重试数字则重试到失败次数达到该值。retryDelaynumber | ((retryAttempt: number, error: SwitchConnectionErrorType) number)。接收重试轮次与错误返回下次重试前的等待毫秒数例如attempt Math.min(attempt 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)为指数退避。关于variables中的connector类型它是wagmi/core的Connector实例通常直接来自useConnections()列表中每一项的connection.connector字段见上文示例无需手动构造。返回类型返回值为 TanStack Query mutation 对象类型useSwitchConnection.ReturnType各字段如下mutate(variables: { connector: Connector }, { onSuccess, onSettled, onError }) void。触发 mutation 的函数可附带一次性回调。mutateAsync同上但返回Promisevoid可await。datavoid | undefined。switchConnection的返回类型经Compute计算后为voidaction 实际返回accounts与chainId但 query 层声明为void默认为undefined记录最近一次成功的数据。errorSwitchConnectionErrorType | null。发生错误时的错误对象。failureCountnumber。失败次数每次失败递增成功后归零。failureReasonSwitchConnectionErrorType | null。触发重试的失败原因成功后置null。isError / isIdle / isPending / isSuccessboolean由status派生。isPausedboolean。mutation 处于暂停状态network mode 相关时为true。reset() void。清空 mutation 内部状态重置为初始状态。statusidle | pending | error | success。idle为初始态pending执行中error/success为最近一次尝试的结果。submittedAtnumber。mutation 提交时间戳默认0。variables{ connector: Connector } | undefined。传入mutate的变量默认undefined。SwitchConnectionErrorType具体包括ConnectorNotConnectedErrorType、BaseError与ErrorType见 actions/switchConnection.ts。其中最常见的是ConnectorNotConnectedError——当目标连接器尚未处于已连接状态时抛出下文详述。底层实现从 primitive 到 action 的调用链从源码结构看useSwitchConnection的完整调用链为createMutation来自 tanstack/solid-query→switchConnectionMutationOptions→switchConnectionaction。第一步query 层包装。switchConnection.tscore/query 中的switchConnectionMutationOptions负责把用户传入的 mutation 选项与内部固定的mutationFn、mutationKey合并export function switchConnectionMutationOptionsconfig extends Config, context( config: config, options: SwitchConnectionOptionsconfig, context {}, ): SwitchConnectionMutationOptionsconfig { return { ...(options.mutation as any), mutationFn(variables) { return switchConnection(config, variables) }, mutationKey: [switchConnection], } }这解释了为什么mutationFn、mutationKey不可覆盖它们在展开用户选项之后才被赋值始终指向 core 的switchConnectionaction且 key 固定为[switchConnection]。第二步action 层的状态变更。switchConnectionaction 的核心逻辑只有三步const connection config.state.connections.get(connector.uid) if (!connection) throw new ConnectorNotConnectedError() await config.storage?.setItem(recentConnectorId, connector.id) config.setState((x) ({ ...x, current: connector.uid, })) return { accounts: connection.accounts, chainId: connection.chainId, }校验连接存在按connector.uid在config.state.connections中查找连接记录找不到即抛ConnectorNotConnectedError。因此不能通过useSwitchConnection去连接一个未连接的钱包——它只负责在既有连接之间切换未连接的钱包应使用useConnect。持久化最近使用的连接器若配置了storage会把recentConnectorId写入其中便于应用重启后恢复上次使用的钱包。更新current指针将config.state.current设为目标连接器的 uid。这一步是切换的关键——所有读取当前连接的 API如 Solid 端的useConnection()、core 端的connectionaction都以此指针为准因此切换后它们会立即反映新地址与新链。错误处理建议由于mutate是异步状态机推荐用返回的isPending/isError信号驱动 UISolid 中它们是可读响应式变量或在mutate的第二个参数里传入一次性onError回调捕获具体错误对象。测试验证useSwitchConnection.test.ts 用一个双连接器场景验证了行为边界先依次connect两个连接器再通过原语来回mutate断言useConnection().address随切换在两个不同地址之间变更、且切回后恢复原值最后disconnect清理。该测试同时说明了测试基础设施wagmi/test的 mock config 与renderPrimitive的组织方式可作为自行编写原语测试的参考。小结useSwitchConnection是 mutation 原语参数以Accessor形式传入以维持 Solid 响应性核心变量只有一个目标connector。它仅切换config.state.current指针并持久化recentConnectorId不改变已连接集合目标连接器未连接时会抛ConnectorNotConnectedError。返回完整 TanStack Query mutation 接口mutate/mutateAsync/status/isPending等支持retry、回调等受支持选项mutationFn与mutationKey由 Wagmi 内部固定不可覆盖。与 useConnections 配合可完整实现列出所有连接 一键切换的多钱包 UI。【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考