TanStack Query中的OnlineManager网络状态管理详解

TanStack Query中的OnlineManager网络状态管理详解

query 🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query. 项目地址: https://gitcode.com/gh_mirrors/qu/query

前言

在现代Web应用开发中，网络连接状态的管理至关重要。TanStack Query作为一个强大的数据同步库，提供了OnlineManager这一专门用于管理网络状态的工具类。本文将深入解析OnlineManager的工作原理、使用场景和最佳实践。

OnlineManager的核心作用

OnlineManager是TanStack Query中负责管理网络连接状态的模块，它主要解决以下问题：

1. 自动检测浏览器在线/离线状态变化
2. 提供手动控制网络状态的接口
3. 统一管理网络状态变更的订阅机制

设计原理与演进

早期版本中，OnlineManager依赖于navigator.onLineAPI来判断网络状态。但在实际使用中发现：

• Chromium内核浏览器存在大量误报问题
• 经常出现"误判"（实际在线但被误判为离线）
• 服务工作者(Service Worker)场景下判断不准确

为解决这些问题，新版OnlineManager采用了更可靠的策略：

1. 乐观假设：默认认为应用处于在线状态
2. 事件驱动：仅通过online/offline事件来更新状态
3. 可扩展性：允许开发者自定义状态检测逻辑

核心API详解

1. setEventListener - 自定义事件监听

onlineManager.setEventListener((setOnline) => {
  return NetInfo.addEventListener((state) => {
    setOnline(!!state.isConnected)
  })
})

使用场景：

• React Native等非浏览器环境
• 需要更精确网络检测的业务场景
• 替代默认的浏览器事件监听

注意事项：

• 回调函数应返回一个取消订阅的函数
• 设置新的监听器会覆盖之前的监听器

2. subscribe - 状态变更订阅

const unsubscribe = onlineManager.subscribe((isOnline) => {
  console.log('网络状态变更:', isOnline)
})

典型应用：

• 显示网络状态提示UI
• 记录网络状态日志
• 根据网络状态调整应用行为

3. setOnline - 手动设置状态

// 强制设置为在线状态
onlineManager.setOnline(true)

// 强制设置为离线状态
onlineManager.setOnline(false)

使用建议：

• 测试离线功能时手动模拟
• 在某些特殊业务逻辑中覆盖自动检测
• 谨慎使用，可能影响查询行为

4. isOnline - 获取当前状态

const currentStatus = onlineManager.isOnline()

返回值：布尔值，表示当前是否在线

最佳实践

1. 移动端适配：在React Native中使用NetInfo替代默认检测
2. 状态同步：确保UI与网络状态保持同步
3. 错误处理：结合错误重试机制提供更好用户体验
4. 服务工作者场景：特别注意可能的误判情况

常见问题解决方案

问题1：如何判断真正的网络可用性而不仅是浏览器在线状态？

方案：通过setEventListener实现自定义检测逻辑，例如增加API心跳检测。

问题2：服务工作者缓存导致误判在线怎么办？

方案：结合setOnline手动控制状态，或实现更复杂的检测逻辑。

总结

TanStack Query的OnlineManager提供了灵活而强大的网络状态管理能力。通过理解其设计原理和掌握核心API的使用方法，开发者可以构建出在各种网络环境下都能稳定运行的应用程序。无论是简单的状态检测还是复杂的自定义逻辑，OnlineManager都能提供可靠的支持。

query 🤖 Powerful asynchronous state management, server-state utilities and data fetching for the web. TS/JS, React Query, Solid Query, Svelte Query and Vue Query. 项目地址: https://gitcode.com/gh_mirrors/qu/query