前言

实时感知网络状态变化对应用体验至关重要，如网络断开时暂停下载、网络恢复时自动重连。@pura/harmony-utils 的 NetworkUtil 封装了网络状态订阅方法，支持实时监听网络变化。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、NetworkUtil订阅核心API

NetworkUtil 提供了以下网络状态订阅方法：

方法	说明	参数	使用场景
onNetworkChange(callback)	订阅网络变化	() => void	实时网络感知
offNetworkChange(callback)	取消网络变化订阅	() => void	释放资源

1.1 核心特性

• 实时感知：网络变化时立即触发回调
• 回调机制：基于回调函数的事件驱动模式
• 生命周期安全：支持注册和取消，避免内存泄漏
• 主线程执行：回调在主线程执行，可直接更新UI

1.2 网络变化回调适用场景

场景	网络恢复	网络断开
下载管理	自动恢复下载	暂停下载
数据同步	自动同步	缓存待同步数据
实时通信	重连服务器	显示离线状态
视频播放	恢复播放	缓冲提示

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 订阅网络变化

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

private networkCallback = () => {
  let available = NetworkUtil.isNetworkAvailable();
  this.result = `网络变化: ${available ? '可用 ✅' : '不可用 ❌'}`;
};

aboutToAppear() {
  NetworkUtil.onNetworkChange(this.networkCallback);
}

aboutToDisappear() {
  NetworkUtil.offNetworkChange(this.networkCallback);
}

2.3 网络变化时自动处理

NetworkUtil.onNetworkChange(() => {
  if (NetworkUtil.isNetworkAvailable()) {
    this.resumePendingRequests();
  } else {
    this.pauseAllRequests();
  }
});

三、完整页面示例

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

@Entry
@Component
struct NetworkSubDemo {
  @State result: string = '等待网络变化...';
  private callback = () => {
    let available = NetworkUtil.isNetworkAvailable();
    this.result = `网络: ${available ? '可用' : '不可用'}`;
  };

  aboutToAppear() {
    NetworkUtil.onNetworkChange(this.callback);
  }
  aboutToDisappear() {
    NetworkUtil.offNetworkChange(this.callback);
  }

  build() {
    Column({ space: 12 }) {
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 网络状态管理器

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

class NetworkStateManager {
  private listeners: Array<(available: boolean) => void> = [];
  private callback = () => {
    let available = NetworkUtil.isNetworkAvailable();
    this.listeners.forEach(cb => cb(available));
  };

  init() {
    NetworkUtil.onNetworkChange(this.callback);
  }

  addListener(listener: (available: boolean) => void) {
    this.listeners.push(listener);
  }

  destroy() {
    NetworkUtil.offNetworkChange(this.callback);
    this.listeners = [];
  }
}

4.2 离线队列

private pendingRequests: Function[] = [];

NetworkUtil.onNetworkChange(() => {
  if (NetworkUtil.isNetworkAvailable()) {
    while (this.pendingRequests.length > 0) {
      let request = this.pendingRequests.shift();
      request?.();
    }
  }
});

五、注意事项

1. 回调引用：注册和取消订阅需使用同一回调引用
2. 生命周期：页面销毁时务必取消订阅
3. 性能：回调中避免耗时操作
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 多次注册：避免重复注册同一回调

六、常见问题

Q1: 回调没有触发怎么办？

检查 AppUtil.init() 是否已调用，以及是否配置了网络权限。

Q2: 可以注册多个回调吗？

可以注册多个不同的回调函数，每个回调都会在网络变化时被调用。

Q3: 回调中如何获取网络类型？

在回调中调用 NetworkUtil.isWifiConnected() 等方法获取最新网络类型。

Q4: 取消订阅后还会收到回调吗？

不会，取消订阅后不再触发回调，但之前已入队的回调可能仍会执行。

总结

NetworkUtil 的网络状态订阅方法为实时感知网络变化提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用网络订阅，可以实现自动重连、离线缓存等智能功能。

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