useOnline

1"use client"
2 
3import * as React from "react"
4 
5export interface UseOnlineOptions {
6  /** SSR 及 hydration 前使用的快照值。默认 `true`——多数访问发生在联网状态下,
7   *  假定在线比假定离线更少造成误报的"离线横幅"闪烁。 */
8  serverFallback?: boolean
9}
10 
11/**
12 * 订阅浏览器的网络在线状态,返回它当前是否在线。用 `useSyncExternalStore`
13 * 把 `window` 的 `online`/`offline` 事件这个外部数据源接进 React 渲染树:
14 * subscribe 挂两个事件监听、getSnapshot 读 `navigator.onLine`、
15 * getServerSnapshot 在服务端渲染时返回 `serverFallback`。零 `useEffect` +
16 * `setState`。
17 *
18 * **诚实边界**:`navigator.onLine` 只反映"这台设备有没有连上一个网络接口"
19 * (Wi-Fi/以太网/蜂窝),**不保证"能到达你的服务器"**——连着 Wi-Fi 但那条
20 * Wi-Fi 本身断了外网时,大多数浏览器仍会把 `navigator.onLine` 报告为
21 * `true`。这是浏览器 API 本身的语义(它检测的是网络接口层,不是端到端可达
22 * 性),不是这个 hook 的实现缺陷。如果需要"服务是否真的可达",要主动探测
23 * (定时 `fetch` 一个健康检查端点),这个 hook 不做这件事——它只回答"设备
24 * 有没有网络接口"。
25 */
26export function useOnline(options: UseOnlineOptions = {}): boolean {
27  const { serverFallback = true } = options
28 
29  const subscribe = React.useCallback((callback: () => void) => {
30    if (typeof window === "undefined") return () => {}
31    window.addEventListener("online", callback)
32    window.addEventListener("offline", callback)
33    return () => {
34      window.removeEventListener("online", callback)
35      window.removeEventListener("offline", callback)
36    }
37  }, [])
38 
39  const getSnapshot = React.useCallback(() => navigator.onLine, [])
40  const getServerSnapshot = React.useCallback(() => serverFallback, [serverFallback])
41 
42  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
43}
44 
45export default useOnline