@capacitor/network

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/network 是 capacitor 生态系统中的核心插件，用于提供网络和连接信息，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境，本文档主要说明在 OpenHarmony 系统中的使用。

该插件提供查询网络连接状态、监听网络状态变化的能力，满足移动应用中根据网络状况调整行为的需求，比如在无网络时提示用户、切换不同的加载策略等。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

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

npm安装：

# 安装插件
npm install @capacitor/network

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/network

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
    "pkg": "@capacitor/network",
    "classpath": "Network"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Network)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Network
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中 src/main/cpp/Network 目录下的 Network.h、Network.cpp、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/Network 目录下。

卸载

# 卸载 network 插件
hionic plugin remove @capacitor/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"
  }
}

更多权限说明参考：申请应用权限。

使用示例

基础示例：监听网络状态变化

import { Network } from '@capacitor/network';

// 添加网络状态变化监听器
Network.addListener('networkStatusChange', status => {
  console.log('Network status changed', status);
});

// 获取当前网络状态
const logCurrentNetworkStatus = async () => {
  const status = await Network.getStatus();
  console.log('Network status:', status);
};

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | | ---- | ---- | ---- | | getStatus() | Promise<ConnectionStatus> | 查询当前网络连接状态 | | addListener('networkStatusChange', listenerFunc: ConnectionStatusChangeListener) | Promise<PluginListenerHandle> | 监听网络连接的变化 | | removeAllListeners() | Promise<void> | 移除该插件的所有监听器（包括网络状态的更改） |

数据结构

ConnectionStatus

表示网络连接的状态和类型

| 属性 | 类型 | 描述 | | -------------------- | ------------------ | ------------------------------------------------------------ | | connected | boolean | 是否存在活跃的连接 | | connectionType | ConnectionType | 目前使用的网络连接类型。如果没有活跃的网络连接，connectionType 会是 'none' |

ConnectionType

设备可能拥有的网络连接类型。

类型定义：

type ConnectionType = 'wifi' | 'cellular' | 'none' | 'unknown';

ConnectionStatusChangeListener

网络状态变化回调函数。

类型定义：

(status: ConnectionStatus) => void;

PluginListenerHandle

监听器句柄，用于移除监听器。

| 属性 | 类型 | | ------------ | ---------------------------------- | | remove | () => Promise<void> |

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- Network   # 插件核心 C++ 实现
|                             |---- Network.cpp
|                             |---- Network.h
|                             |---- CMakeLists.txt
|     |---- README.md          # 说明文档
|     |---- package.json       # npm 配置文件
|     |---- plugin.xml         # capacitor 插件配置
|     |---- LICENSE            # 许可证文件

贡献代码

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

许可证

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