网络模式

TanStack Query 提供三种不同的网络模式，用于区分在无网络连接时 Queries 和 Mutations 的行为。该模式可为每个 Query / Mutation 单独设置，也可通过查询 / 修改默认配置全局设置。

由于 TanStack Query 最常与数据拉取库配合用于数据拉取，其默认网络模式为 online。

网络模式：online

在此模式下，仅当存在网络连接时，Query 和 Mutation 才会触发。这是默认模式。如果因无网络连接而无法发起查询拉取，则该查询将始终停留在其当前状态 state（pending、error、success）中。不过，此模式额外暴露了 fetchStatus，其值可能为以下之一：

• fetching：queryFn 正在真实执行中——请求正在进行。
• paused：查询未执行——它将保持 paused 状态，直至你重新获得网络连接。
• idle：查询既未拉取，也未暂停。

标志 isFetching 和 isPaused 由此状态派生，并为方便起见予以暴露。

请注意，仅检查 pending 状态可能不足以显示加载指示器。Query 可能处于 state: 'pending' 状态，但若其首次挂载且你无网络连接，则 fetchStatus: 'paused'。

若 Query 因你在线而运行，但在拉取过程中你转为离线，TanStack Query 也会暂停重试机制。已暂停的 Query 将在你重新获得网络连接后继续执行。这与 refetchOnReconnect（在此模式下同样默认为 true）无关，因为它并非 refetch，而是一种 continue。若该 Query 在此期间已被 cancelled，则不会继续执行。

网络模式：always

在此模式下，TanStack Query 始终执行拉取，并忽略 online / offline 状态。如果你在无需活跃网络连接即可使 Query 正常工作的环境中使用 TanStack Query（例如仅从 AsyncStorage 读取，或仅希望从 queryFn 返回 Promise.resolve(5)），那么此模式很可能正是你的首选。

• Query 永远不会因无网络连接而进入 paused 状态。
• 重试也不会暂停——若 Query 失败，它将进入 error 状态。
• refetchOnReconnect 在此模式下默认为 false，因为重新连接网络已不再是一个可靠的信号，表明过期的 Query 应被重新拉取。你仍可手动启用它。

网络模式：offlineFirst

此模式介于前两种之间：TanStack Query 将执行一次 queryFn，随后暂停重试。当你使用 serviceWorker 拦截请求以实现缓存（如 offline-first PWA 中），或通过 Cache-Control header 使用 HTTP 缓存时，此模式非常实用。

在这些场景中，首次拉取可能成功，因为它来自离线存储 / 缓存。然而，若发生缓存未命中，网络请求将发出并失败；此时该模式的行为将类似于 online 查询——暂停重试。

开发者工具

TanStack Query Devtools 会在无网络连接但 Query 本应拉取时，将其显示为 paused 状态。其中还提供一个 Mock offline behavior（模拟离线行为）切换按钮。请注意，该按钮不会实际干扰你的网络连接（你可在浏览器开发者工具中执行该操作），而是将 OnlineManager 设为离线状态。

签名

• networkMode: 'online' | 'always' | 'offlineFirst'
  • 可选
  • 默认为 'online'