企业官网建设流程全解析

Wagmi Vue useDisconnect 完全指南：断开连接 Composable 的用法、参数与源码剖析

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi

useDisconnect 是@wagmi/vue提供的一个响应式 Composable，用于断开当前钱包与应用的连接（disconnect）。它在连接切换、账户登出、多账户管理等场景中扮演着收尾角色：用户点击“Disconnect”按钮后，它会清理掉当前的 connection 状态，并让useConnection、useAccount等状态随之变为 disconnected。读完本文，你将掌握 useDisconnect 的导入方式、完整参数与返回值、基于 TanStack Query 的 mutation 用法，以及它底层如何通过disconnectaction 更新 config 状态。

Import

useDisconnect从@wagmi/vue包中导出，直接引入即可：

import { useDisconnect } from '@wagmi/vue'

从源码结构看，该导出由 packages/vue/src/exports/index.ts 统一对外暴露，Nuxt 模块 packages/vue/src/nuxt/module.ts 中同样复用了它，因此无论你是纯 Vue 3 项目还是 Nuxt 项目，导入路径一致。

Usage

基础用法：一个按钮断开连接

最典型的使用方式是在组件中调用useDisconnect()获取 mutation，然后在按钮的点击事件中触发mutate()：

<script setup lang="ts"> import { useDisconnect } from '@wagmi/vue' const disconnect = useDisconnect() </script> <template> <button @click="disconnect.mutate()"> Disconnect </button> </template>

对应的 config 配置示例可参考 site/snippets/vue/config.ts。需要说明的是，上面的示例会断开当前（current）连接；如果你想指定断开某个特定连接，可以像下面这样传入connector：

<script setup lang="ts"> import { useDisconnect } from '@wagmi/vue' import { useConnections } from '@wagmi/vue' import { config } from './config' const { connections } = useConnections() const disconnect = useDisconnect() function onDisconnect() { // 断开第一个连接对应的 connector disconnect.mutate({ connector: connections.value[0]?.connector }) } </script>

与 useConnection 联动验证

仓库中的单元测试 packages/vue/src/composables/useDisconnect.test.ts 完整演示了 useDisconnect 与useConnection的联动：先通过connect建立连接，断言address已定义、status为'connected'；调用disconnect.mutate()后，等待isDisconnected变为 true，最终address变为 undefined、status变为'disconnected'。这印证了 useDisconnect 会同步驱动所有依赖连接状态的响应式数据更新。

Parameters

useDisconnect的参数类型为UseDisconnectParameters：

import { type UseDisconnectParameters } from '@wagmi/vue'

config

Config | undefined

传入一个Config实例以替代从WagmiPlugin中自动获取的默认 config。在大多数情况下你不需要传它，只有当你显式管理多个 config 实例、或需要在插件上下文之外使用时才需要指定：

<script setup lang="ts"> import { useDisconnect } from '@wagmi/vue' import { config } from './config' const disconnect = useDisconnect({ config, }) </script>

从源码看（packages/vue/src/composables/useDisconnect.ts），useDisconnect内部通过useConfig(parameters)解析 config，并通过useConnections({ config })获取当前全部连接，因此即使你传入了自定义 config，连接列表的获取也会保持一致。

mutation

TanStack Query 的 mutation 参数。注意：Wagmi 出于内部实现需要，不允许覆盖mutationFn与mutationKey（它们被固定为指向disconnectaction 与['disconnect']），其余 TanStack Query mutation 选项均可使用，包括：

• gcTime：number | Infinity | undefined，非活动缓存数据在内存中保留的毫秒数，设为Infinity可禁用垃圾回收。
• meta：Record<string, unknown> | undefined，附加到 mutation 缓存条目的额外信息，可在onError、onSuccess等回调中访问。
• networkMode：'online' | 'always' | 'offlineFirst' | undefined，默认'online'，用于控制离线时的网络行为。
• onError：(error, variables, context?) => ...，mutation 出错时触发。
• onMutate：(variables) => ...，在 mutation 执行前触发，常用于乐观更新，返回值会传递给onError与onSettled。
• onSuccess：(data, variables, context?) => ...，mutation 成功时触发。
• onSettled：(data, error, variables, context?) => ...，无论成败都会触发。
• queryClient：QueryClient，指定自定义 QueryClient，否则使用最近上下文中的实例。
• retry：boolean | number | ((failureCount, error) => boolean) | undefined，默认0（不重试），true无限重试，数字则限制重试次数。
• retryDelay：number | ((retryAttempt, error) => number) | undefined，控制重试间隔，可用指数退避或线性退避函数。

示例——在断开前做乐观 UI 更新、成功后弹提示：

<script setup lang="ts"> import { useDisconnect } from '@wagmi/vue' import { useConnections } from '@wagmi/vue' const { connections } = useConnections() const disconnect = useDisconnect({ mutation: { onMutate(variables) { // 断开前的乐观更新：例如先将本地 UI 置为 disconnected console.log('onMutate', variables) }, onSuccess() { console.log('已断开连接') }, onError(error) { console.error('断开失败', error) }, }, }) </script>

Return Type

useDisconnect返回UseDisconnectReturnType：

import { type UseDisconnectReturnType } from '@wagmi/vue'

返回值本质是一个 TanStack Query mutation 返回值（通过 packages/vue/src/utils/query.ts 中的UseMutationReturnType封装），并额外暴露了三个 Vueref/方法。字段说明如下：

注意data的类型是void——disconnectaction 成功时并不返回任何业务数据，你更多依赖status、isSuccess或useConnection的状态来判断断开是否完成。

其中status的取值语义：'idle'为执行前初始状态，'pending'表示正在执行，'error'表示上次尝试失败，'success'表示上次尝试成功。

TanStack Query 类型导入

若需要显式声明类型，可从@wagmi/vue/query导入与 disconnect 相关的 mutation 类型：

import { type DisconnectData, type DisconnectVariables, type DisconnectMutate, type DisconnectMutateAsync, disconnectMutationOptions, } from '@wagmi/vue/query'

其中DisconnectData即void，DisconnectVariables为DisconnectParameters | undefined（即{ connector?: Connector } | undefined），disconnectMutationOptions用于在非组件环境下直接构造 mutation 选项。

Action

useDisconnect底层调用的是 core 包中的disconnectaction（文档原链接指向disconnect，此处以仓库实际源码为准）。该 action 的完整执行流程如下（packages/core/src/actions/disconnect.ts）：

1. 解析目标 connector：若传入parameters.connector则使用它，否则从config.state中取current对应的连接及其 connector。
2. 调用connector.disconnect()：通知钱包端断开，同时移除change与disconnect事件监听、恢复connect事件监听，避免断开后继续响应旧的变更事件。
3. 从 connections Map 中删除该连接。
4. 更新 config 状态：若连接列表已空，则重置为disconnected状态（current: null）；否则自动切换到下一个连接作为新的current。
5. 持久化 recentConnectorId：若存在新的 current 连接，将recentConnectorId写入 storage，供下次自动重连使用。

mutation 选项的桥接

在 core 包的 packages/core/src/query/disconnect.ts 中，disconnectMutationOptions将options.mutation与固定的mutationFn、mutationKey: ['disconnect']合并。useDisconnect正是通过disconnectMutationOptions(config, parameters)构造选项后交给useMutation（见 packages/vue/src/composables/useDisconnect.ts），这也是前文“不允许覆盖mutationFn/mutationKey”的原因。

错误类型

disconnect可能抛出的错误类型（DisconnectErrorType）包括：ConnectorNotFoundError（未找到指定 connector）、ConnectorNotConnectedError（指定 connector 未连接），以及基类错误。类型断言测试见 packages/vue/src/composables/useDisconnect.test-d.ts，其中验证了onError收到的 error 类型为DisconnectErrorType、onSuccess收到的 data 类型为void。

完整实战示例

最后给出一个带连接状态提示的完整组件，将本文内容串起来：

<script setup lang="ts"> import { useDisconnect, useConnection } from '@wagmi/vue' const { connections } = useConnection() // 当前连接 const disconnect = useDisconnect({ mutation: { onSuccess: () => alert('连接已断开'), onError: (error) => console.error('断开失败：', error), }, }) const isConnected = connections.status.value === 'connected' </script> <template> <button v-if="isConnected" :disabled="disconnect.status.value === 'pending'" @click="disconnect.mutate()" > {{ disconnect.status.value === 'pending' ? '断开中...' : 'Disconnect' }} </button> </template>

这样，按钮会随着连接状态自动显示/隐藏，并在断开过程中禁用，避免用户重复点击。

【免费下载链接】wagmiReactive primitives for Ethereum apps项目地址: https://gitcode.com/GitHub_Trending/wa/wagmi