网络模式

TanStack Query 提供了三种不同的网络模式，用于控制 Queries 和 Mutations 在没有网络连接时的行为。你可以针对每个 Query/Mutation单独设置网络模式，也可以通过全局默认配置进行统一设置。

由于 TanStack Query 主要用于数据获取，并且通常与数据获取库配合使用，因此默认的网络模式是online。

网络模式：online

在这种模式下，Queries和Mutations只有在有网络连接时才会触发。这是默认模式。

• 如果查询已经开始，但由于没有网络连接无法进行请求，它会始终保持当前状态（pending、error、success）。

• 同时fetchStatus 也会暴露额外的信息，它的值可能是：

  • fetching：queryFn 正在执行，网络请求正在进行中。

  • paused：查询未执行，它会暂停，直到重新连接网络。

  • idle：查询既未进行请求，也未处于暂停状态。

• isFetching 和 isPaused 这两个标志是从 fetchStatus 派生出来的，方便使用。

注意

仅仅检查pending状态可能不足以判断是否显示加载动画。 如果查询首次挂载且没有网络连接，它的state可能是pending，但 fetchStatus 却是 'paused'。

📌 关于离线时的重试机制：

• 如果查询在联网状态下开始，但在请求过程中掉线，TanStack Query 会暂停重试。

• 当网络恢复时，暂停的查询会继续执行（这不同于refetchOnReconnect，后者默认也是true）。

• 如果查询在此期间被取消，它将不会继续执行。

网络模式：always

在此模式下，TanStack Query 将始终执行获取操作，而不会考虑在线/离线状态。如果你在一个不需要网络连接的环境中使用 TanStack Query，例如只从AsyncStorage读取数据，或者你的queryFn只是返回Promise.resolve(5)，那么这可能是你想要选择的模式。

• Queries永远不会因为没有网络连接而暂停。

• Retries也不会暂停,如果查询失败，它将直接进入error状态。

• refetchOnReconnect在此模式下默认设置为false，因为重新连接到网络不再是一个可靠的指标来判断是否应该重新获取过期的查询数据。当然，如果你需要，你仍然可以手动开启它。

网络模式：offlineFirst

这种模式是前两种选项之间的折中方案，其中 TanStack Query 会执行queryFn一次，但随后会暂停重试。这在某些情况下非常有用，比如：

• 你有一个serviceWorker用于拦截请求并进行缓存（例如在离线优先的 PWA 中）。

• 你使用Cache-Control头进行 HTTP 缓存。

在这些情况下，首次请求可能会成功，因为数据可能来自离线存储或缓存。然而，如果缓存未命中（cache miss），网络请求会被发送出去并可能失败，在这种情况下，此模式的行为就会像在线查询一样暂停重试。