useNetworkStatus 是一个基于 Vue Composition API 封装的响应式网络状态检测 Hook,初始化时读取 navigator.onLine,监听 online/offline 事件并自动清理;可选集成心跳检测提升准确性,并利用 navigator.connection 辅助识别弱网场景,支持参数配置与全局复用。

用 Vue Composition API 实现网络状态的实时检测,核心是封装一个响应式、可复用的 useNetworkStatus 组合式函数,监听 window 的 online/offline 事件,并结合 navigator.onLine 初始化状态。它比 Options API 更简洁,也更容易在多个组件间共享逻辑。
基础实现:监听 online/offline 事件
直接在 setup 中注册事件监听器,用 ref 存储当前状态,并确保组件卸载时自动清理:
- 定义
isOnline = ref(navigator.onLine),初始值取浏览器当前判断 - 在
onMounted中添加window.addEventListener('online', () => isOnline.value = true)和对应offline事件 - 在
onBeforeUnmount中移除监听,避免内存泄漏 - 返回
isOnline,供模板或逻辑使用:v-if="!isOnline" 显示离线提示
增强可靠性:加入心跳检测(可选)
navigator.onLine 有局限性——比如 WiFi 已连但服务器不通,它仍返回 true。为减少误判,可叠加轻量心跳:
- 用
setInterval每 8–15 秒发起一次无副作用的 HEAD 请求(如/health或/ping) - 请求成功 → 视为“真在线”,设
isOnline.value = true - 连续失败 2 次 → 设
isOnline.value = false,并暂停后续心跳直到恢复 - 注意:心跳 URL 需支持跨域且不带敏感头,避免触发预检或鉴权拦截
适配移动端与弱网场景(进阶)
借助 navigator.connection 可获取更细粒度信息,用于策略调整而非状态判定主逻辑:
- 检查
if ('connection' in navigator),再读取effectiveType(如'slow-2g')或downlink(如) - 当检测到弱网时,可动态设置:
isOnSlowNetwork = true,用于降级 UI(如隐藏图片、禁用自动播放) - 监听
connection.addEventListener('change', handler)做实时响应,但不做断网依据——仅作辅助提示 - iOS Safari 对该 API 支持有限,需做存在性判断,不抛错也不强依赖
封装成可复用的自定义 Hook
把上述逻辑抽成 useNetworkStatus(),支持传参控制是否启用心跳、自定义心跳地址等:
- 返回对象包含:
isOnline、isOnSlowNetwork、effectiveType、downlink - 内部自动处理生命周期清理、防抖切换提示(避免 1 秒内反复触发 online/offline)
- 配合
provide/inject或 Pinia,在根组件初始化一次,全局消费 - 已有成熟方案可参考
@vueuse/core中的useNetwork,它已内置重试、延迟更新和类型推导
大量免费API接口:立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游,为数据API应用能力赋能!










