电容网络插件

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

特征

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

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

缺少一个功能? 刚刚 打开一个问题 我们看看!

使用大小写

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

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

兼容性

指南

• 如何检测控制器中的网络状况: 检查连接类型, 听取更改, 并处理离线连接和分解连接 .
• 如何在电容器中探测卫星网络:探测Android 15+和iOS 26上的卫星和超受限网络并适应有限的带宽.

安装

你可以用我们的 AI 辅助设置 以安装插件. 添加数据 超级技能 至您的 AI 工具,使用以下命令:

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.

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

npm install @capawesome/capacitor-network
npx cap sync

打开 机器人,插件宣布 ACCESS_NETWORK_STATE 因此不需要额外的配置.

配置

此插件不需要配置 .

使用量

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

获取当前网络状态

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

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

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

探测卫星网络

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

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

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

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

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

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

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

检测超约束网络

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

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

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

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

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

检查飞机模式是否启用

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

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

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

查看网络状态的更改

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

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

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

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

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

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

API 密码

• getStatus()
• isAirplaneModeEnabled()
• addListener('networkStatusChange', ...)
• removeAllListeners()
• 接口
• 数字

获取状态( C)

getStatus() => Promise<GetStatusResult>

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

仅在Android,iOS和Web上提供.

回返情况: Promise<GetStatusResult>

自: 0.1.0 (中文(简体) )

飞机模型

isAirplaneModeEnabled() => Promise<IsAirplaneModeEnabledResult>

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

只能从Android上找到.

回返情况: Promise<IsAirplaneModeEnabledResult>

自: 0.1.0 (中文(简体) )

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

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

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

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

仅在Android,iOS和Web上提供.

回返情况: Promise<PluginListenerHandle>

自: 0.1.0 (中文(简体) )

删除所有收听器( )

removeAllListeners() => Promise<void>

删除此插件的所有听众 .

自: 0.1.0 (中文(简体) )

接口

获取状态

飞机模型

插件听筒

数字

连接类型

网络信息

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

• 机器人: 网络状态从 ConnectivityManager编辑 internetReachable 财产反映 NET_CAPABILITY_VALIDATED 能力,当一个 VPN 或 封存的门户活动时,可以修正假阳性.
• iOS系统: 网络状态从 NWPathMonitor 网络框架。 这个 internetReachable 属性总是 null 因为iOS无法区分经验证的互联网接入和单纯的连接. VPN连接报告为 UNKNOWN编辑 isAirplaneModeEnabled() 方法不可用,因为没有公开的API.
• 网页: 网络状态从 navigator.onLine 编辑 网络信息 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 而不是潜在的误导价值。 在这些平台上,连接到一个网络并不能保证互联网能够到达。 见 网络信息 具体平台细节.

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

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

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

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

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

不,插件在没有任何额外配置的情况下起作用 。 在Android上,插件已经声明了所需的内容 ACCESS_NETWORK_STATE 允许在自己的清单中,参见: 安装 节.

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

在iOS上,网络状态从 NWPathMonitor 网络框架,VPN连接作为 UNKNOWN编辑 VPN 连接类型只在能够检测到它的平台上报告,如Android. 见 网络信息 区域,用于更多平台差异.

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

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

相关插件

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

通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 《卡帕索克通讯》。 。 。 .

更改日志

见 变动情况。 。 。 .

许可证

见 自由主义。 。 。 .