鸿蒙三方库 | harmony-utils之NetworkUtil WiFi与蜂窝网络判断详解

前言

了解当前网络类型（WiFi或蜂窝）对应用行为优化很重要，如大文件下载在WiFi下自动进行，蜂窝网络下提示用户。@pura/harmony-utils的NetworkUtil封装了网络类型判断方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、NetworkUtil类型核心API

NetworkUtil提供了以下网络类型判断方法：

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 快速响应：同步返回结果，无需异步等待

1.2 网络类型与应用策略

二、完整使用步骤

2.1 安装依赖

ohpminstall@pura/harmony-utils

2.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';}

五、注意事项

1. 下载策略：WiFi下自动下载，蜂窝下提示用户
2. 视频播放：WiFi下自动高清，蜂窝下默认标清
3. 数据同步：WiFi下自动同步，蜂窝下手动同步
4. 初始化依赖：使用前需确保AppUtil.init()已调用
5. 网络切换：网络类型可能随时变化

六、常见问题

Q1: WiFi和蜂窝同时连接时返回什么？

通常WiFi优先，isWifiConnected()返回true。

Q2: 如何监听网络类型变化？

使用NetworkUtil.onNetworkChange()订阅网络变化事件。

Q3: getConnectionType()返回什么格式？

返回网络类型字符串，如 “WiFi”、“Cellular”、“Ethernet” 等。

Q4: 蜂窝网络下如何判断是4G还是5G？

使用NetworkUtil的蜂窝详情方法或5G检测方法。

总结

NetworkUtil的网络类型判断方法让应用能够根据网络类型做出智能决策。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理利用网络类型信息，既节省用户流量又提升使用体验。

本文基于@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。