# @capawesome/capacitor-network 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-network/

版本：0\.1\.5
npm 元数据更新时间：2026-10-21T06:20:05.468Z
中文译文更新时间：2026-11-09T09:09:23.904Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-network
原文对照：https://npmcn.com/package/%40capawesome/capacitor-network/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/network/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：99.6 kB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T12:20:32.466Z
- 最新版本发布：2026-10-21T06:20:04.905Z
- 近 30 天下载量：3131（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

电容插件可以访问关于Android,iOS,和Web的网络信息.

## 安装

```sh
npm install @capawesome/capacitor-network
```

也可以使用：`pnpm add @capawesome/capacitor-network`、`yarn add @capawesome/capacitor-network`、`bun add @capawesome/capacitor-network`

## README

# 电容网络插件

访问网络信息的电容插件.

[![Try Capawesome Cloud free for 14 days — iOS builds without a Mac](https://capawesome.io/assets/banners/cloud-free-trial-capacitor-apps.png)](https://capawesome.io/)

## 特征

Capacitor网络插件是Capacitor应用软件最完整的网络信息解决方案之一. 以下是一些关键特征:

-   📶 **网络状态**:读取设备是否连接以及如何连接(Wi-Fi,蜂窝,eethnet,VPN).
-   🌍 **互联网可达性**: 检测连接是否已经核实了互联网(Android)的访问.
-   💸 **数据保存成本( C)**: 检测连接是否受限(数据保存器或低数据模式)或昂贵(计量).
-   🛰️ **卫星网络**:探测到Android 15+上的卫星运输,以及iOS 26+上的超紧接接.
-   ✈️ **飞机模式**: 读取飞机模式是否启用(Android).
-   👂 **改变事件**: 查看网络状态的更改.
-   🌐 **网络支持**:在网络上读取网络状态.
-   🤝 **兼容性**: 与 [维菲](https://capawesome.io/docs/sdks/capacitor/wifi/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

网络插件通常在应用程序需要响应设备连接时使用,例如:

-   **离线检测**: 在连接丢失时显示离线横幅或禁用依赖网络的特性.
-   **有条件下载**:只有在设备通过Wi-Fi而不是蜂窝网络连接时才会下载大文件.
-   **可靠的同步**: 在Android上,检查连接在开始同步前是否已经核实了互联网接入,避免了被俘门户或VPN造成的假阳性.
-   **飞机模式提示**:在Android上,检测飞机模式被启用,并告知用户为何无法连接.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 指南

-   [如何检测控制器中的网络状况](https://capawesome.io/blog/how-to-detect-the-network-status-in-a-capacitor-app/): 检查连接类型, 听取更改, 并处理离线连接和分解连接 .
-   [如何在电容器中探测卫星网络](https://capawesome.io/blog/how-to-detect-satellite-networks-in-a-capacitor-app/):探测Android 15+和iOS 26上的卫星和超受限网络并适应有限的带宽.

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-network` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capawesome/capacitor-network
npx cap sync
```

打开 **机器人**,插件宣布 [`ACCESS_NETWORK_STATE`](https://developer.android.com/reference/android/Manifest.permission#ACCESS_NETWORK_STATE) 因此不需要额外的配置.

## 配置

此插件不需要配置 .

## 使用量

以下示例显示如何获得当前网络状态,检查飞机模式是否启用,并倾听网络状态的更改.

### 获取当前网络状态

读取设备目前是否连接,连接的类型(如Wi-Fi或蜂窝),以及Android上,连接是否已经验证了对互联网的访问:

```typescript
import { Network } from '@capawesome/capacitor-network';

const getStatus = async () => {
  const status = await Network.getStatus();
  return status;
};
```

### 探测卫星网络

读取设备是否通过卫星网络连接. 仅在Android上可用:

```typescript
import { ConnectionType, Network } from '@capawesome/capacitor-network';

const isSatellite = async () => {
  const { connectionType } = await Network.getStatus();
  return connectionType === ConnectionType.Satellite;
};
```

Android只使用受限制的卫星网络,用于识别自己对其最优化的应用. 如果您的应用被优化为极其有限的带宽和可变延迟,请在其中添加以下元素: `application` 图标 `AndroidManifest.xml`数字 :

```xml
<meta-data
  android:name="android.telephony.PROPERTY_SATELLITE_DATA_OPTIMIZED"
  android:value="PACKAGE_NAME"
/>
```

替换 `PACKAGE_NAME` 与您的应用程序的软件包名称。 此插件不会自动添加此元素, 因为每个应用程序必须决定它是否适合受限制的卫星访问 。 推进通知必须随同 `bandwidth_constrained_ok` 在这样的网络上发送旗帜。 见 [限制的卫星网络](https://developer.android.com/develop/connectivity/satellite/constrained-networks) 更多信息.

打开 **iOS系统**,载体提供的卫星连接报告为 `CELLULAR` 与 `ultraConstrained` 设置为 `true`,因为苹果并不将卫星暴露为连接类型.

### 检测超约束网络

读取连接在带宽方面是否受到严重限制,例如载波提供的卫星网络. 仅在Android和iOS 26+上提供:

```typescript
import { Network } from '@capawesome/capacitor-network';

const isUltraConstrained = async () => {
  const { ultraConstrained } = await Network.getStatus();
  return ultraConstrained;
};
```

打开 **机器人**这是 `true` 卫星网络和系统报告为带宽受限的网络。 卫星网络总是被报告为超受限,而带宽-受限探测则需要Android 16+(API级36)或 [U 扩展](https://developer.android.com/guide/sdk-extensions) 16+,可以在运行Android 14的合格设备上出现.

打开 **iOS系统**,检测此状态则不需要资格。 但是,如果您的应用程序想要通过这样的网络传输数据,它必须允许每个请求中的数据(参见: [`allowsUltraConstrainedNetworkAccess`](https://developer.apple.com/documentation/foundation/urlrequest/allowsultraconstrainednetworkaccess))并可能需要 [`com.apple.developer.networking.carrier-constrained.appcategory`](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.networking.carrier-constrained.appcategory) 允许所有承运人享有这种权利。 此插件既不添加应享权利,也不修改您的 `URLSession` 或者说 `NWParameters` 配置 。 见 [为超约束网络配置您的应用程序](https://developer.apple.com/documentation/bundleresources/configuring-your-app-for-ultra-constrained-networks) 更多信息.

### 检查飞机模式是否启用

读取当前是否启用飞机模式 。 仅在Android上可用:

```typescript
import { Network } from '@capawesome/capacitor-network';

const isAirplaneModeEnabled = async () => {
  const { enabled } = await Network.isAirplaneModeEnabled();
  return enabled;
};
```

### 查看网络状态的更改

当设备的网络状态发生变化时, 立即通知 。 设备只被观测到,而至少一个监听器被附加:

```typescript
import { Network } from '@capawesome/capacitor-network';

const addNetworkStatusChangeListener = async () => {
  await Network.addListener('networkStatusChange', status => {
    console.log('Network status changed:', status);
  });
};
```

当您不再需要更新时, 请删除所有听众 :

```typescript
import { Network } from '@capawesome/capacitor-network';

const removeAllListeners = async () => {
  await Network.removeAllListeners();
};
```

## API 密码

-   [`getStatus()`](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-getstatus)
-   [`isAirplaneModeEnabled()`](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-isairplanemodeenabled)
-   [`addListener('networkStatusChange', ...)`](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-addlistenernetworkstatuschange-)
-   [`removeAllListeners()`](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-removealllisteners)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-enums)

### 获取状态( C)

```typescript
getStatus() => Promise<GetStatusResult>
```

获取设备的当前网络状态 .

仅在Android,iOS和Web上提供.

**回返情况:** `Promise<[GetStatusResult](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-getstatusresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 飞机模型

```typescript
isAirplaneModeEnabled() => Promise<IsAirplaneModeEnabledResult>
```

获取飞机模式是否已启用 .

只能从Android上找到.

**回返情况:** `Promise<[IsAirplaneModeEnabledResult](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-isairplanemodeenabledresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 添加倾听器( “ 网络状态变化 ” ,...)

```typescript
addListener(eventName: 'networkStatusChange', listenerFunc: (event: GetStatusResult) => void) => Promise<PluginListenerHandle>
```

查看设备的网络状态变化 .

设备只在至少附着一个收听器时被观察到.

仅在Android,iOS和Web上提供.

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'networkStatusChange'` |
| **`listenerFunc`** | `(event: [GetStatusResult](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-getstatusresult)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-pluginlistenerhandle)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 删除所有收听器( )

```typescript
removeAllListeners() => Promise<void>
```

删除此插件的所有听众 .

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 获取状态

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`connected`** | `boolean` | 目前设备是否连接到网络 . | 0.1.0 (中文(简体) ) |
| **`connectionType`** | `[ConnectionType](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-connectiontype)` | 当前活动网络连接的类型 . | 0.1.0 (中文(简体) ) |
| **`internetReachable`** | `boolean | null` | 正在运行的网络连接是否验证了对互联网的访问. 这是 `null` 在无法验证互联网接入(iOS和Web)的平台上,连通性不能保证可访问性。 只能从Android上找到. | 0.1.0 (中文(简体) ) |
| **`constrained`** | `boolean | null` | 活动网络连接是否受数据保存限制,如Android上的数据保存器或iOS上的数据低模式. 这是 `false` 如果设备没有连接到网络 `null` 在不披露此信息的浏览器上. | 0.1.2 (中文(简体) ) |
| **`expensive`** | `boolean | null` | 活动网络连接是否被认为是昂贵的,例如一个Memet Wi-Fi网络或蜂窝网络. 这是 `false` 如果设备没有连接到网络 `null` 在无法确定连接成本的平台(Web)上. | 0.1.2 (中文(简体) ) |
| **`ultraConstrained`** | `boolean | null` | 主动网络连接在带宽方面是否受到严重限制,例如载体提供的卫星网络. 这是 `false` 如果设备没有连接到网络 `null` 在无法确定这一点的平台上(Web和iOS低于26). 在Android上,卫星网络总是被报告为超受约束. 检测其他受带宽限制的网络需要Android 16+(API级36)或U扩展16+. 仅在Android和iOS 26+上提供. | 0.1.2 (中文(简体) ) |

#### 飞机模型

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`enabled`** | `boolean` | 目前飞机模式是否启用 . | 0.1.0 (中文(简体) ) |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

### 数字

#### 连接类型

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Cellular`** | `'CELLULAR'` | 该设备通过蜂窝网络连接. | 0.1.0 (中文(简体) ) |
| **`Ethernet`** | `'ETHERNET'` | 该设备通过有线醚网网络相接. | 0.1.0 (中文(简体) ) |
| **`None`** | `'NONE'` | 该设备没有连接到任何网络 . | 0.1.0 (中文(简体) ) |
| **`Satellite`** | `'SATELLITE'` | 该设备通过卫星网络连接。 只能从Android上找到. | 0.1.2 (中文(简体) ) |
| **`Unknown`** | `'UNKNOWN'` | 无法确定网络连接的类型 . | 0.1.0 (中文(简体) ) |
| **`Vpn`** | `'VPN'` | 该设备通过虚拟私人网络(VPN)相接. | 0.1.0 (中文(简体) ) |
| **`Wifi`** | `'WIFI'` | 该设备通过无线网络连接. | 0.1.0 (中文(简体) ) |

## 网络信息

在访问网络信息时要铭记以下平台差异:

-   **机器人**: 网络状态从 [`ConnectivityManager`](https://developer.android.com/reference/android/net/ConnectivityManager)编辑 `internetReachable` 财产反映 [`NET_CAPABILITY_VALIDATED`](https://developer.android.com/reference/android/net/NetworkCapabilities#NET_CAPABILITY_VALIDATED) 能力,当一个 VPN 或 封存的门户活动时,可以修正假阳性.
-   **iOS系统**: 网络状态从 [`NWPathMonitor`](https://developer.apple.com/documentation/network/nwpathmonitor) 网络框架。 这个 `internetReachable` 属性总是 `null` 因为iOS无法区分经验证的互联网接入和单纯的连接. VPN连接报告为 `UNKNOWN`编辑 `isAirplaneModeEnabled()` 方法不可用,因为没有公开的API.
-   **网页**: 网络状态从 [`navigator.onLine`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine) 编辑 [网络信息 API](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API) (支持的地方). 这个 `internetReachable` 属性总是 `null`编辑 `isAirplaneModeEnabled()` 没有可用的方法.

## 财务问题

### 此插件与其他类似插件有何不同?

它在Android、iOS和网络上报告连通性和连接类型(Wi-Fi、蜂窝、醚网或VPN), 您可以读取状态一次或听取更改事件,设备只被观察,而听取者被附着,全部通过一个完全打入的API和打入的连接类型enum. 它在 iOS 上支持 CocoaPods 和 Swift 软件包管理器, 通过返回来诚实地了解平台限制 `null` 可达到性无法验证的,并针对最新的Capacitor和OS版本积极维护.

### 两者有什么区别 `connected` 财务报告和审定财务报表 `internetReachable`? 吗?

这个 `connected` 属性告诉设备是否连接到任何网络,同时 `internetReachable` 告诉你这个连接是否 已经核实进入互联网。 一个设备可以在不实际到达互联网的情况下连接到一个网络上,比如在被封存的门户后或者当一个VPN活动时. 这个 `internetReachable` 属性只在Android上可用,如果它反映了 `NET_CAPABILITY_VALIDATED` 连接能力.

### 为什么 `internetReachable` 永远 `null` 在iOS和Web上吗?

iOS 和 Web 平台无法区分已验证的互联网接入和纯网络连接, 因此插件返回 `null` 而不是潜在的误导价值。 在这些平台上,连接到一个网络并不能保证互联网能够到达。 见 [网络信息](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-network-information) 具体平台细节.

### 二者有何区别 `SATELLITE` 连接类型和 `ultraConstrained`? 吗?

这个 `SATELLITE` 连接类型告诉你连接是什么,而 `ultraConstrained` 告诉你,它严重限制带宽。 卫星只在Android上被报告为连接类型,因为iOS将这一条件暴露为连接属性. 两者并非总是相符的:卫星网络不一定报告为带宽受限,而带宽受限网络不一定是卫星网络.

### 我能检查飞机模式是iOS还是Web启用的吗?

不,那个 `isAirplaneModeEnabled()` 方法只在Android上可用. 在iOS上,没有公开的API来读取飞机模式状态,而Web平台也没有披露这些信息.

### 使用此插件需要任何权限吗 ?

不,插件在没有任何额外配置的情况下起作用 。 在Android上,插件已经声明了所需的内容 `ACCESS_NETWORK_STATE` 允许在自己的清单中,参见: [安装](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-installation) 节.

### 为什么VPN连接被报告为 `UNKNOWN` 在iOS上吗?

在iOS上,网络状态从 `NWPathMonitor` 网络框架,VPN连接作为 `UNKNOWN`编辑 `VPN` 连接类型只在能够检测到它的平台上报告,如Android. 见 [网络信息](https://npmcn.com/package/%40capawesome/capacitor-network/#readme-network-information) 区域,用于更多平台差异.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [电池](https://capawesome.io/docs/sdks/capacitor/battery/): 获取设备的电池信息.
-   [蓝牙低能](https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/):与蓝牙低能(BLE)设备在中外作用相通.
-   [NFC 纳菲公司](https://capawesome.io/docs/sdks/capacitor/nfc/):读取,写出,并仿取具有HCE等先进特性的NFC标签和原始命令处理.
-   [辛语](https://capawesome.io/docs/sdks/capacitor/sim/):读取SIM卡和载体信息.
-   [维菲](https://capawesome.io/docs/sdks/capacitor/wifi/):管理无线连接,包括添加,连接和断开网络.

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/network/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/network/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-network 是什么？

电容插件可以访问关于Android,iOS,和Web的网络信息\.

### 如何安装 @capawesome/capacitor-network？

在项目目录运行 npm install @capawesome/capacitor-network，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-network 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/capacitor-network 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-network 可以商用吗？

@capawesome/capacitor-network 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-network 的下载量有多少？

根据 npm 官方下载统计，@capawesome/capacitor-network 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,131 次，日均约 104 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/capacitor-network 还在维护吗？

最新版本 0\.1\.5 发布于 2026/10/21（19 天前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/07/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。