前言

IP地址是网络通信的基础标识，在设备发现、本地服务、网络诊断等场景中经常需要获取设备IP地址。@pura/harmony-utils 的 NetworkUtil 封装了IP地址获取方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、NetworkUtil IP核心API

NetworkUtil 提供了以下IP地址获取方法：

方法	说明	返回类型	使用场景
getIpAddress()	获取IP地址	string	设备发现、本地服务
getIpv6Address()	获取IPv6地址	string	IPv6网络
getGateway()	获取网关地址	string	网络诊断
getNetMask()	获取子网掩码	string	网络计算
getDnsServers()	获取DNS服务器	string[]	DNS配置

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 信息全面：覆盖IPv4、IPv6、网关、掩码、DNS等

1.2 IP地址类型对比

类型	格式	示例	适用场景
IPv4	32位	192.168.1.100	局域网通信
IPv6	128位	fe80::1	新一代网络

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 获取IP地址

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

Button('获取IP地址')
  .width('100%')
  .onClick(() => {
    try {
      let ip = NetworkUtil.getIpAddress();
      this.result = `IP地址: ${ip}\n类型: IPv4`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 获取网络详情

Button('获取网络详情')
  .width('100%')
  .onClick(() => {
    try {
      let ip = NetworkUtil.getIpAddress();
      let gateway = NetworkUtil.getGateway();
      let mask = NetworkUtil.getNetMask();
      this.result = `IP: ${ip}\n网关: ${gateway}\n掩码: ${mask}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('获取IP地址').width('100%').onClick(() => {
        try {
          let ip = NetworkUtil.getIpAddress();
          this.result = `本机IP: ${ip}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 局域网设备发现

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

function getLocalNetworkPrefix(): string {
  let ip = NetworkUtil.getIpAddress();
  let parts = ip.split('.');
  return `${parts[0]}.${parts[1]}.${parts[2]}`;
}

4.2 网络诊断信息收集

function collectNetworkInfo(): Record<string, string> {
  return {
    ip: NetworkUtil.getIpAddress(),
    gateway: NetworkUtil.getGateway(),
    mask: NetworkUtil.getNetMask()
  };
}

五、注意事项

1. 网络依赖：需连接网络后才能获取IP地址
2. 多网卡：设备可能有多个网络接口，返回的可能是任一接口的IP
3. 隐私合规：IP地址属于用户隐私数据，使用时需注意合规
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 动态分配：IP地址可能由DHCP动态分配，会发生变化

六、常见问题

Q1: 未连接网络时获取IP返回什么？

可能返回空字符串或0.0.0.0，建议先检查网络连接状态。

Q2: 如何获取指定网络接口的IP？

当前API返回默认网络接口的IP，如需指定接口需使用系统底层API。

Q3: IPv6地址获取失败怎么办？

部分网络环境不支持IPv6，建议同时获取IPv4作为备选。

Q4: getDnsServers()返回多个DNS是什么意思？

设备可能配置了主DNS和备用DNS，返回数组包含所有DNS服务器地址。

总结

NetworkUtil 的IP地址获取方法为网络通信和诊断提供了基础数据支撑。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些信息实现设备发现、本地服务、网络诊断等功能。

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