译零 TransZero · TanStack Query 中文文档
主站

网络模式

更新于 2026-11-02 Preact 查看英文原文 ↗

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'

本页为 TanStack Query 文档(Preact 版)的非官方中文翻译,原文由上游团队维护,遵循 MIT 许可。 译文如有偏差,以英文原文为准。

译自上游 59d11de