useNetwork

跟蹤瀏覽器網路連接狀況

useNetwork 使用 Network Information API 和線上/離線事件提供有關使用者網路連線的詳細資訊。它回傳一個物件，包含 online 狀態、連線 type、effectiveType（2g/3g/4g）、downlink 速度、rtt（往返時間）以及是否正在使用行動數據等資訊。

使用場景

  • 根據網路速度自適應調整內容品質（例如影像解析度、影片品質）
  • 在使用者離線或連線品質差時顯示警告
  • 實作離線優先策略，根據網路狀態決定資料同步行為

注意事項

  • SSR 安全：在伺服器端渲染時所有值回傳 undefined。伺服器上不會存取 navigator 或 window 事件。
  • Network Information API：詳細的連線屬性（downlink、effectiveType、rtt、type）僅在基於 Chromium 的瀏覽器中可用。online 狀態則普遍支援。
  • 相關 hooks：另請參閱 useOnline 用於更簡單的網路連線狀態布林值封裝。

Usage

Live Editor

function Demo() {
  const state = useNetwork();

  return <pre>{JSON.stringify(state, null, 2)}</pre>;
};
Result

API

useNetwork

Returns

IUseNetworkState

Arguments

IUseNetworkState

參數名描述類型預設值
online浏览器是否连接网络boolean | undefined (必填)-
previousonline 属性的先前值。 帮助识别浏览器是否刚刚连接或失去连接。boolean | undefined (必填)-
since{Date} 对象指向状态更改发生的时刻。Date | undefined (必填)-
downlink有效带宽估计（以兆位每秒为单位），四舍五入到25 kbps 的最接近倍数。INetworkInformation['downlink'] | undefined (必填)-
downlinkMax最大下行链路速度，以兆比特每秒 (Mbps) 为单位INetworkInformation['downlinkMax'] | undefined (必填)-
effectiveType连接的有效类型，表示“slow-2g”、“2g”、“3g”或“4g”之一。该值是根据最近观察到的往返时间和和下行链路值的组合确定的INetworkInformation['effectiveType'] | undefined (必填)-
rtt当前连接的估计有效往返时间，四舍五入精确到 25 毫秒的最接近倍数INetworkInformation['rtt'] | undefined (必填)-
saveData如果用户在用户代理上设置了减少数据使用选项，则为 {true}。INetworkInformation['saveData'] | undefined (必填)-
type设备用于与网络通信的连接类型。它将是以下值之一：- 蓝牙- 蜂窝网络- 以太网- 没有任何- 无线上网- 无线麦克斯- 其他- 未知INetworkInformation['type'] | undefined (必填)-

INetworkInformation

export interface INetworkInformation extends EventTarget {
  readonly downlink: number;
  readonly downlinkMax: number;
  readonly effectiveType: 'slow-2g' | '2g' | '3g' | '4g';
  readonly rtt: number;
  readonly saveData: boolean;
  readonly type: 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
  onChange: (event: Event) => void;
}