npm package: @luqi_test/cordova-plugin-network-information
Description: Cordova network information Plugin
Author: Huawei Device, Inc. Ltd. and
Latest version: 3.0.0

# 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 前提条件

在安装插件前，请确保你的开发环境已满足以下条件：



1. 已安装 Node.js (v14.0.0 及以上) 和 npm (v6.0.0 及以上)

2. 已安装 HCordova CLI (10.0.0 及以上)，可通过以下命令安装：



```bash
npm install -g hcordova
```



1. 已创建 Cordova 项目（若未创建，可通过 `hcordova create myApp` 命令创建）

### 3.2 插件安装命令

在 Cordova 项目根目录下，执行以下命令安装插件：

#### 从 npm 安装（推荐）



```bash
#全平台安装
hcordova plugin add cordova-plugin-network-information

#指定OHOS平台安装
hcordova plugin add cordova-plugin-network-information --platform ohos

```

#### 从 GitCode 源码安装


```bash
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-network-information.git --platform ohos
```

#### 安装指定版本


```bash
hcordova plugin add cordova-plugin-network-information@1.0.0 --platform ohos
```

### 3.3 插件卸载命令

若需卸载插件，执行以下命令：


```bash
#全平台卸载
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 监听在线 / 离线事件

```js
// 监听“在线”事件

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 页面示例，展示如何集成插件并实现网络状态监听功能：



```html
<!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中添加网络权限配置

```json
{
    "name": "ohos.permission.INTERNET"
}
```

## 7. 许可证

本插件基于 **Apache License 2.0** 开源协议发布，详见 [LICENSE](LICENSE) 文件。

你可以自由使用、复制、修改、分发和 sublicense 本插件，无需支付任何费用，但需在分发时保留原始版权声明和许可证信息。

## 8. 联系方式

若你在使用过程中遇到问题，可通过以下渠道获取帮助：

* **GitCode Issues**：在 [仓库 GitCode 页面](https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-network-information/issues) 提交问题。

* **Apache Cordova**：访问 [Apache Cordova Android/iOS插件](https://www.npmjs.com/package/cordova-plugin-network-information)。