前言

网络可用性检测是移动应用的基础能力，在发起网络请求前先检测网络状态，可以避免无效请求并给用户友好提示。@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 安装依赖

ohpm install @pura/harmony-utils

2.2 检测网络可用性

import { NetworkUtil } from '@pura/harmony-utils';

Button('检测网络可用性')
  .width('100%')
  .onClick(() => {
    try {
      let available = NetworkUtil.isNetworkAvailable();
      this.result = `网络可用: ${available ? '是 ✅' : '否 ❌'}\n${available ? '可以发起网络请求' : '请检查网络设置'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 网络请求前检查

async fetchData() {
  if (!NetworkUtil.isNetworkAvailable()) {
    ToastUtil.show('网络不可用，请检查网络设置');
    return;
  }
  let data = await this.api.getData();
  this.dataList = data;
}

三、完整页面示例

import { NetworkUtil } from '@pura/harmony-utils';

@Entry
@Component
struct NetworkAvailDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('检测网络').width('100%').onClick(() => {
        try {
          let available = 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';

async function safeRequest(requestFn: Function) {
  if (!NetworkUtil.isNetworkAvailable()) {
    ToastUtil.showToast('网络不可用，请稍后重试');
    return null;
  }
  return await requestFn();
}

4.2 网络状态UI指示器

@State networkAvailable: boolean = true;

aboutToAppear() {
  this.networkAvailable = NetworkUtil.isNetworkAvailable();
}

五、注意事项

1. 权限配置：需要在module.json5中配置网络权限
2. 实时性：返回的是调用时刻的网络状态
3. 网络切换：网络状态可能随时变化，建议使用订阅方式
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 多次检测：关键操作前建议再次检测

六、常见问题

Q1: isNetworkAvailable()返回true但无法访问网络？

可能是连接了WiFi但无法访问互联网，建议使用 hasInternet() 进一步检测。

Q2: 如何实时监听网络状态变化？

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

Q3: 飞行模式下返回什么？

飞行模式下所有网络检测方法都返回false。

Q4: 网络权限需要配置哪个？

需要在module.json5中配置 ohos.permission.INTERNET 权限。

总结

NetworkUtil 的网络可用性检测方法为应用提供了快速的网络状态判断能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。在网络请求前检测网络状态，可以避免无效请求并提升用户体验。

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