在鸿蒙HarmonyOS开发中实时监听网络状态是保障应用体验的核心能力。当用户在 Wi-Fi、4G、5G 等网络间切换时应用需及时响应如提示网络变化、调整下载并发数避免因网络波动导致卡顿或流量浪费。鸿蒙通过kit.NetworkKit中的ohos.net.connection模块提供标准化的网络状态监听接口。以下是完整的实战开发指南一、 环境准备与权限配置网络状态监听属于敏感操作必须在module.json5中声明相关权限requestPermissions: [ { name: ohos.permission.INTERNET }, { name: ohos.permission.GET_NETWORK_INFO } ]二、 核心代码网络状态监听与类型识别通过createNetConnection创建网络连接对象注册各类网络变化事件并在回调中解析当前网络类型。import { connection } from kit.NetworkKit; import { BusinessError } from kit.BasicServicesKit; Entry Component struct NetworkMonitorDemo { private netConnection: connection.NetConnection connection.createNetConnection(); aboutToAppear() { this.startNetworkMonitor(); } private startNetworkMonitor() { // 1. 注册网络订阅必须先注册才能接收后续事件 this.netConnection.register((error: BusinessError) { if (error) { console.error(网络注册监听失败:, JSON.stringify(error)); return; } console.info(网络注册监听成功); }); // 2. 监听网络可用事件 this.netConnection.on(netAvailable, (data: connection.NetHandle) { console.info(网络可用, netId: ${data.netId}); }); // 3. 监听网络能力变化核心用于识别网络类型切换 this.netConnection.on(netCapabilitiesChange, (data: connection.NetCapabilityInfo) { const bearerTypes data.netCap?.bearerTypes; const networkCaps data.netCap?.networkCap; // 解析网络类型Wi-Fi / 蜂窝网络 if (bearerTypes?.includes(connection.NetBearType.BEARER_WIFI)) { console.info(当前网络类型: Wi-Fi); } else if (bearerTypes?.includes(connection.NetBearType.BEARER_CELLULAR)) { console.info(当前网络类型: 蜂窝网络 (4G/5G)); } // 解析网络能力如是否真正可访问互联网 if (networkCaps?.includes(connection.NetCap.NET_CAPABILITY_VALIDATED)) { console.info(网络已验证可正常访问互联网); } }); // 4. 监听网络丢失事件如断开 Wi-Fi 且无蜂窝网络 this.netConnection.on(netLost, (data: connection.NetHandle) { console.warn(网络丢失, netId: ${data.netId}); }); // 5. 监听网络不可用事件如连上了 Wi-Fi 但无法上网 this.netConnection.on(netUnavailable, () { console.warn(当前网络不可用); }); } aboutToDisappear() { // 退出页面时取消订阅防止内存泄漏 this.netConnection.unregister((error: BusinessError) { if (error) { console.error(取消网络监听失败:, JSON.stringify(error)); } }); } build() { Column({ space: 20 }) { Text(网络状态监听演示) .fontSize(24) .fontWeight(FontWeight.Bold) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }三、 进阶结合状态管理实现 UI 联动在实际业务中网络状态通常需要全局共享并驱动 UI 更新。推荐使用AppStorage结合StorageProp和Watch实现响应式联动。// 1. 在工具类或全局监听中将状态写入 AppStorage this.netConnection.on(netCapabilitiesChange, (data) { let isNetAvailable data.netCap?.networkCap?.includes(connection.NetCap.NET_CAPABILITY_VALIDATED); AppStorage.setOrCreate(isNetAvailable, isNetAvailable ?? false); }); // 2. 在 UI 组件中监听状态变化 StorageProp(isNetAvailable) Watch(onNetworkChanged) isNetAvailable: boolean true; onNetworkChanged() { if (this.isNetAvailable) { console.info(网络已恢复执行重新连接/恢复下载逻辑); } else { console.warn(网络已断开暂停下载并提示用户); } }开发建议与注意事项区分netLost与netUnavailablenetLost网络严重中断或正常断开如手动关闭 Wi-Fi。netUnavailable网络已连接但不可用如连上了 Wi-Fi 但路由器未连外网图标显示感叹号。网络切换的事件触发顺序当设备从 Wi-Fi 切换到蜂窝网络时系统会先触发netLostWi-Fi 丢失再触发netAvailable蜂窝网络可用。在开发重连逻辑时需注意时序。低功耗设计鸿蒙网络监听采用事件订阅机制仅在状态变化时唤醒应用回调避免了持续轮询带来的高耗电问题。不支持主动切换系统原生能力仅支持通过回调“感知”网络切换不支持应用主动进行网络切换。四、 精准识别蜂窝网络代际5G/4G/3G/2G基础的connection模块只能区分出当前是否处于“蜂窝网络”状态。如果需要精准识别当前是 5G、4G 还是 3G需要结合ohos.telephony.radio模块获取信号信息。核心代码示例import { connection } from kit.NetworkKit; import { radio } from kit.TelephonyKit; // 当监听到当前网络为蜂窝网络时进一步获取具体代际 async function getCellularGeneration() { try { // 获取当前设备的信号信息列表支持双卡 const signalInfos await radio.getSignalInformation(); if (signalInfos signalInfos.length 0) { // 获取主卡的信号类型 const signalType signalInfos[0].signalType; switch (signalType) { case radio.NetworkType.NETWORK_TYPE_NR: console.info(当前蜂窝网络: 5G); break; case radio.NetworkType.NETWORK_TYPE_LTE: console.info(当前蜂窝网络: 4G); break; case radio.NetworkType.NETWORK_TYPE_WCDMA: case radio.NetworkType.NETWORK_TYPE_TDSCDMA: console.info(当前蜂窝网络: 3G); break; default: console.info(当前蜂窝网络: 2G/未知); break; } } } catch (err) { console.error(获取蜂窝网络代际失败); } }五、 弱网状态感知ASCF 框架在音视频通话、实时游戏等对网络延迟敏感的场景中仅知道“网络是否连接”是不够的还需要感知当前是否处于“弱网”状态。鸿蒙 ASCF 框架提供了专门的弱网监听接口。核心代码示例import { has } from kit.ASCFKit; // 假设基于 ASCF 框架 // 监听弱网状态变化 has.onNetworkWeakChange((res) { console.info(弱网状态变更: ${res.weakNet}, 当前网络类型: ${res.networkType}); if (res.weakNet) { // 弱网策略降低视频码率、减少心跳频率、暂停后台预加载等 console.warn(检测到弱网正在切换至低画质模式...); } else { // 网络恢复恢复正常策略 console.info(网络状况良好恢复标准画质); } }); // 在生命周期中取消监听 has.offNetworkWeakChange();六、 多网并发与连接迁移Network Boost Kit对于大型文件下载、直播推流等高吞吐业务鸿蒙提供了 Network Boost Kit允许应用感知多网并发状态例如同时使用 Wi-Fi 和蜂窝网络从而制定更优的数据传输策略。核心代码示例import { netHandover } from kit.NetworkBoostKit; import { BusinessError } from kit.BasicServicesKit; // 订阅多网状态信息变化 try { netHandover.on(multiPathStateChange, (data: netHandover.MultiPathStateInfo) { console.info(多网状态变化: JSON.stringify(data)); // 根据多网状态调整并发下载线程数或传输策略 }); } catch (err) { console.error(监听多网状态失败: (err as BusinessError).message); } // 业务结束时取消订阅 try { netHandover.off(multiPathStateChange); } catch (err) { console.error(取消多网状态监听失败: (err as BusinessError).message); }七、 网络质量量化监控延迟、带宽、信号强度在音视频通话、实时游戏等对网络延迟极度敏感的场景中除了感知“弱网”还需要获取具体的网络质量指标如 RTT 延迟、上下行带宽、信号强度 RSRP。由于系统可能没有直接提供实时的质量变化监听通常采用定时主动探测的方式来实现。核心代码示例import { connection } from kit.NetConnectionKit; // 定义网络质量模型 interface NetworkQuality { level: EXCELLENT | GOOD | FAIR | POOR | UNKNOWN; signalStrength: number; latency: number; bandwidth: number; } // 定时检测网络质量 async function measureNetworkQuality(): PromiseNetworkQuality { const startTime Date.now(); try { // 通过发起轻量级请求来测量延迟RTT await fetch(https://connectivitycheck.gstatic.com/generate_204, { timeout: 5000 }); const latency Date.now() - startTime; // 根据延迟评估质量等级 let level: NetworkQuality[level] UNKNOWN; if (latency 100) level EXCELLENT; else if (latency 300) level GOOD; else if (latency 800) level FAIR; else level POOR; return { level, signalStrength: 0, latency, bandwidth: 0 }; } catch (err) { return { level: POOR, signalStrength: 0, latency: -1, bandwidth: 0 }; } } // 每 5 秒执行一次质量评估 setInterval(async () { const quality await measureNetworkQuality(); console.info(当前网络质量: ${quality.level}, 延迟: ${quality.latency}ms); }, 5000);八、 智能 DNS 解析在多网络并存或复杂网络环境下直接使用域名发起请求可能会遇到 DNS 劫持或解析缓慢的问题。鸿蒙提供了系统级的智能 DNS 解析接口可以直接获取目标域名的 IP 地址列表便于应用层自行管理连接。核心代码示例import { connection } from kit.NetworkKit; async function resolveDomain() { try { const addresses await connection.getAddressesByName(www.example.com); console.info(解析到的 IP 地址列表:, addresses.join(, )); // 业务层可使用解析出的 IP 直接建立连接绕过系统默认 DNS } catch (err) { console.error(DNS 解析失败:, (err as BusinessError).message); } }九、 底层网络状态强制修正在某些极端场景下如底层网卡驱动异常、代理软件干扰应用内部记录的网络状态可能与系统网络管理器不一致。鸿蒙提供了强制报告网络状态的接口用于纠正系统的误判。核心代码示例import { connection } from kit.NetworkKit; // 当发现网络状态异常且确认当前网络不可用时强制向系统报告网络断开 function forceReportDisconnect(badNetHandle: connection.NetHandle) { connection.reportNetDisconnected(badNetHandle); console.warn(已强制报告网络断开); } // 当确认某个网络句柄实际可用但系统未识别时强制报告连接 function forceReportConnect(goodNetHandle: connection.NetHandle) { connection.reportNetConnected(goodNetHandle); console.info(已强制报告网络连接); }底层通信资源管控与避坑在复杂的网络切换过程中底层通信资源的管理至关重要处理不当极易导致内存泄漏或请求异常。Socket 资源强制释放当监听到网络切换如 Wi-Fi 切 5G或网络丢失时必须主动关闭旧的 Socket 连接。旧的网络句柄在新的网络环境下已失效继续持有会导致资源泄漏。推荐使用高级通信套件在多网络频繁切换的场景下强烈建议使用kit.RemoteCommunicationKit替代原生的 HTTP 模块它内置了更好的连接池管理和网络异常恢复机制。紧急情况下的状态修正当遇到应用内部记录的网络状态与系统管理器不一致时例如应用认为已断网但系统实际可用可以调用connection.reportNetDisconnected(badNetHandle)或connection.reportNetConnected(goodNetHandle)强制向系统报告网络状态。生命周期严格绑定网络监听会持续占用系统资源。务必在EntryAbility的onCreate中开启订阅在onWindowStageDestroy中关闭订阅防止应用进入后台后仍进行不必要的状态回调。
网络状态监听：监听网络连接类型(WiFi/5G)变化（41）
在鸿蒙HarmonyOS开发中实时监听网络状态是保障应用体验的核心能力。当用户在 Wi-Fi、4G、5G 等网络间切换时应用需及时响应如提示网络变化、调整下载并发数避免因网络波动导致卡顿或流量浪费。鸿蒙通过kit.NetworkKit中的ohos.net.connection模块提供标准化的网络状态监听接口。以下是完整的实战开发指南一、 环境准备与权限配置网络状态监听属于敏感操作必须在module.json5中声明相关权限requestPermissions: [ { name: ohos.permission.INTERNET }, { name: ohos.permission.GET_NETWORK_INFO } ]二、 核心代码网络状态监听与类型识别通过createNetConnection创建网络连接对象注册各类网络变化事件并在回调中解析当前网络类型。import { connection } from kit.NetworkKit; import { BusinessError } from kit.BasicServicesKit; Entry Component struct NetworkMonitorDemo { private netConnection: connection.NetConnection connection.createNetConnection(); aboutToAppear() { this.startNetworkMonitor(); } private startNetworkMonitor() { // 1. 注册网络订阅必须先注册才能接收后续事件 this.netConnection.register((error: BusinessError) { if (error) { console.error(网络注册监听失败:, JSON.stringify(error)); return; } console.info(网络注册监听成功); }); // 2. 监听网络可用事件 this.netConnection.on(netAvailable, (data: connection.NetHandle) { console.info(网络可用, netId: ${data.netId}); }); // 3. 监听网络能力变化核心用于识别网络类型切换 this.netConnection.on(netCapabilitiesChange, (data: connection.NetCapabilityInfo) { const bearerTypes data.netCap?.bearerTypes; const networkCaps data.netCap?.networkCap; // 解析网络类型Wi-Fi / 蜂窝网络 if (bearerTypes?.includes(connection.NetBearType.BEARER_WIFI)) { console.info(当前网络类型: Wi-Fi); } else if (bearerTypes?.includes(connection.NetBearType.BEARER_CELLULAR)) { console.info(当前网络类型: 蜂窝网络 (4G/5G)); } // 解析网络能力如是否真正可访问互联网 if (networkCaps?.includes(connection.NetCap.NET_CAPABILITY_VALIDATED)) { console.info(网络已验证可正常访问互联网); } }); // 4. 监听网络丢失事件如断开 Wi-Fi 且无蜂窝网络 this.netConnection.on(netLost, (data: connection.NetHandle) { console.warn(网络丢失, netId: ${data.netId}); }); // 5. 监听网络不可用事件如连上了 Wi-Fi 但无法上网 this.netConnection.on(netUnavailable, () { console.warn(当前网络不可用); }); } aboutToDisappear() { // 退出页面时取消订阅防止内存泄漏 this.netConnection.unregister((error: BusinessError) { if (error) { console.error(取消网络监听失败:, JSON.stringify(error)); } }); } build() { Column({ space: 20 }) { Text(网络状态监听演示) .fontSize(24) .fontWeight(FontWeight.Bold) } .width(100%) .height(100%) .justifyContent(FlexAlign.Center) } }三、 进阶结合状态管理实现 UI 联动在实际业务中网络状态通常需要全局共享并驱动 UI 更新。推荐使用AppStorage结合StorageProp和Watch实现响应式联动。// 1. 在工具类或全局监听中将状态写入 AppStorage this.netConnection.on(netCapabilitiesChange, (data) { let isNetAvailable data.netCap?.networkCap?.includes(connection.NetCap.NET_CAPABILITY_VALIDATED); AppStorage.setOrCreate(isNetAvailable, isNetAvailable ?? false); }); // 2. 在 UI 组件中监听状态变化 StorageProp(isNetAvailable) Watch(onNetworkChanged) isNetAvailable: boolean true; onNetworkChanged() { if (this.isNetAvailable) { console.info(网络已恢复执行重新连接/恢复下载逻辑); } else { console.warn(网络已断开暂停下载并提示用户); } }开发建议与注意事项区分netLost与netUnavailablenetLost网络严重中断或正常断开如手动关闭 Wi-Fi。netUnavailable网络已连接但不可用如连上了 Wi-Fi 但路由器未连外网图标显示感叹号。网络切换的事件触发顺序当设备从 Wi-Fi 切换到蜂窝网络时系统会先触发netLostWi-Fi 丢失再触发netAvailable蜂窝网络可用。在开发重连逻辑时需注意时序。低功耗设计鸿蒙网络监听采用事件订阅机制仅在状态变化时唤醒应用回调避免了持续轮询带来的高耗电问题。不支持主动切换系统原生能力仅支持通过回调“感知”网络切换不支持应用主动进行网络切换。四、 精准识别蜂窝网络代际5G/4G/3G/2G基础的connection模块只能区分出当前是否处于“蜂窝网络”状态。如果需要精准识别当前是 5G、4G 还是 3G需要结合ohos.telephony.radio模块获取信号信息。核心代码示例import { connection } from kit.NetworkKit; import { radio } from kit.TelephonyKit; // 当监听到当前网络为蜂窝网络时进一步获取具体代际 async function getCellularGeneration() { try { // 获取当前设备的信号信息列表支持双卡 const signalInfos await radio.getSignalInformation(); if (signalInfos signalInfos.length 0) { // 获取主卡的信号类型 const signalType signalInfos[0].signalType; switch (signalType) { case radio.NetworkType.NETWORK_TYPE_NR: console.info(当前蜂窝网络: 5G); break; case radio.NetworkType.NETWORK_TYPE_LTE: console.info(当前蜂窝网络: 4G); break; case radio.NetworkType.NETWORK_TYPE_WCDMA: case radio.NetworkType.NETWORK_TYPE_TDSCDMA: console.info(当前蜂窝网络: 3G); break; default: console.info(当前蜂窝网络: 2G/未知); break; } } } catch (err) { console.error(获取蜂窝网络代际失败); } }五、 弱网状态感知ASCF 框架在音视频通话、实时游戏等对网络延迟敏感的场景中仅知道“网络是否连接”是不够的还需要感知当前是否处于“弱网”状态。鸿蒙 ASCF 框架提供了专门的弱网监听接口。核心代码示例import { has } from kit.ASCFKit; // 假设基于 ASCF 框架 // 监听弱网状态变化 has.onNetworkWeakChange((res) { console.info(弱网状态变更: ${res.weakNet}, 当前网络类型: ${res.networkType}); if (res.weakNet) { // 弱网策略降低视频码率、减少心跳频率、暂停后台预加载等 console.warn(检测到弱网正在切换至低画质模式...); } else { // 网络恢复恢复正常策略 console.info(网络状况良好恢复标准画质); } }); // 在生命周期中取消监听 has.offNetworkWeakChange();六、 多网并发与连接迁移Network Boost Kit对于大型文件下载、直播推流等高吞吐业务鸿蒙提供了 Network Boost Kit允许应用感知多网并发状态例如同时使用 Wi-Fi 和蜂窝网络从而制定更优的数据传输策略。核心代码示例import { netHandover } from kit.NetworkBoostKit; import { BusinessError } from kit.BasicServicesKit; // 订阅多网状态信息变化 try { netHandover.on(multiPathStateChange, (data: netHandover.MultiPathStateInfo) { console.info(多网状态变化: JSON.stringify(data)); // 根据多网状态调整并发下载线程数或传输策略 }); } catch (err) { console.error(监听多网状态失败: (err as BusinessError).message); } // 业务结束时取消订阅 try { netHandover.off(multiPathStateChange); } catch (err) { console.error(取消多网状态监听失败: (err as BusinessError).message); }七、 网络质量量化监控延迟、带宽、信号强度在音视频通话、实时游戏等对网络延迟极度敏感的场景中除了感知“弱网”还需要获取具体的网络质量指标如 RTT 延迟、上下行带宽、信号强度 RSRP。由于系统可能没有直接提供实时的质量变化监听通常采用定时主动探测的方式来实现。核心代码示例import { connection } from kit.NetConnectionKit; // 定义网络质量模型 interface NetworkQuality { level: EXCELLENT | GOOD | FAIR | POOR | UNKNOWN; signalStrength: number; latency: number; bandwidth: number; } // 定时检测网络质量 async function measureNetworkQuality(): PromiseNetworkQuality { const startTime Date.now(); try { // 通过发起轻量级请求来测量延迟RTT await fetch(https://connectivitycheck.gstatic.com/generate_204, { timeout: 5000 }); const latency Date.now() - startTime; // 根据延迟评估质量等级 let level: NetworkQuality[level] UNKNOWN; if (latency 100) level EXCELLENT; else if (latency 300) level GOOD; else if (latency 800) level FAIR; else level POOR; return { level, signalStrength: 0, latency, bandwidth: 0 }; } catch (err) { return { level: POOR, signalStrength: 0, latency: -1, bandwidth: 0 }; } } // 每 5 秒执行一次质量评估 setInterval(async () { const quality await measureNetworkQuality(); console.info(当前网络质量: ${quality.level}, 延迟: ${quality.latency}ms); }, 5000);八、 智能 DNS 解析在多网络并存或复杂网络环境下直接使用域名发起请求可能会遇到 DNS 劫持或解析缓慢的问题。鸿蒙提供了系统级的智能 DNS 解析接口可以直接获取目标域名的 IP 地址列表便于应用层自行管理连接。核心代码示例import { connection } from kit.NetworkKit; async function resolveDomain() { try { const addresses await connection.getAddressesByName(www.example.com); console.info(解析到的 IP 地址列表:, addresses.join(, )); // 业务层可使用解析出的 IP 直接建立连接绕过系统默认 DNS } catch (err) { console.error(DNS 解析失败:, (err as BusinessError).message); } }九、 底层网络状态强制修正在某些极端场景下如底层网卡驱动异常、代理软件干扰应用内部记录的网络状态可能与系统网络管理器不一致。鸿蒙提供了强制报告网络状态的接口用于纠正系统的误判。核心代码示例import { connection } from kit.NetworkKit; // 当发现网络状态异常且确认当前网络不可用时强制向系统报告网络断开 function forceReportDisconnect(badNetHandle: connection.NetHandle) { connection.reportNetDisconnected(badNetHandle); console.warn(已强制报告网络断开); } // 当确认某个网络句柄实际可用但系统未识别时强制报告连接 function forceReportConnect(goodNetHandle: connection.NetHandle) { connection.reportNetConnected(goodNetHandle); console.info(已强制报告网络连接); }底层通信资源管控与避坑在复杂的网络切换过程中底层通信资源的管理至关重要处理不当极易导致内存泄漏或请求异常。Socket 资源强制释放当监听到网络切换如 Wi-Fi 切 5G或网络丢失时必须主动关闭旧的 Socket 连接。旧的网络句柄在新的网络环境下已失效继续持有会导致资源泄漏。推荐使用高级通信套件在多网络频繁切换的场景下强烈建议使用kit.RemoteCommunicationKit替代原生的 HTTP 模块它内置了更好的连接池管理和网络异常恢复机制。紧急情况下的状态修正当遇到应用内部记录的网络状态与系统管理器不一致时例如应用认为已断网但系统实际可用可以调用connection.reportNetDisconnected(badNetHandle)或connection.reportNetConnected(goodNetHandle)强制向系统报告网络状态。生命周期严格绑定网络监听会持续占用系统资源。务必在EntryAbility的onCreate中开启订阅在onWindowStageDestroy中关闭订阅防止应用进入后台后仍进行不必要的状态回调。
