鸿蒙App 网络状态监听（Wi-Fi/4G/5G切换提示）技术详解

一、引言​

二、技术背景​

1. 鸿蒙网络管理核心架构

2. 关键技术特性

• 多网络协同：支持同时监听Wi-Fi、蜂窝网络（4G/5G）、以太网等多网络连接状态。
• 精细化区分：蜂窝网络中可进一步识别2G/3G/4G/5G（需API 10+），支持信号强度（RSRP）获取。
• 事件驱动：通过回调函数实时响应网络状态变化（如从无网到有网、Wi-Fi切换到5G）。
• 低功耗设计：采用事件订阅机制，仅在状态变化时唤醒应用，避免持续轮询耗电。

三、应用场景​

四、核心原理与流程图​

1. 原理解释

• 网络状态存储：系统通过网络管理服务（Network Management Service）维护当前活跃网络连接的状态（类型、能力、信号强度）。
• 事件订阅机制：应用通过@ohos.net.connection模块的NetConnection对象注册事件监听器（如netAvailable、netLost、netCapabilitiesChange），当网络状态变化时，系统主动回调应用注册的回调函数。
• 网络类型判断：通过NetCapability接口的getNetworkType()方法获取基础类型（Wi-Fi/Cellular），蜂窝网络进一步通过getSignalStrength()或运营商信息区分4G/5G（需API 10+）。

2. 原理流程图

graph TD
    A[系统网络状态变化] --> B[网络管理服务]
    B --> C[通知订阅应用]
    C --> D[应用NetConnection回调]
    D --> E[解析网络类型/能力]
    E --> F{是否需提示用户?}
    F -->|是| G[显示切换提示]
    F -->|否| H[内部逻辑调整]
    G --> I[用户交互响应]
    H --> J[优化数据传输策略]

五、核心特性​

1. 全网络类型覆盖：支持Wi-Fi、蜂窝网络（2G/3G/4G/5G）、以太网、无网络等状态监听。
2. 动态能力获取：实时获取网络带宽、延迟、信号强度（RSRP/RSRQ）等指标。
3. 多事件监听：支持网络连接/断开、能力变化、信号强度变化等10+事件类型。
4. 用户友好提示：内置Snackbar/AlertDialog组件，支持自定义提示文案与样式。
5. 低功耗优化：事件驱动机制避免无效轮询，CPU占用率＜1%（典型场景）。

六、环境准备​

1. 开发环境

• DevEco Studio：3.1+（最新版）
• HarmonyOS SDK：API 9+（基础监听）、API 10+（5G精细区分）
• 设备：真机（华为手机/平板，支持4G/5G）、模拟器（API 9+，可模拟网络切换）

2. 项目配置

import connection from '@ohos.net.connection';  // 网络连接模块
import promptAction from '@ohos.promptAction';    // 提示框模块
import { BusinessError } from '@ohos.base';      // 错误处理

七、详细代码实现​

场景1：基础网络状态监听组件（NetworkMonitor）​

1. 组件代码（NetworkMonitor.ets）

import connection from '@ohos.net.connection';
import { BusinessError } from '@ohos.base';

// 网络类型映射（中文描述）
const NetworkTypeMap = new Map<connection.NetworkType, string>([
  [connection.NetworkType.NETWORK_TYPE_WIFI, 'Wi-Fi'],
  [connection.NetworkType.NETWORK_TYPE_CELLULAR, '蜂窝网络'],
  [connection.NetworkType.NETWORK_TYPE_ETHERNET, '以太网'],
  [connection.NetworkType.NETWORK_TYPE_NONE, '无网络']
]);

// 蜂窝网络子类型（API 10+）
const CellularTypeMap = new Map<number, string>([
  [connection.CellularType.CELLULAR_TYPE_2G, '2G'],
  [connection.CellularType.CELLULAR_TYPE_3G, '3G'],
  [connection.CellularType.CELLULAR_TYPE_4G, '4G'],
  [connection.CellularType.CELLULAR_TYPE_5G, '5G']
]);

@Component
export struct NetworkMonitor {
  @State currentNetworkType: connection.NetworkType = connection.NetworkType.NETWORK_TYPE_NONE;
  @State currentNetworkDesc: string = '未知网络';
  @State signalStrength: number = 0; // 信号强度（0-4格，4格最强）
  private netConnection: connection.NetConnection | null = null;
  private callbacks: Array<(type: connection.NetworkType, desc: string, strength: number) => void> = [];

  aboutToAppear() {
    this.initNetConnection();
  }

  aboutToDisappear() {
    this.releaseNetConnection();
  }

  // 初始化网络连接监听
  private async initNetConnection() {
    try {
      this.netConnection = connection.createNetConnection();
      // 注册网络可用事件
      this.netConnection.on('netAvailable', (data) => {
        this.handleNetworkChange(data);
      });
      // 注册网络能力变化事件（含类型/信号变化）
      this.netConnection.on('netCapabilitiesChange', (data) => {
        this.handleNetworkChange(data);
      });
      // 注册网络丢失事件
      this.netConnection.on('netLost', (data) => {
        this.currentNetworkType = connection.NetworkType.NETWORK_TYPE_NONE;
        this.currentNetworkDesc = '无网络';
        this.signalStrength = 0;
        this.notifyCallbacks();
      });
      // 主动获取当前网络状态
      await this.getCurrentNetworkStatus();
    } catch (err) {
      console.error('初始化网络监听失败:', (err as BusinessError).message);
    }
  }

  // 处理网络状态变化
  private async handleNetworkChange(data: connection.NetHandle) {
    const netCaps = this.netConnection?.getNetCapabilities(data);
    if (!netCaps) return;

    // 获取网络类型
    const networkType = netCaps.getNetworkType();
    this.currentNetworkType = networkType;

    // 解析网络描述（含4G/5G区分）
    let desc = NetworkTypeMap.get(networkType) || '未知网络';
    if (networkType === connection.NetworkType.NETWORK_TYPE_CELLULAR) {
      const cellularType = this.getCellularType(netCaps); // API 10+获取蜂窝子类型
      desc += `(${CellularTypeMap.get(cellularType) || '未知'})`;
    }
    this.currentNetworkDesc = desc;

    // 获取信号强度（0-4格）
    this.signalStrength = await this.getSignalStrength(data);
    this.notifyCallbacks(); // 通知外部回调
  }

  // 获取当前网络状态（初始化时调用）
  private async getCurrentNetworkStatus() {
    try {
      const netHandles = connection.getActiveNetworks();
      if (netHandles.length === 0) {
        this.currentNetworkType = connection.NetworkType.NETWORK_TYPE_NONE;
        this.currentNetworkDesc = '无网络';
        return;
      }
      // 取第一个活跃网络连接
      const activeNet = netHandles[0];
      await this.handleNetworkChange(activeNet);
    } catch (err) {
      console.error('获取当前网络状态失败:', (err as BusinessError).message);
    }
  }

  // 获取蜂窝网络子类型（API 10+）
  private getCellularType(netCaps: connection.NetCapabilities): number {
    if (netCaps.hasCapability(connection.NetCapability.NET_CAPABILITY_5G)) {
      return connection.CellularType.CELLULAR_TYPE_5G;
    } else if (netCaps.hasCapability(connection.NetCapability.NET_CAPABILITY_4G)) {
      return connection.CellularType.CELLULAR_TYPE_4G;
    } else if (netCaps.hasCapability(connection.NetCapability.NET_CAPABILITY_3G)) {
      return connection.CellularType.CELLULAR_TYPE_3G;
    } else {
      return connection.CellularType.CELLULAR_TYPE_2G;
    }
  }

  // 获取信号强度（0-4格）
  private async getSignalStrength(netHandle: connection.NetHandle): Promise<number> {
    try {
      const signalInfo = await connection.getSignalInformation(netHandle);
      if (signalInfo.length === 0) return 0;
      // 取第一个信号的RSRP值（参考信号接收功率，单位dBm）
      const rsrp = signalInfo[0].rsrp;
      // 映射到0-4格（5G/4G信号范围：-140dBm ~ -44dBm）
      if (rsrp >= -85) return 4; // 强信号
      if (rsrp >= -95) return 3; // 中等
      if (rsrp >= -105) return 2; // 较弱
      if (rsrp >= -115) return 1; // 弱
      return 0; // 无信号
    } catch (err) {
      console.error('获取信号强度失败:', (err as BusinessError).message);
      return 0;
    }
  }

  // 注册状态变化回调
  registerCallback(callback: (type: connection.NetworkType, desc: string, strength: number) => void) {
    this.callbacks.push(callback);
  }

  // 通知所有回调
  private notifyCallbacks() {
    this.callbacks.forEach(cb => cb(this.currentNetworkType, this.currentNetworkDesc, this.signalStrength));
  }

  // 释放资源
  private releaseNetConnection() {
    if (this.netConnection) {
      this.netConnection.off('netAvailable');
      this.netConnection.off('netCapabilitiesChange');
      this.netConnection.off('netLost');
      this.netConnection = null;
    }
  }

  build() {
    // 可视化网络状态（可选，用于调试）
    Column() {
      Text(`当前网络: ${this.currentNetworkDesc}`)
        .fontSize(16)
      Row() {
        ForEach([1, 2, 3, 4], (item: number) => {
          Circle()
            .width(20)
            .height(20)
            .fill(item <= this.signalStrength ? '#00FF00' : '#CCCCCC')
        })
      }
    }
  }
}

场景2：网络切换提示逻辑（NetworkSwitchNotifier）​

1. 提示工具类代码（NetworkSwitchNotifier.ets）

import promptAction from '@ohos.promptAction';
import { NetworkMonitor } from './NetworkMonitor';
import connection from '@ohos.net.connection';

export class NetworkSwitchNotifier {
  private lastNetworkType: connection.NetworkType = connection.NetworkType.NETWORK_TYPE_NONE;
  private monitor: NetworkMonitor;

  constructor(monitor: NetworkMonitor) {
    this.monitor = monitor;
    // 注册网络状态变化回调
    this.monitor.registerCallback(this.handleNetworkChange.bind(this));
  }

  // 处理网络变化并提示
  private handleNetworkChange(type: connection.NetworkType, desc: string, strength: number) {
    if (this.lastNetworkType === connection.NetworkType.NETWORK_TYPE_NONE) {
      // 初始状态，不提示
      this.lastNetworkType = type;
      return;
    }
    if (this.lastNetworkType !== type) {
      // 网络类型变化，弹出提示
      promptAction.showToast({
        message: `网络已切换: ${desc}`,
        duration: 3000
      });
      this.lastNetworkType = type;
    }
  }
}

场景3：综合应用示例（NetworkStatusPage）​

1. 页面代码（NetworkStatusPage.ets）

import { NetworkMonitor } from '../components/NetworkMonitor';
import { NetworkSwitchNotifier } from '../utils/NetworkSwitchNotifier';
import connection from '@ohos.net.connection';

@Entry
@Component
struct NetworkStatusPage {
  private networkMonitor: NetworkMonitor = new NetworkMonitor();
  private notifier: NetworkSwitchNotifier | null = null;

  aboutToAppear() {
    // 初始化切换提示器
    this.notifier = new NetworkSwitchNotifier(this.networkMonitor);
  }

  aboutToDisappear() {
    // 释放资源（实际项目中建议在全局管理器中统一释放）
    this.networkMonitor.aboutToDisappear();
  }

  build() {
    Column({ space: 20 }) {
      // 标题
      Text('网络状态监听')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 20 });

      // 网络状态展示（嵌入NetworkMonitor组件）
      this.networkMonitor.build(); // 直接调用组件的build方法（或通过@Builder封装）

      // 手动刷新按钮
      Button('刷新网络状态', { type: ButtonType.Normal })
        .width(200)
        .height(40)
        .onClick(async () => {
          await this.networkMonitor.getCurrentNetworkStatus();
        });
    }
    .width('100%')
    .height('100%')
    .alignItems(HorizontalAlign.Center)
  }
}

八、运行结果与测试步骤​

1. 预期效果

• 实时显示：页面顶部显示当前网络类型（如“蜂窝网络(5G)”）、信号强度（4格绿色圆表示强信号）。
• 切换提示：从Wi-Fi切换到5G时，底部弹出Toast提示“网络已切换: 蜂窝网络(5G)”。
• 手动刷新：点击“刷新网络状态”按钮，重新获取当前网络信息。

2. 测试步骤

1. 环境配置：
   • 安装DevEco Studio 3.1+，创建“Empty Ability”项目（语言选择TS）。
   • 将上述代码文件放入entry/src/main/ets/components/（NetworkMonitor）、utils/（NetworkSwitchNotifier）、pages/（NetworkStatusPage）。
2. 真机测试：
   • 连接华为手机（HarmonyOS 4.0+，支持5G），开启USB调试。
   • 运行项目，观察初始网络状态显示。
   • 手动切换网络（关闭Wi-Fi→使用5G→切换为4G），验证提示是否正常弹出。
3. 模拟器测试：
   • 使用DevEco Studio模拟器，通过“设置→网络”模拟Wi-Fi/蜂窝网络切换，观察状态更新。

九、部署场景​

十、疑难解答​

十一、未来展望与技术趋势​

1. 趋势

• AI网络预测：基于历史切换数据预测用户常驻网络（如家中Wi-Fi、公司Wi-Fi），提前缓存内容。
• 多网络协同：支持“Wi-Fi+5G”双连接（API 11+），自动选择最优网络传输数据。
• 场景化适配：根据用户行为（如视频通话优先5G低延迟，文件下载优先Wi-Fi高带宽）动态调整策略。
• 隐私增强：允许用户手动关闭网络状态提示，或模糊化敏感网络信息（如具体基站位置）。

2. 挑战

• 跨设备一致性：不同厂商手机（华为/荣耀/小米）的5G信号标识可能存在差异。
• 弱网优化：极端弱网（如电梯内）下的状态判断准确性与功耗平衡。

十二、总结​

1. 核心API：通过@ohos.net.connection模块的NetConnection注册事件，监听netAvailable、netCapabilitiesChange等回调。
2. 状态解析：结合NetworkType和NetCapabilities区分Wi-Fi/4G/5G，通过信号强度（RSRP）量化网络质量。
3. 最佳实践：
   • 封装NetworkMonitor组件统一管理监听逻辑，避免重复代码。
   • 使用NetworkSwitchNotifier实现切换提示，添加防抖避免频繁打扰用户。
   • 针对不同设备（车机/智慧屏）优化提示文案与时机。

完整源码下载：

NetworkMonitor.ets

NetworkSwitchNotifier.ets

NetworkStatusPage.ets