前言

在多网络环境下（如同时连接WiFi和蜂窝），了解默认网络和绑定网络的概念对网络管理很重要。@pura/harmony-utils 的 NetworkUtil 封装了默认网络查询方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、NetworkUtil默认网络核心API

NetworkUtil 提供了以下默认网络查询方法：

方法	说明	返回类型	使用场景
getDefaultNetwork()	获取默认网络	object	网络管理
isDefaultNetworkMetered()	默认网络是否计量	boolean	流量判断
hasDefaultNetwork()	是否有默认网络	boolean	网络可用性

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 多网络支持：支持多网络环境下的默认网络判断

1.2 默认网络选择策略

场景	默认网络	说明
WiFi+蜂窝	WiFi	WiFi优先
仅蜂窝	蜂窝	无WiFi时使用蜂窝
仅以太网	以太网	有线网络优先
无网络	无	网络不可用

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 查询默认网络

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

Button('查询默认网络')
  .width('100%')
  .onClick(() => {
    try {
      let hasDefault = NetworkUtil.hasDefaultNetwork();
      let isMetered = NetworkUtil.isDefaultNetworkMetered();
      this.result = `有默认网络: ${hasDefault ? '是 ✅' : '否 ❌'}\n是否计量: ${isMetered ? '是' : '否'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 网络选择策略

getBestNetwork(): string {
  if (NetworkUtil.isWifiConnected()) {
    return 'WiFi';
  } else if (NetworkUtil.isCellularConnected()) {
    return '蜂窝';
  }
  return '无网络';
}

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('查询默认网络').width('100%').onClick(() => {
        try {
          let hasDefault = NetworkUtil.hasDefaultNetwork();
          let isMetered = NetworkUtil.isDefaultNetworkMetered();
          this.result = `默认网络: ${hasDefault ? '可用' : '不可用'}\n计量: ${isMetered ? '是' : '否'}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 多网络环境管理

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

function getNetworkReport(): Record<string, boolean> {
  return {
    hasDefault: NetworkUtil.hasDefaultNetwork(),
    isMetered: NetworkUtil.isDefaultNetworkMetered(),
    isWifi: NetworkUtil.isWifiConnected(),
    isCellular: NetworkUtil.isCellularConnected()
  };
}

4.2 智能网络选择

function selectNetworkForTask(taskType: string): string {
  if (taskType === 'download' && NetworkUtil.isDefaultNetworkMetered()) {
    return '建议连接WiFi后下载';
  }
  return '当前网络可用';
}

五、注意事项

1. 默认网络：系统自动选择的最优网络作为默认网络
2. 网络优先级：WiFi > 以太网 > 蜂窝
3. 动态切换：默认网络可能随网络状态变化自动切换
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 权限要求：需要网络相关权限

六、常见问题

Q1: hasDefaultNetwork()和isNetworkAvailable()有什么区别？

hasDefaultNetwork() 判断是否有系统默认网络，isNetworkAvailable() 判断网络是否可用，两者通常一致但不完全相同。

Q2: 默认网络可以手动指定吗？

普通应用无法指定默认网络，由系统根据网络优先级自动选择。

Q3: 同时连接WiFi和蜂窝时使用哪个？

系统默认使用WiFi，蜂窝作为备用。WiFi断开时自动切换到蜂窝。

Q4: getDefaultNetwork()返回的对象包含什么？

返回默认网络的标识对象，具体内容取决于系统实现，可用于网络绑定等操作。

总结

NetworkUtil 的默认网络查询方法为多网络环境管理提供了数据支撑。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据默认网络状态智能调整网络策略。

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