@cordova-ohos/cordova-plugin-networkinterface

v2.2.1

Published

23 days ago

Cordova Networkinterface Plugin

0High
0Medium
0Low

cordova networkinterface ecosystem:cordova cordova-openharmony

cordova-plugin-networkinterface

本项目基于 [email protected] 开发，本文档重点阐述其在 OpenHarmony（OHOS）系统中的具体应用。

cordova-plugin-networkinterface

简介

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 [email protected] --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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

cordova-plugin-networkinterface

简介

功能特性

支持平台

下载安装

前提条件

从 npm 安装（推荐）

从 GitCode 仓库安装

离线安装（本地包）

安装后验证

卸载

约束与限制

兼容性

使用示例

1. 获取 wifi 的 IP 地址

2. 获取蜂窝网络的 IP 地址和子网掩码

3. 获取代理信息

使用说明

1. 核心 API 说明

1.1 getWiFiIPAddress：获取 WiFi 的 IP 地址

1.2 getCarrierIPAddress：获取蜂窝网络的 IP 地址

1.3 getHttpProxyInformation：获取代理信息

2. 返回结果说明

2.1 IP 信息对象（getWiFiIPAddress、getCarrierIPAddress 返回）

2.2 代理信息对象（getHttpProxyInformation 返回）

3. 注意事项

目录结构

贡献代码

许可证

官方资源