@cordova-ohos/cordova-plugin-network-information

v3.0.0

Published

3 days ago

Cordova network information Plugin

Downloads

147

0High
0Medium
0Low

cordova network-information ecosystem:cordova cordova-openharmony

cordova-plugin-network-information

1. 插件介绍

cordova-plugin-network-information 是一款用于 Cordova/PhoneGap 应用的插件，旨在帮助开发者获取设备的网络连接状态信息，包括网络类型（如 WiFi、蜂窝数据等）、连接状态（在线 / 离线）等关键数据。通过该插件，开发者可以轻松实现网络状态监听、网络类型判断等功能，从而为用户提供更智能的应用体验（例如在离线时提示用户检查网络连接），本文档主要介绍该插件在OHOS系统中的应用。

该插件遵循 Cordova 插件开发规范，支持多平台运行，并提供了简洁易用的 JavaScript API，可快速集成到 Cordova 项目中。

2. 支持平台

该插件目前支持以下操作系统和平台：

Android (API 级别 22 及以上)
iOS (iOS 11.0 及以上)
Windows (Windows 10 及以上，包括 UWP 应用)
Browser (主流浏览器，如 Chrome、Firefox、Safari 等)
OHOS (5.0 及以上)

3. 安装步骤

3.1 前提条件

在安装插件前，请确保你的开发环境已满足以下条件：

已安装 Node.js (v14.0.0 及以上) 和 npm (v6.0.0 及以上)
已安装 HCordova CLI (10.0.0 及以上)，可通过以下命令安装：

npm install -g hcordova

已创建 Cordova 项目（若未创建，可通过 hcordova create myApp 命令创建）

3.2 插件安装命令

在 Cordova 项目根目录下，执行以下命令安装插件：

从 npm 安装（推荐）

#全平台安装
hcordova plugin add cordova-plugin-network-information

#指定OHOS平台安装
hcordova plugin add cordova-plugin-network-information --platform ohos

从 GitCode 源码安装

hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-network-information.git --platform ohos

安装指定版本

hcordova plugin add [email protected] --platform ohos

3.3 插件卸载命令

若需卸载插件，执行以下命令：

#全平台卸载
hcordova plugin remove cordova-plugin-network-information

#指定平台卸载
hcordova plugin remove cordova-plugin-network-information --platform ohos

4. 核心 API 说明

插件通过 navigator.connection 对象暴露所有网络相关 API，以下是核心功能的详细说明。

4.1 获取当前网络状态

通过 navigator.connection.type 可获取当前设备的网络类型，返回值为字符串类型，具体枚举值如下：

| 返回值 | 说明 | | ---------- | ------------------------- | | unknown | 未知网络类型 | | ethernet | 以太网连接 | | wifi | WiFi 网络 | | 2g | 2G 蜂窝网络（如 GSM、CDMA） | | 3g | 3G 蜂窝网络（如 WCDMA、CDMA2000） | | 4g | 4G 蜂窝网络（如 LTE） | | cellular | 通用蜂窝网络（未区分 2G/3G/4G） | | none | 无网络连接（离线） |

示例代码

// 获取当前网络类型
const networkType = navigator.connection.type;
// 打印网络类型
console.log('当前网络类型：', networkType);
// 判断是否为 WiFi 网络
if (networkType === navigator.connection.WIFI) {
   alert('当前使用 WiFi 网络');
}

// 判断是否离线
else if (networkType === navigator.connection.NONE) {
   alert('当前无网络连接，请检查网络设置');

}

4.2 监听网络状态变化

通过 document.addEventListener 监听 online 和 offline 事件，可实时捕获网络连接状态的变化（在线 / 离线）；监听 networkconnectionchange 事件，可捕获网络类型的变化（如从 WiFi 切换到 4G）。

4.2.1 监听在线 / 离线事件

// 监听“在线”事件

document.addEventListener('online', function() {
   alert('网络已连接，当前网络类型：' + navigator.connection.type);
}, false);

// 监听“离线”事件

document.addEventListener('offline', function() {
   alert('网络已断开，请检查网络连接');
}, false);

4.3 网络类型常量

插件为常用网络类型定义了常量，可直接通过 navigator.connection 访问，避免硬编码字符串，提高代码可读性：

| 常量名 | 对应值 | 说明 | | ---------- | ---------- | ------- | | UNKNOWN | unknown | 未知网络类型 | | ETHERNET | ethernet | 以太网 | | WIFI | wifi | WiFi 网络 | | CELL_2G | 2g | 2G 蜂窝网络 | | CELL_3G | 3g | 3G 蜂窝网络 | | CELL_4G | 4g | 4G 蜂窝网络 | | CELLULAR | cellular | 通用蜂窝网络 | | NONE | none | 无网络连接 |

5. 完整示例

以下是一个完整的 Cordova 页面示例，展示如何集成插件并实现网络状态监听功能：

<!DOCTYPE html>
<html>
<head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>网络状态监听示例</title>
   <script type="text/javascript" src="cordova.js"></script>
   <script type="text/javascript">
       // Cordova 加载完成后执行
       document.addEventListener('deviceready', onDeviceReady, false);
       function onDeviceReady() {
           console.log('Cordova 已加载完成');
           // 初始化时获取当前网络状态
           updateNetworkStatus();
           // 监听网络状态变化
           document.addEventListener('online', updateNetworkStatus, false);
           document.addEventListener('offline', updateNetworkStatus, false);
       }

       // 更新网络状态显示
       function updateNetworkStatus() {
           const networkType = navigator.connection.type;
           const statusElement = document.getElementById('network-status');
           // 根据网络类型设置显示内容
           let statusText = '';
           switch (networkType) {
               case navigator.connection.WIFI:
                   statusText = '当前网络：WiFi';
                   statusElement.style.color = 'green';
                   break;
               case navigator.connection.CELL_2G:
               case navigator.connection.CELL_3G:
               case navigator.connection.CELL_4G:
               case navigator.connection.CELLULAR:
                   statusText = `当前网络：${networkType}`;
                   statusElement.style.color = 'orange';
                   break;
               case navigator.connection.NONE:
                   statusText = '当前网络：离线';
                   statusElement.style.color = 'red';
                   break;
               default:
                   statusText = `当前网络：未知（${networkType}）`;
                   statusElement.style.color = 'gray';
                   break;
           }

           // 更新页面显示
           statusElement.textContent = statusText;
           console.log('网络状态更新：', statusText);
       }
   </script>
</head>
<body style="padding: 20px; font-family: Arial, sans-serif;">
   <h1>网络状态监听</h1>
   <p id="network-status">正在获取网络状态...</p>
</body>
</html>

6. OHOS平台特定注意事项

权限配置，在主项目的module.json5中添加网络权限配置

{
    "name": "ohos.permission.INTERNET"
}

7. 许可证

本插件基于 Apache License 2.0 开源协议发布，详见 LICENSE 文件。

8. 联系方式

若你在使用过程中遇到问题，可通过以下渠道获取帮助：

GitCode Issues：在仓库 GitCode 页面提交问题。
Apache Cordova：访问 Apache Cordova Android/iOS插件。