前言

了解网络的详细类型和能力，可以帮助应用做出更精细的网络策略。@pura/harmony-utils 的 NetworkUtil 封装了网络能力查询方法，让开发者获取网络类型、传输能力等详细信息。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、NetworkUtil能力核心API

NetworkUtil 提供了以下网络能力查询方法：

方法	说明	返回类型	使用场景
getNetworkType()	获取网络类型	string	网络类型展示
getNetworkCapabilities()	获取网络能力	string[]	能力判断
isNetworkCapabilityValid()	判断网络能力是否有效	boolean	有效性检查

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 能力全面：覆盖网络类型和传输能力

1.2 网络能力类型

能力	说明	影响
INTERNET	可访问互联网	网络请求
MMS	支持彩信	消息功能
NOT_METERED	非按流量计费	大文件下载
VALIDATED	网络已验证	互联网可达

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 获取网络类型

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

Button('获取网络类型')
  .width('100%')
  .onClick(() => {
    try {
      let type = NetworkUtil.getNetworkType();
      this.result = `网络类型: ${type}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 查询网络能力

Button('查询网络能力')
  .width('100%')
  .onClick(() => {
    try {
      let capabilities = NetworkUtil.getNetworkCapabilities();
      this.result = `网络能力: ${JSON.stringify(capabilities)}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('查询网络能力').width('100%').onClick(() => {
        try {
          let type = NetworkUtil.getNetworkType();
          let valid = NetworkUtil.isNetworkCapabilityValid();
          this.result = `类型: ${type}\n能力有效: ${valid}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 按流量计费检测

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

function checkMeteredBeforeDownload() {
  let capabilities = NetworkUtil.getNetworkCapabilities();
  let isMetered = !capabilities.includes('NOT_METERED');
  if (isMetered) {
    ToastUtil.showToast('当前按流量计费，下载将消耗流量');
  }
}

4.2 网络能力综合判断

function canPerformHeavyTask(): boolean {
  if (!NetworkUtil.isNetworkAvailable()) return false;
  let capabilities = NetworkUtil.getNetworkCapabilities();
  return capabilities.includes('NOT_METERED') && capabilities.includes('VALIDATED');
}

五、注意事项

1. 能力类型：包括INTERNET、MMS、NOT_METERED等
2. 动态变化：网络能力可能随网络切换变化
3. 权限要求：需要网络相关权限
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 能力验证：建议结合 isNetworkCapabilityValid() 判断

六、常见问题

Q1: getNetworkCapabilities()返回空数组？

可能是网络未连接或权限不足，建议先检查网络状态和权限配置。

Q2: NOT_METERED能力有什么用？

表示当前网络不按流量计费（如WiFi），可以放心进行大文件下载等操作。

Q3: isNetworkCapabilityValid()和isNetworkAvailable()有什么区别？

isNetworkCapabilityValid() 判断网络能力对象是否有效，isNetworkAvailable() 判断网络是否可用。

Q4: 网络类型和能力有什么关系？

网络类型是WiFi/蜂窝等分类，能力是网络支持的功能特性，两者相互独立。

总结

NetworkUtil 的网络能力查询方法让开发者能够深入了解当前网络的详细能力，从而做出更精准的网络策略决策。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。

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