@ionic-native/network

本项目基于@ionic-native/[email protected]开发。

简介

一个用于获取设备网络连接状态信息的插件，支持对网络状态的实时监控和类型识别。兼容Android、iOS和OpenHarmony平台，为跨平台应用开发提供统一的网络状态管理能力。本文档主要说明在OpenHarmony系统中的应用。

在移动应用开发中，网络状态管理是常见的功能需求，常用于根据网络状态调整应用行为，提升用户体验。@ionic-native/network插件通过封装原生平台API，为开发者提供了统一的跨平台接口，无需深入原生开发即可实现网络状态的全方位监控。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @ionic-native/network

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @ionic-native/network

手动引入安装

1.添加插件配置

根据plugin.xml的config-json项，找到entry模块中config.xml文件，并根据param标签添加配置

<feature name="Network">
  <param name="harmony-package" value="Network" />
  <param name="onload" value="true" />
</feature>

2.修改CMake配置

根据plugin.xml的CMakeLists项，找到cordova模块，路径为target字段的文件CMakeLists.txt，添加add_library

add_library(cordova SHARED
  // ...
  NetworkManager/NetworkManager.cpp
  // ...
)

3.复制源码文件

根据plugin.xml的source-file项，将src字段的路径代码复制到cordova模块中target-dir字段的目录中：

将源码中src/main/cpp/NetworkManager目录下的NetworkManager.h、NetworkManager.cpp文件引入到cordova模块中src/main/cpp/NetworkManager目录下。

卸载

# hionic CLI卸载
hionic plugin remove @ionic-native/network

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony权限参考申请应用权限，在主工程的module.json5的requestPermissions添加ohos.permission.GET_NETWORK_INFO,示例如下：

{
  "name" : "ohos.permission.GET_NETWORK_INFO",
  "reason": "$string:network",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
}

配置

无特殊配置项

使用示例

示例1：获取当前网络类型

实现获取当前网络类型的功能。

import { Network } from "@ionic-native/network";

const getNetworkType = async () => {
  try {
    const type = Network.type;
    console.log('当前网络类型:', type);
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('获取网络类型失败:', errorMsg);
  }
};

示例2：监听网络连接状态

实现监听网络连接状态变化的功能。

import { Network } from "@ionic-native/network";

const listenNetworkStatus = () => {
  try {
    // 监听网络连接
    Network.onConnect().subscribe(() => {
      console.log('网络已连接');
    });
    
    // 监听网络断开
    Network.onDisconnect().subscribe(() => {
      console.log('网络已断开');
    });
    
    // 监听网络状态变化
    Network.onchange().subscribe((status: 'connected' | 'disconnected') => {
      console.log('网络状态变化:', status);
    });
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    console.error('监听网络状态失败:', errorMsg);
  }
};

使用说明

插件在全局对象 Network 下暴露所有功能接口，使用前需确保设备就绪事件（deviceready）已触发。

1. 获取网络类型

获取当前设备的网络连接类型。

属性签名

Network.type

2. 获取最大下行带宽

获取当前网络的最大下行带宽。

属性签名

Network.downlinkMax

3. 监听网络连接

监听设备获得网络连接的事件。

方法签名

Network.onConnect()

4. 监听网络断开

监听设备失去网络连接的事件。

方法签名

Network.onDisconnect()

5. 监听网络状态变化

监听网络连接状态变化的事件。

方法签名

Network.onchange()

网络类型返回值说明

| 返回值 | 说明 | |------------|-----------| | unknown | 未知网络类型 | | ethernet | 以太网连接 | | wifi | WiFi网络 | | 2g | 2G蜂窝网络 | | 3g | 3G蜂窝网络 | | 4g | 4G蜂窝网络 | | cellular | 通用蜂窝网络 | | none | 无网络连接（离线） |

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |---- cpp  # C++ 代码
|     |---- www    # Web 侧代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

常见问题（FAQ）

1. 为什么获取到的网络类型有时是"unknown"？

• 原因：可能是网络状态正在变化或者系统无法准确识别当前网络类型
• 解决方案：建议在网络状态稳定后再获取信息，或实现重试机制

贡献代码

使用过程中发现任何问题都可以提Issue，当然，也非常欢迎发PR共建。

许可证

本项目基于MIT License开源，详见LICENSE文件。