鸿蒙cordova的获取网络信息插件
当前访问频次受限，请登录后继续访问
cordova-plugin-networkinterface
本项目基于 cordova-plugin-networkinterface@2.2.0 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。
简介
cordova-plugin-networkinterface 是一款专为 Cordova 混合移动应用打造的网络接口信息获取插件，支持跨平台获取设备网络适配器的详细信息，包括 IP 地址、MAC 地址、子网掩码、网关等关键网络参数，助力开发者实现网络诊断、设备绑定等场景化需求。
功能特性
-
网络信息获取：支持获取所有网络适配器的 IP 地址（IPv4/IPv6）、MAC 地址、子网掩码、网关、DNS 服务器等完整参数
-
多适配器识别：自动识别 Wi-Fi、以太网、移动数据（4G/5G）、蓝牙共享等不同类型的网络适配器
-
活跃网络检测：快速定位当前设备正在使用的活跃网络适配器，避免无效信息干扰
-
跨平台一致性：在 Android、iOS、Browser、OHOS 平台提供统一 API，屏蔽平台差异，降低开发成本
-
完整错误处理：针对权限不足、网络未连接等场景提供明确错误信息，便于问题定位
支持平台
-
Android（API 级别 22 及以上）
-
iOS（iOS 11.0 及以上）
-
Browser（主流浏览器，如 Chrome、Firefox、Safari 等）
-
OHOS（5.0 及以上）
下载安装
通过 hcordova CLI 即可快速安装插件，支持从 npm 仓库或 GitCode 仓库获取，安装前请确保已创建 Cordova 项目（若未创建，执行 cordova create networkApp com.example.networkapp NetworkApp 创建）。
前提条件
在安装插件前，请确保开发环境已满足以下条件：
-
已安装 Node.js（v14.0.0 及以上）和 npm（v6.0.0 及以上）
-
已安装 HCordova CLI（10.0.0 及以上），可通过以下命令安装：
npm install -g hcordova
- 已创建 Cordova 项目（若未创建，可通过
cordova create networkApp com.example.networkapp NetworkApp命令创建）
从 npm 安装（推荐）
# 安装最新稳定版插件
hcordova plugin add cordova-plugin-networkinterface
# 指定 OHOS 安装
hcordova plugin add cordova-plugin-networkinterface --platform ohos
# 安装指定版本（示例：1.0.0 版本）
hcordova plugin add cordova-plugin-networkinterface@1.0.0 --platform ohos
从 GitCode 仓库安装
适用于需要体验最新功能的开发者，仅为 OHOS 平台安装开发版插件：
# 仅支持 OHOS 平台
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-networkinterface.git --platform ohos
# 指定标签/分支安装
hcordova plugin add https://gitcode.com/CPF-Cordova/cordova-plugin-networkinterface.git@develop --platform ohos
离线安装（本地包）
适用于无网络环境，先下载插件包到本地，再执行离线安装：
# 下载插件包到本地（示例路径：../Downloads/cordova-plugin-networkinterface）
# 执行离线安装
hcordova plugin add ../Downloads/cordova-plugin-networkinterface --platform ohos
安装后验证
安装完成后，可通过以下命令验证插件是否成功添加到项目中：
# 查看已安装的插件列表，若包含本插件 ID 则表示插件已成功安装
hcordova plugin list
卸载
进入项目根目录，执行以下命令卸载插件，卸载后建议重新构建项目以清理残留的原生配置文件：
# Cordova CLI 全平台卸载
hcordova plugin remove cordova-plugin-networkinterface
# 指定平台卸载
hcordova plugin remove cordova-plugin-networkinterface --platform ohos
约束与限制
-
依赖插件：无强制依赖，可直接集成到 Cordova 项目中使用
-
权限要求：部分网络信息（如 MAC 地址）获取需设备授予对应权限，权限不足时会返回明确错误信息
-
IP 地址支持：当前获取 IP 地址功能仅支持 IPv4，IPv6 暂不支持
兼容性
支持：
| 项目 | 版本/信息 |
|---|---|
| SDK | API12+ |
| IDE | DevEco Studio: 5.0+ |
| ROM | 5.1+ |
| Emulator | OpenHarmony 6.0+ |
在以下版本中已测试通过：
| 项目 | 版本/信息 |
|---|---|
| @cordova-ohos/ohos | 14.0.1-ohos-14.0.1 |
| SDK | 5.0.0(12) |
| IDE | DevEco Studio: 6.0.13.200 |
| ROM | 5.1.0.120 SP3 |
| Emulator | OpenHarmony 6.0.1(21) |
使用示例
插件通过全局对象 networkinterface 暴露所有 API 方法，所有操作均需在 deviceready 事件触发后调用，支持回调函数调用方式，以下为各功能的完整使用示例，可直接复制到项目中使用。
1. 获取 wifi 的 IP 地址
获取当前设备正在使用的活跃网络适配器的 IP 地址信息，当前仅支持 IPv4，返回 IP 地址和子网掩码：
// 返回 ip 地址和子网掩码
networkinterface.getWiFiIPAddress(function(ipInformation){
document.getElementById("wifiIp").innerHTML = "IP: " + ipInformation.ip + " subnet:" + ipInformation.subnet;
},function(error){
document.getElementById("wifiIp").innerHTML = error;
})
返回结果（IP 信息对象）：
{
"ip": "192.168.1.100", // IP 地址
"subnet": "255.255.255.0", // 子网掩码
}
2. 获取蜂窝网络的 IP 地址和子网掩码
获取当前连接的蜂窝网络 IP 地址及子网掩码信息：
networkinterface.getCarrierIPAddress(function(ipInformation){
document.getElementById("4GIp").innerHTML = "IP: " + ipInformation.ip + " subnet:" + ipInformation.subnet;
},function(error){
document.getElementById("4GIp").innerHTML = error;
})
返回结果（IP 信息对象）：
{
"ip": "192.168.1.100", // IP 地址
"subnet": "255.255.255.0", // 子网掩码
}
3. 获取代理信息
获取指定地址的 HTTP 代理信息，返回代理类型、地址和端口：
function getHttpProxyInformation() {
networkinterface.getHttpProxyInformation("http://www.***.com", function(proxy){
document.getElementById("proxy").innerHTML = "type: " + proxy.type + " host:" + proxy.host+" port:"+proxy.port;
},function(error){
document.getElementById("proxy").innerHTML = error;
})
}
返回结果（适配器列表）：
{
"type": "1", // 1：配置有代理，0：无代理直连方式
"host": "192.168.1.100", // 返回代理地址
"port": 8090 // 返回代理端口
}
使用说明
以下为插件使用的核心说明，包括 API 详解、返回结果说明、注意事项等，帮助开发者快速上手并避免异常。
1. 核心 API 说明
插件通过全局对象 networkinterface 暴露所有 API 方法，无需额外引入，需在 Cordova 加载完成后（即 deviceready 事件触发后）调用，否则可能出现 API 调用失败的异常。
1.1 getWiFiIPAddress：获取 WiFi 的 IP 地址
功能：获取当前设备正在使用的活跃 WiFi 网络适配器的 IP 地址信息，当前仅支持 IPv4。
参数说明：
-
成功回调（第一个参数）：触发时返回 IP 信息对象，包含
ip（IP 地址）和subnet（子网掩码）两个属性。 -
失败回调（第二个参数）：触发时返回错误信息字符串，用于排查问题（如权限不足、未连接 WiFi 等）。
1.2 getCarrierIPAddress：获取蜂窝网络的 IP 地址
功能：获取当前设备连接的蜂窝网络（4G/5G）的 IP 地址及子网掩码信息。
参数说明：
-
成功回调（第一个参数）：触发时返回 IP 信息对象，结构与
getWiFiIPAddress返回结果一致。 -
失败回调（第二个参数）：触发时返回错误信息字符串（如未连接蜂窝网络、权限不足等）。
1.3 getHttpProxyInformation：获取代理信息
功能：获取指定网络地址的 HTTP 代理信息，判断是否配置代理及代理详情。
参数说明：
-
第一个参数：需检测代理的网络地址（如
http://www.***.com）。 -
成功回调（第二个参数）：触发时返回代理信息对象，包含
type（代理类型，1 为有代理，0 为无代理）、host（代理地址）、port（代理端口）三个属性。 -
失败回调（第三个参数）：触发时返回错误信息字符串（如地址无效、网络未连接等）。
2. 返回结果说明
插件所有 API 的成功回调均返回对应信息对象，各对象结构及字段说明如下：
2.1 IP 信息对象（getWiFiIPAddress、getCarrierIPAddress 返回）
| 字段名 | 类型 | 说明 |
|---|---|---|
| ip | 字符串 | 设备对应网络适配器的 IPv4 地址 |
| subnet | 字符串 | 对应网络的子网掩码 |
2.2 代理信息对象（getHttpProxyInformation 返回）
| 字段名 | 类型 | 说明 |
|---|---|---|
| type | 字符串 | 代理类型，1 表示配置有代理，0 表示无代理直连 |
| host | 字符串 | 代理服务器地址（type 为 1 时有效） |
| port | 数字 | 代理服务器端口（type 为 1 时有效） |
3. 注意事项
-
API 调用时机：所有 API 必须在
deviceready事件触发后调用，否则会导致 API 未定义、调用失败等异常。 -
权限配置：部分网络信息（如 MAC 地址）的获取需要设备授予对应权限，权限不足时会触发失败回调并返回明确错误信息，需在应用中处理权限申请逻辑。
-
IP 地址支持：当前插件仅支持获取 IPv4 地址，IPv6 地址暂不支持，若需 IPv6 相关功能，可关注插件后续更新。
-
网络状态要求：获取 WiFi 或蜂窝网络 IP 地址时，需确保设备已连接对应网络，否则会返回网络未连接相关错误。
-
错误处理：建议在所有 API 的失败回调中添加错误日志打印或用户提示，便于排查问题，提升应用体验。
目录结构
cordova-plugin-networkinterface # [根目录] 网络接口插件项目根目录
├── src # [源码目录] 存放原生平台代码
│ └── main # [主目录] 主代码目录
│ ├── cpp # [C++ 目录] C++ 原生代码目录
│ │ └── NetworkManager # [C++ 模块] 网络管理 C++ 模块文件夹
│ │ ├── networkinterface.cpp # [C++ 实现] C++ 源文件，实现网络接口底层逻辑
│ │ └── networkinterface.h # [C++ 声明] C++ 头文件，定义接口
│ └── ets # [ArkTS 目录] ArkTS/ETS 代码目录
│ └── components # [组件目录] 存放 UI 或逻辑组件
│ └── PluginAction # [TS 模块] 插件动作逻辑文件夹
│ └── GetNetWorkInfo.ets # [ETS 文件] 获取网络信息的 ArkTS 实现
├── www # [前端目录] 存放供 Web 端调用的 JS 接口文件
│ └── networkinterface.js # [JS 文件] 暴露给 Web 端的网络接口操作 API
├── .gitignore # [Git 配置] 指定 Git 版本控制中需要忽略的文件和目录
├── LICENSE # [许可证] 项目的开源协议或版权声明
├── OAT.xml # [门禁配置] OHOS 系统的安全或权限配置文件
├── package.json # [NPM 配置] 项目元数据，包含版本、依赖等信息
├── plugin.xml # [Cordova 配置] 核心配置文件，定义插件结构和映射
└── README.md # [说明文档] 项目的使用说明和功能介绍
贡献代码
使用过程中发现任何问题都可以提 Issue ，当然也非常欢迎发 PR 共建。
许可证
本插件基于 Apache License 2.0 开源，详见 LICENSE 文件。
官方资源
-
Android 和 iOS：cordova-plugin-networkinterface 官方指南
-
GitCode 仓库：CPF-Cordova/cordova-plugin-networkinterface