鸿蒙三方库 | harmony-utils之NetworkUtil网络可用性检测详解
前言
网络可用性检测是移动应用的基础能力，在发起网络请求前先检测网络状态，可以避免无效请求并给用户友好提示。@pura/harmony-utils的NetworkUtil封装了网络状态检测方法，一行代码即可判断网络是否可用。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。
一、NetworkUtil可用性核心API
NetworkUtil提供了以下网络可用性检测方法：
| 方法 | 说明 | 返回类型 | 使用场景 |
|---|---|---|---|
isNetworkAvailable() | 判断网络是否可用 | boolean | 网络请求前检查 |
hasInternet() | 判断是否有互联网连接 | boolean | 互联网可达性 |
isNetworkConnected() | 判断网络是否连接 | boolean | 网络状态查询 |
1.1 核心特性
- 简洁易用：封装复杂API为一行调用，降低使用门槛
- 类型安全：完整的TypeScript类型定义，编译期即可发现错误
- 异常处理：内置异常捕获机制，避免运行时崩溃
- 快速响应：同步返回结果，无需异步等待
1.2 网络状态判断策略
| 场景 | 推荐方法 | 说明 |
|---|---|---|
| 网络请求前 | isNetworkAvailable() | 综合判断网络可用性 |
| 互联网检测 | hasInternet() | 判断是否能访问互联网 |
| UI状态展示 | isNetworkConnected() | 显示网络连接状态 |
二、完整使用步骤
2.1 安装依赖
ohpminstall@pura/harmony-utils2.2 检测网络可用性
import{NetworkUtil}from'@pura/harmony-utils';Button('检测网络可用性').width('100%').onClick(()=>{try{letavailable=NetworkUtil.isNetworkAvailable();this.result=`网络可用:${available?'是 ✅':'否 ❌'}\n${available?'可以发起网络请求':'请检查网络设置'}`;}catch(e){this.result='异常: '+e;}})2.3 网络请求前检查
asyncfetchData(){if(!NetworkUtil.isNetworkAvailable()){ToastUtil.show('网络不可用，请检查网络设置');return;}letdata=awaitthis.api.getData();this.dataList=data;}三、完整页面示例
import{NetworkUtil}from'@pura/harmony-utils';@Entry@Componentstruct NetworkAvailDemo{@Stateresult:string='';build(){Column({space:12}){Button('检测网络').width('100%').onClick(()=>{try{letavailable=NetworkUtil.isNetworkAvailable();this.result=`网络状态:${available?'可用 ✅':'不可用 ❌'}`;}catch(e){this.result='异常: '+e;}});Text(this.result).fontSize(14).fontColor('#333333')}.padding(16)}}四、进阶用法
4.1 网络状态全局拦截器
import{NetworkUtil,ToastUtil}from'@pura/harmony-utils';asyncfunctionsafeRequest(requestFn:Function){if(!NetworkUtil.isNetworkAvailable()){ToastUtil.showToast('网络不可用，请稍后重试');returnnull;}returnawaitrequestFn();}4.2 网络状态UI指示器
@StatenetworkAvailable:boolean=true;aboutToAppear(){this.networkAvailable=NetworkUtil.isNetworkAvailable();}五、注意事项
- 权限配置：需要在module.json5中配置网络权限
- 实时性：返回的是调用时刻的网络状态
- 网络切换：网络状态可能随时变化，建议使用订阅方式
- 初始化依赖：使用前需确保
AppUtil.init()已调用 - 多次检测：关键操作前建议再次检测
六、常见问题
Q1: isNetworkAvailable()返回true但无法访问网络？
可能是连接了WiFi但无法访问互联网，建议使用hasInternet()进一步检测。
Q2: 如何实时监听网络状态变化？
使用NetworkUtil.onNetworkChange()订阅网络变化事件。
Q3: 飞行模式下返回什么？
飞行模式下所有网络检测方法都返回false。
Q4: 网络权限需要配置哪个？
需要在module.json5中配置ohos.permission.INTERNET权限。
总结
NetworkUtil的网络可用性检测方法为应用提供了快速的网络状态判断能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。在网络请求前检测网络状态，可以避免无效请求并提升用户体验。
本文基于
@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。