更新记录

1.0.1（2026-05-24）

调整鸿蒙发现逻辑。

1.0.0（2026-05-24）

初始化发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

概述

XF-pingUTS封装了Android、iOS和Harmony系统的网络连通性探测能力，也提供获取本机当前网络IP、扫描当前网络 IPv4 网段的能力，支持当前网络 IPv4 网段扫描。

Android使用系统ping命令执行ICMP探测；iOS使用本地ICMP socket实现；Harmony使用@ohos-rs/ping执行ICMP探测，并在扫描时使用TCP常见端口探测作为补充。

Android实现参考了“通过系统ping命令判断目标IP是否可达”、枚举本机网卡地址、通过UDP触发ARP表更新后读取ARP缓存的常见实现思路。getCurrentIp只枚举本机当前网络地址，不请求公网IP服务。scanCurrentNetworkIps只扫描当前手机所在的IPv4局域网网段，不请求公网IP服务，扫描结果只返回IPv4地址。

使用前提

Android

• 需要网络访问权限：android.permission.INTERNET。
• 插件已在utssdk/app-android/config.json声明该权限，使用方仍需确认最终AndroidManifest中包含该权限。
• Android实现依赖系统ping命令，不需要root权限。
• scanCurrentNetworkIps 使用 UDP 触发 ARP 表更新，并读取/proc/net/arp解析当前网段内可见设备；随后对未发现的IPv4补充TCP常见端口探测；不会执行arp -a。

iOS

• 需要允许应用访问网络。
• 插件使用本地ICMP socket，不需要额外三方库。
• 如果目标网络屏蔽ICMP，结果会显示丢包或失败。
• scanCurrentNetworkIps 使用本地ICMP socket扫描当前IPv4网段，并对ICMP未回包的IPv4补充TCP常见端口探测；iOS不会返回局域网设备MAC地址。

Harmony

• 需要网络访问权限：ohos.permission.INTERNET。
• 获取当前网络IP还需要网络状态权限：ohos.permission.GET_NETWORK_INFO。
• 使用方需要在Harmony工程module.json5中声明上述权限；插件已在utssdk/app-harmony/config.json中声明。
• Harmony依赖@ohos-rs/ping，插件已在utssdk/app-harmony/config.json中配置@ohos-rs/ping: 0.0.2。
• scanCurrentNetworkIps 在Harmony上优先使用ICMP扫描当前IPv4网段，再使用TCP常见端口探测作为补充；普通Harmony应用可能无法读取ARP缓存表，因此不会返回设备MAC地址。TCP连接成功或连接被拒绝也会视为该IP在线；如果目标设备同时屏蔽ICMP和TCP探测，仍可能无法被发现。

插件接口

ping

对传入的域名或IP进行网络探测，并通过回调返回探测结果。

uni-app项目中（nvue）调用示例：

import { ping } from "@/uni_modules/XF-pingUTS"

ping({
  host: "www.baidu.com",
  count: 4,
  timeout: 3000,
  packetSize: 56,
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { ping } from "@/uni_modules/XF-pingUTS";
import { PingOptions } from "@/uni_modules/XF-pingUTS/utssdk/interface.uts";

let options = {
  host: "www.baidu.com",
  count: 4,
  timeout: 3000,
  packetSize: 56,
  complete: (res : any) => {
    console.log(res)
  }
} as PingOptions;
ping(options);

参数说明

返回结果

错误码

可用性

iOS、Android、Harmony系统

可提供的1.0.0及更高版本

getCurrentIp

获取当前设备本机网络IP，返回IPv4、IPv6、地址列表和当前命中的网卡名。该接口只读取本机网络接口，不请求公网IP服务。

uni-app项目中（nvue）调用示例：

import { getCurrentIp } from "@/uni_modules/XF-pingUTS"

getCurrentIp({
  preferIPv6: false,
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { getCurrentIp } from "@/uni_modules/XF-pingUTS";
import { GetCurrentIpOptions } from "@/uni_modules/XF-pingUTS/utssdk/interface.uts";

let options = {
  preferIPv6: false,
  complete: (res : any) => {
    console.log(res)
  }
} as GetCurrentIpOptions;
getCurrentIp(options);

参数说明

返回结果

错误码

可用性

iOS、Android、Harmony系统

可提供的1.0.0及更高版本

scanCurrentNetworkIps

扫描当前手机网络所在的IPv4网段，返回可探测到的IP设备列表。扫描结果只返回IPv4地址。Android 使用 UDP 触发 ARP 表更新并读取/proc/net/arp后补充TCP探测，iOS 使用 ICMP 探测后补充TCP探测，Harmony 使用@ohos-rs/ping执行ICMP探测后补充TCP探测。TCP连接成功或连接被拒绝也会视为该IP在线。

uni-app项目中（nvue）调用示例：

import { scanCurrentNetworkIps } from "@/uni_modules/XF-pingUTS"

scanCurrentNetworkIps({
  timeout: 350,
  startHost: 1,
  endHost: 254,
  complete: (res) => {
    console.log(res)
  }
});

uni-app x项目（uvue）中调用示例：

import { scanCurrentNetworkIps } from "@/uni_modules/XF-pingUTS";
import { ScanCurrentNetworkIpsOptions } from "@/uni_modules/XF-pingUTS/utssdk/interface.uts";

let options = {
  timeout: 350,
  startHost: 1,
  endHost: 254,
  complete: (res : any) => {
    console.log(res)
  }
} as ScanCurrentNetworkIpsOptions;
scanCurrentNetworkIps(options);

参数说明

返回结果

ScannedIpDevice

错误码

可用性

iOS、Android、Harmony系统

可提供的1.0.0及更高版本