引言在移动应用开发中网络状态管理是一个看似简单却极易出错的环节。用户可能在 Wi-Fi 和蜂窝网络之间切换可能进入飞行模式也可能连接到按流量计费的热点。一个健壮的应用需要感知这些变化并做出合理响应——在网络恢复时自动重试请求在按流量计费时降低图片质量在完全断网时展示友好的离线提示。HarmonyOS NEXT 通过ohos.net.connection模块提供了完整的网络管理能力。它不仅能查询当前的网络连接状态和属性还能通过事件监听机制实时感知网络变化。本文将构建一个网络诊断中心Demo从静态查询到动态监听全面展示 connection 模块的核心用法。读完本文你将掌握获取默认网络getDefaultNetSync()获取当前活跃网络句柄查询网络能力getNetCapabilitiesSync()了解带宽、计费模式、接入类型读取连接属性getConnectionPropertiesSync()获取 IP 地址、DNS、网卡名称DNS 域名解析getAddressesByName()将域名解析为 IP 地址实时网络监听NetConnection.on()注册 6 种网络事件的回调所有网络枚举getAllNetsSync()查看系统中所有可用网络环境与权限ohos.net.connection属于NetworkKit工具包自 API 8 开始提供。本文 Demo 基于 API 24 编写使用同步 API 版本xxxSync。需要申请的权限在module.json5中配置requestPermissions: [ { name: ohos.permission.GET_NETWORK_INFO }, // 获取网络信息 { name: ohos.permission.INTERNET } // 访问互联网 ]注意ohos.permission.GET_NETWORK_INFO是 normal 级别权限安装时自动授予ohos.permission.INTERNET同样是 normal 级别。这两个权限都不需要用户手动授权但必须在配置文件中声明。一、核心数据结构在深入 API 之前先了解几个关键的数据类型NetHandle — 网络句柄interfaceNetHandle{netId:number;// 网络ID0 表示无默认网络≥100 表示有效网络getAddressesByName(host:string):PromiseArrayNetAddress;// DNS解析}NetHandle是网络的身份证通过getDefaultNetSync()获取当前活跃网络的句柄后续的能力查询和属性读取都依赖它。NetCapabilities — 网络能力interfaceNetCapabilities{linkUpBandwidthKbps?:number;// 上行带宽 (Kbps)linkDownBandwidthKbps?:number;// 下行带宽 (Kbps)networkCap?:ArrayNetCap;// 网络能力标志集bearerTypes:ArrayNetBearType;// 承载类型WiFi/蜂窝/以太网等}NetBearType — 网络承载类型enumNetBearType{BEARER_CELLULAR0,// 蜂窝网络 (4G/5G)BEARER_WIFI1,// Wi-FiBEARER_BLUETOOTH2,// 蓝牙共享网络BEARER_ETHERNET3,// 以太网BEARER_VPN4// VPN}NetCap — 网络能力标志enumNetCap{NET_CAPABILITY_MMS0,// 可访问MMSC发送彩信NET_CAPABILITY_NOT_METERED11,// 不限流量非计费网络NET_CAPABILITY_INTERNET12,// 可访问互联网NET_CAPABILITY_NOT_VPN15,// 非VPN网络NET_CAPABILITY_VALIDATED16,// 网络已验证NET_CAPABILITY_PORTAL17,// Portal认证网络NET_CAPABILITY_NOT_RESTRICTED20,// 不受限制NET_CAPABILITY_NOT_CONGESTED21// 不拥塞}ConnectionProperties — 连接属性interfaceConnectionProperties{interfaceName:string;// 网卡名称 (如 wlan0)domains:string;// 域名搜索域linkAddresses:ArrayLinkAddress;// IP地址列表dnses:ArrayNetAddress;// DNS 服务器列表}interfaceLinkAddress{address:NetAddress;// IP地址prefixLength:number;// 前缀长度 (子网掩码)}interfaceNetAddress{address:string;// 地址字符串 (如 192.168.1.100 或 fe80::1)}二、静态查询快照式网络诊断2.1 获取默认网络一切网络查询的起点是获取当前默认网络的NetHandleimportconnectionfromohos.net.connection;// 先检查是否有可用网络if(connection.hasDefaultNetSync()){letnetHandleconnection.getDefaultNetSync();console.log(默认网络ID: netHandle.netId);// 输出如 100}hasDefaultNetSync()返回booleangetDefaultNetSync()返回NetHandle。两者都是同步调用立即返回不需要回调。2.2 查询网络能力拿到NetHandle后查询这个网络的传输能力letcaps:connection.NetCapabilitiesconnection.getNetCapabilitiesSync(netHandle);// 判断网络类型for(leti0;icaps.bearerTypes.length;i){lettypecaps.bearerTypes[i];if(typeconnection.NetBearType.BEARER_WIFI){console.log(当前连接: Wi-Fi);}elseif(typeconnection.NetBearType.BEARER_CELLULAR){console.log(当前连接: 蜂窝网络);}}// 判断计费模式letisMeteredtrue;if(caps.networkCap){for(leti0;icaps.networkCap.length;i){if(caps.networkCap[i]connection.NetCap.NET_CAPABILITY_NOT_METERED){isMeteredfalse;// 找到不限流量标志}}}if(isMetered){// 降级策略降低图片质量、暂停后台同步}2.3 读取连接属性获取 IP 地址、DNS 等网络配置letprops:connection.ConnectionPropertiesconnection.getConnectionPropertiesSync(netHandle);// 网卡名称console.log(网卡: props.interfaceName);// wlan0// IP 地址 — LinkAddress.address.address 直接返回字符串for(leti0;iprops.linkAddresses.length;i){letipprops.linkAddresses[i].address.address;console.log(IP: ip);// 192.168.1.100}// DNS 服务器 — NetAddress.address 已是字符串for(leti0;iprops.dnses.length;i){console.log(DNS: props.dnses[i].address);}2.4 枚举所有网络系统可能同时存在多个网络接口如 Wi-Fi 蜂窝数据同时开启。getAllNetsSync()返回所有网络句柄letallNetsconnection.getAllNetsSync();console.log(共找到 allNets.length 个网络);for(leti0;iallNets.length;i){letcapsconnection.getNetCapabilitiesSync(allNets[i]);// 逐个检查每个网络的能力}三、动态监听实时感知网络变化静态查询只能获取当前快照而NetConnection的监听机制可以实时感知网络事件。3.1 创建监听器letnetConnectionconnection.createNetConnection();createNetConnection()接受两个可选参数netSpecifier?: NetSpecifier— 指定要监听的网络类型如只监听 Wi-Fitimeout?: number— 超时时间毫秒超时后触发netUnavailable3.2 注册 6 种事件回调NetConnection提供了 6 种事件类型// 1. netAvailable — 网络变得可用netConnection.on(netAvailable,(netHandle:connection.NetHandle){console.log(网络可用, netIdnetHandle.netId);});// 2. netCapabilitiesChange — 网络能力发生变化如带宽变更netConnection.on(netCapabilitiesChange,(info:connection.NetCapabilityInfo){lettypesinfo.netCap.bearerTypes;console.log(网络能力变更: types.length 个承载类型);});// 3. netConnectionPropertiesChange — 连接属性变更如IP变更netConnection.on(netConnectionPropertiesChange,(info:connection.NetConnectionPropertyInfo){console.log(连接属性更新: info.connectionProperties.interfaceName);});// 4. netLost — 网络丢失netConnection.on(netLost,(netHandle:connection.NetHandle){console.log(网络丢失, netIdnetHandle.netId);});// 5. netUnavailable — 网络不可用超时未找到合适网络netConnection.on(netUnavailable,(){console.log(无可用网络);});// 6. netBlockStatusChange — 网络阻塞状态变化netConnection.on(netBlockStatusChange,(info:connection.NetBlockStatusInfo){console.log(阻塞状态: (info.blocked?已阻塞:已恢复));});3.3 激活与注销监听注册回调后必须调用register()激活监听不需要时调用unregister()释放资源// 激活监听netConnection.register((err){if(err){console.error(注册监听失败: JSON.stringify(err));}else{console.log(网络监听已启动);}});// 停止监听netConnection.unregister((err){if(err){console.error(注销监听失败: JSON.stringify(err));}else{console.log(网络监听已停止);}});四、DNS 域名解析connection模块还内置了 DNS 解析功能通过getAddressesByName()将域名解析为 IPconnection.getAddressesByName(www.example.com,(err,addresses){if(err){console.error(DNS解析失败: JSON.stringify(err));return;}for(leti0;iaddresses.length;i){console.log(解析结果: addresses[i].address);// addresses[i].address 是字符串如 93.184.216.34}});getAddressesByName()是异步方法使用回调返回结果。还有一个同步版本getAddressesByNameWithOptions()返回 Promise支持QueryOptions参数控制超时和 DNS 服务器。五、实战 Demo网络诊断中心页面结构Demo 页面NetDiagnosticPage.ets整合了上述全部功能提供可视化的网络诊断体验网络诊断中心 ├── 状态栏 — 实时操作反馈 ├── 网络概况 │ ├── 三列概览 — 网络类型 / 连接状态 / 可用网络数 │ ├── 刷新状态 按钮 — 重新拉取所有网络信息 │ └── 开启监听 按钮 — 启动/停止 NetConnection 事件监听 ├── 连接属性 — 网卡名称 / IP地址 / DNS / 域名 ├── 网络能力 — 承载类型 / 上下行带宽 / 计费模式 / 互联网访问 ├── DNS解析测试 — 域名输入 解析按钮 结果展示 ├── 网络事件日志 — 最近20条事件含时间戳和事件类型 └── 核心 API 参考 — 12 个关键 API4 个交互点刷新网络状态— 调用getDefaultNetSync()getNetCapabilitiesSync()getConnectionPropertiesSync()一次性获取并展示当前网络的全部诊断信息开启/停止网络监听— 创建NetConnection实例注册 6 种事件回调激活后每个网络事件都会在日志面板中实时显示DNS 解析测试— 输入域名调用getAddressesByName()进行解析展示所有解析到的 IP 地址查看事件日志— 监听开启期间所有netAvailable、netLost、netCapabilitiesChange等事件都记录在日志列表中可追溯网络变化历史核心代码位置完整代码在dev/entry/src/main/ets/pages/NetDiagnosticPage.ets约 390 行路由已注册为pages/NetDiagnosticPage。六、三种 API 调用模式的选择connection 模块大部分操作同时支持 Callback 异步、Promise 异步和同步 Sync 三种模式。以getNetCapabilities为例// 方式1Callbackconnection.getNetCapabilities(netHandle,(err,caps){if(err)return;lettypescaps.bearerTypes;});// 方式2Promiseconnection.getNetCapabilities(netHandle).then((caps){lettypescaps.bearerTypes;}).catch((err){console.error(err);});// 方式3SyncDemo 推荐letcapsconnection.getNetCapabilitiesSync(netHandle);lettypescaps.bearerTypes;选择建议场景推荐方式原因UI 初始化/手动刷新同步 Sync代码简洁直观数据量小无明显阻塞后台定时轮询Promise 异步不阻塞主线程大文件上传前的网络检查Callback 异步兼容旧版 API事件监听NetConnection.on()原生异步事件驱动七、常见问题1. hasDefaultNetSync() 返回 false这意味着设备当前没有活跃的数据网络检查 Wi-Fi 是否已连接检查蜂窝数据是否开启是否处于飞行模式模拟器默认网络连接通常正常2. 获取到的 linkAddresses 为空数组设备的网络接口可能尚未完成 DHCP 地址分配。在netAvailable事件触发后稍等片刻再查或使用netConnectionPropertiesChange回调来接收 IP 分配完成的通知。3. NetBearType 数组包含多个值这是正常的。例如设备可能同时通过 Wi-Fi (BEARER_WIFI1) 和 VPN (BEARER_VPN4) 传输数据。bearerTypes数组的第一元素通常是主要网络类型。4. register() 回调报错确保在module.json5中声明了ohos.permission.GET_NETWORK_INFO没有重复注册同一个NetConnection实例需先unregister再重新register页面销毁前调用unregister()释放资源八、与 zlib/cryptoFramework 的 API 设计对比connection 模块延续了 HarmonyOS 系统 API 的统一设计哲学模式zlibcryptoFrameworkconnection同步查询statSync()(file.fs)digestSync()getDefaultNetSync()异步操作compressFile()(Promise)digest()(Promise/Callback)getAddressesByName()(Callback)事件监听无无NetConnection.on()资源管理无无状态无无状态register()/unregister()connection 模块特有的事件监听模式使其区别于纯函数式的 zlib 和 cryptoFramework——它不仅是工具更是服务需要在生命周期内管理注册与注销。九、最佳实践网络感知的应用架构基于 connection 模块可以构建一个应用级的网络感知层// NetworkManager.ets — 全局单例exportclassNetworkManager{privatestaticinstance:NetworkManager;privateconn:connection.NetConnection;publicisOnline:booleanfalse;publicisMetered:booleanfalse;publicnetType:stringunknown;staticgetInstance():NetworkManager{/* 单例实现 */}startListen():void{this.connconnection.createNetConnection();this.conn.on(netAvailable,(h){this.isOnlinetrue;});this.conn.on(netLost,(){this.isOnlinefalse;});this.conn.on(netCapabilitiesChange,(info){this.isMeteredthis.checkMetered(info.netCap);this.netTypethis.getTypeName(info.netCap);});this.conn.register((err){if(!err)console.log(NetworkManager ready);});}destroy():void{this.conn?.unregister((){});}}各页面在使用网络前检查NetworkManager.getInstance().isOnline在计费网络下降低流量消耗实现优雅的全态网络体验。十、总结ohos.net.connection为 HarmonyOS NEXT 应用提供了完善的网络管理能力静态快照—getDefaultNetSync()getNetCapabilitiesSync()getConnectionPropertiesSync()三步获取完整网络视图网络类型判断— 5 种NetBearTypeWiFi/蜂窝/蓝牙/以太网/VPN计费感知— 12 种NetCap标志精准判断流量计费连接细节— IP 地址、DNS 服务器、网卡名称、域名域DNS 解析—getAddressesByName()内置域名解析实时监听—NetConnection 6 种事件回调 register/unregister 生命周期管理多网络枚举—getAllNetsSync()查看所有可用接口这套能力让你能够构建网络感知型的应用架构——在网络波动时优雅降级在恢复连接时自动重试在计费网络下珍惜用户的每一 KB 流量。