TanStack Query 提供了三种不同的网络模式,用于区分在无网络连接时查询(Queries)和变更(Mutations)的行为。该模式可以针对每个查询/变更单独设置,也可以通过查询/变更的全局默认值进行配置。
由于 TanStack Query 最常与数据获取库配合使用,其默认网络模式为在线模式(online)。
在此模式下,只有存在网络连接时才会触发查询和变更。这是默认模式。如果因无网络连接导致查询请求无法发起,该查询将始终保持当前状态(pending、error、success)。此外,系统会额外暴露一个获取状态(fetchStatus),其可能值为:
为方便使用,系统会根据此状态派生出isFetching和isPaused标志。
需注意:仅检查pending状态可能不足以显示加载动画。如果首次挂载查询时无网络连接,查询可能处于state: 'pending'但fetchStatus: 'paused'状态。
若查询因网络在线而启动,但在获取过程中断网,TanStack Query 也会暂停重试机制。暂停的查询将在恢复网络连接后继续执行。此行为与refetchOnReconnect(该模式默认值为true)无关,因为这不是"重新获取",而是"继续执行"。若查询期间被取消(cancelled),则不会继续。
在此模式下,TanStack Query 会忽略在线/离线状态始终执行获取。如果您在不需要活跃网络连接的环境中(例如仅从AsyncStorage读取数据,或queryFn直接返回Promise.resolve(5))使用 TanStack Query,此模式是理想选择。
此模式是前两种模式的折中方案,TanStack Query 会执行一次queryFn,但暂停后续重试。这对于使用Service Worker拦截请求实现缓存的离线优先PWA,或通过Cache-Control头实现HTTP缓存的场景非常实用。
在这些场景中,首次获取可能因离线存储/缓存而成功。若缓存未命中,网络请求将发出并失败,此时该模式的行为与online查询相同——暂停重试。
TanStack Query开发者工具会显示处于paused状态的查询——这些查询本应获取数据但因断网而暂停。工具还提供模拟离线行为的切换按钮。请注意该按钮不会实际干扰网络连接(您可在浏览器开发者工具中操作),而是会将OnlineManager设置为离线状态。