鸿蒙三方库 | harmony-utils之NetworkUtil WiFi与蜂窝网络判断详解
前言
了解当前网络类型（WiFi或蜂窝）对应用行为优化很重要，如大文件下载在WiFi下自动进行，蜂窝网络下提示用户。@pura/harmony-utils的NetworkUtil封装了网络类型判断方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。
一、NetworkUtil类型核心API
NetworkUtil提供了以下网络类型判断方法：
| 方法 | 说明 | 返回类型 | 使用场景 |
|---|---|---|---|
isWifiConnected() | 是否WiFi连接 | boolean | WiFi场景判断 |
isCellularConnected() | 是否蜂窝连接 | boolean | 流量场景判断 |
isEthernetConnected() | 是否以太网连接 | boolean | 有线网络判断 |
getConnectionType() | 获取连接类型 | string | 网络类型展示 |
1.1 核心特性
- 简洁易用：封装复杂API为一行调用，降低使用门槛
- 类型安全：完整的TypeScript类型定义，编译期即可发现错误
- 异常处理：内置异常捕获机制，避免运行时崩溃
- 快速响应：同步返回结果，无需异步等待
1.2 网络类型与应用策略
| 网络类型 | 下载策略 | 视频质量 | 数据同步 |
|---|---|---|---|
| WiFi | 自动下载 | 高清 | 自动同步 |
| 蜂窝 | 提示用户 | 标清 | 手动同步 |
| 以太网 | 自动下载 | 高清 | 自动同步 |
二、完整使用步骤
2.1 安装依赖
ohpminstall@pura/harmony-utils2.2 判断WiFi连接
import{NetworkUtil}from'@pura/harmony-utils';Button('判断WiFi连接').width('100%').onClick(()=>{try{letisWifi=NetworkUtil.isWifiConnected();this.result=`WiFi:${isWifi?'已连接 📶':'未连接'}`;}catch(e){this.result='异常: '+e;}})2.3 判断蜂窝连接
Button('判断蜂窝连接').width('100%').onClick(()=>{try{letisCellular=NetworkUtil.isCellularConnected();this.result=`蜂窝:${isCellular?'已连接 📡':'未连接'}`;}catch(e){this.result='异常: '+e;}})三、完整页面示例
import{NetworkUtil}from'@pura/harmony-utils';@Entry@Componentstruct NetworkTypeDemo{@Stateresult:string='';build(){Column({space:12}){Button('获取网络类型').width('100%').onClick(()=>{try{letisWifi=NetworkUtil.isWifiConnected();letisCellular=NetworkUtil.isCellularConnected();this.result=`WiFi:${isWifi?'是':'否'}\n蜂窝:${isCellular?'是':'否'}`;}catch(e){this.result='异常: '+e;}});Text(this.result).fontSize(14).fontColor('#333333')}.padding(16)}}四、进阶用法
4.1 智能下载策略
import{NetworkUtil,ToastUtil}from'@pura/harmony-utils';asyncfunctionsmartDownload(url:string){if(NetworkUtil.isWifiConnected()){awaitdownloadFile(url);}elseif(NetworkUtil.isCellularConnected()){ToastUtil.showToast('当前使用蜂窝网络，下载将消耗流量');}else{ToastUtil.showToast('网络不可用');}}4.2 视频质量自适应
functiongetVideoQuality():string{returnNetworkUtil.isWifiConnected()?'1080p':'720p';}五、注意事项
- 下载策略：WiFi下自动下载，蜂窝下提示用户
- 视频播放：WiFi下自动高清，蜂窝下默认标清
- 数据同步：WiFi下自动同步，蜂窝下手动同步
- 初始化依赖：使用前需确保
AppUtil.init()已调用 - 网络切换：网络类型可能随时变化
六、常见问题
Q1: WiFi和蜂窝同时连接时返回什么？
通常WiFi优先，isWifiConnected()返回true。
Q2: 如何监听网络类型变化？
使用NetworkUtil.onNetworkChange()订阅网络变化事件。
Q3: getConnectionType()返回什么格式？
返回网络类型字符串，如 “WiFi”、“Cellular”、“Ethernet” 等。
Q4: 蜂窝网络下如何判断是4G还是5G？
使用NetworkUtil的蜂窝详情方法或5G检测方法。
总结
NetworkUtil的网络类型判断方法让应用能够根据网络类型做出智能决策。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理利用网络类型信息，既节省用户流量又提升使用体验。
本文基于
@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。