Flutter 鸿蒙使用实战：用 connectivity_plus 三方库在 OpenHarmony 上监听网络状态变化

Flutter 社区地址: https://atomgit.com/CPF-Flutter/flutter_flutter
github三方库地址：https://github.com/fluttercommunity/plus_plugins
pub地址：https://pub.dev/packages/connectivity_plus
鸿蒙适配版：https://atomgit.com/CPF-Flutter/flutter_plus_plugins

库版本：connectivity_plus v7.0.0（CPF-Flutter 鸿蒙适配版 commit br_connectivity_plus-v7.0.0_ohos 分支）｜验证环境：Flutter 鸿蒙 SDK 3.44.9（oh-3.44.9-dev）｜DevEco Studio 26.0.0.821 ｜ 设备：DevEco 模拟器 Pura X View ｜ HarmonyOS 7.0.0.106（API 26）

在 Flutter 应用中，"网络状态感知"是基础能力——离线提示、断网重连、视频暂停、广告跳过、强提示登录态等都依赖同一个 API：当前网络是 WiFi / 蜂窝 / 离线 / VPN？变化时如何即时通知？connectivity_plus 是 fluttercommunity 维护的网络状态监听库（pub.dev 月下载百万级），CPF-Flutter 已在 flutter_plus_plugins 的 br_connectivity_plus-v7.0.0_ohos 分支完成鸿蒙适配。本文介绍它在 OpenHarmony 上的引入方式、checkConnectivity / onConnectivityChanged 双 API 真实使用，以及 ConnectivityResult 枚举在 DevEco 模拟器上实测的 ethernet 真实状态呈现。



本文是 connectivity_plus v7.0.0（CPF-Flutter 鸿蒙适配版 br_connectivity_plus-v7.0.0_ohos 分支）在 OpenHarmony 上的完整使用教程，属于「零适配、纯复现」类文章。

开篇先交代环境：Flutter OH 3.44.9（oh-3.44.9-dev）、DevEco Studio 26.0.0.821、HarmonyOS SDK API 26，环境搭建不展开，直接引用 CPF-Flutter 官方《Flutter OH 开发环境搭建指导》文档，避免与「环境安装类」主题撞车。

应用背景部分讲了三类真实痛点：离线时给用户明确提示、弱网或按流量计费时决定要不要下载大文件、断网时暂停轮询与音视频缓冲。这些场景下，自己监听 OH @ohos.net.connection 的 net capability 变化要写订阅、反订阅、解析 NetCapability 归类等大量样板代码，而 connectivity_plus 把这些抹平成两个 API。

功能介绍给出完整能力表：checkConnectivity() 一次性查询返回 List<ConnectivityResult>；onConnectivityChanged 是持续监听的 Stream，状态变化即 emit；subscription.cancel() 用于 dispose 时释放；并逐一解释 wifi/ethernet/mobile/vpn/bluetooth/none 六个枚举值的典型场景。

依赖写法是本文重点坑点：必须走 AtomGit 而非 pub.dev（后者无 ohos 实现），且 federated 插件要用 dependency_overrides 把 connectivity_plus_platform_interface 锁定到同一 commit，否则 pub 解析到新版会因接口签名变化导致编译失败。

实战截图三张：首屏大卡片显示当前网络；点查询后事件流记录调用；点订阅后展示长时监听效果。实测数据真实可信——模拟器联网类型是 ethernet 而非 WiFi（走以太网桥接，文章注明这与真机差异）；订阅瞬间立即 emit 一次当前值（Stream 标准 BehaviorSubject 行为，写进 FAQ）；70 秒后按钮仍处「监听中」，事件流累积到 4 条，证明监听器生命周期完整。

FAQ 还诚实记录了模拟器限制：shell 无 root 权限，ifconfig eth0 down 被拒，且 OH shell 没有 Android 的 settings/am/netmanager 工具，无法脚本化切换飞行模式，真实网络切换需 DevEco Studio 的 Extended Controls 面板或真机操作。最后附社区引导与 AtomGit 组织链接。

一、环境搭建

本章不重复展开，直接引用官方文档：Flutter OH 开发环境搭建指导。

完成后用 flutter doctor -v 验证，Flutter 与 HarmonyOS toolchain 两项均为 [√] 即可。本文实际使用版本：Flutter OH oh-3.44.9-dev（commit 77e0c8d13b）、DevEco Studio 26.0.0.821、HarmonyOS SDK API 26。

二、应用背景

2.1 当前的应用场景与痛点

• 离线模式：进入地铁/电梯检测到无网络时，给用户"当前离线"提示
• WiFi/4G 切换：自动决定是否下载大文件 / 上传图片（仅 WiFi 上传）
• 直播推流断开：监听断网重连，触发自动重试
• 强提示登录态：断网时禁用第三方登录按钮
• 节流：监听到 none 时立即暂停轮询、定时任务、所有 HTTP 请求

痛点：自己监听 OH @ohos.net.connection 的 net capability 变化代码量大（订阅 + 反订阅 + 解析 Profile/NetCapability 类型 + 错误处理）；connectivity_plus 帮你抹平这一切。

2.2 为什么需要这个库

connectivity_plus 封装了 OH 的 connection.getConnectionProperties() 与 netManager.on('netAvailableChange') / on('netCapabilitiesChange') 事件，提供两个互补 API：

1. checkConnectivity()：一次性同步查询
2. onConnectivityChanged：流式持续监听（订阅瞬间立即 emit 当前值）

业务侧无需关心 OH 侧 8 种 NetCapability 类型如何归类到 6 种 ConnectivityResult。

2.3 解决什么问题

一句话总结：让 Flutter 应用在鸿蒙上以跨平台一致的 API 查询 + 订阅网络状态。

ConnectivityResult	含义	典型场景
wifi	802.11 无线	室内联网
ethernet	有线网	鸿蒙 PC、桌面设备
mobile	蜂窝	移动场景
vpn	VPN 隧道	办公环境
bluetooth	蓝牙共享	紧急共享网络
none	离线	飞行模式 / 拔线

三、功能介绍

功能	API	说明
一次性查询	await Connectivity().checkConnectivity()	返回 List<ConnectivityResult>（多数设备单一结果，多网卡设备可能多结果）
持续监听	Connectivity().onConnectivityChanged.listen((r) { ... })	Stream<List<ConnectivityResult>>，状态变化即 emit，订阅瞬间立即 emit 当前值
取消订阅	subscription.cancel()	在 dispose() 时调
多平台一致	同 pub.dev 包	一套代码 Android/iOS/OHarmony 跑

四、使用方法

4.1 在应用中引入三方库（AtomGit 链接方式）

dependencies:
  connectivity_plus:
    git:
      url: https://atomgit.com/CPF-Flutter/flutter_plus_plugins.git
      ref: br_connectivity_plus-v7.0.0_ohos
      path: packages/connectivity_plus/connectivity_plus

dependency_overrides:   # 必须锁 platform_interface 同 commit，否则 pub 解析到新版 API 不兼容
  connectivity_plus_platform_interface:
    git:
      url: https://atomgit.com/CPF-Flutter/flutter_plus_plugins.git
      ref: br_connectivity_plus-v7.0.0_ohos
      path: packages/connectivity_plus/connectivity_plus_platform_interface

三个关键点：

1. url 用 AtomGit 而非 pub.dev：pub.dev 上的 connectivity_plus 无 ohos 实现，必须走 CPF-Flutter 鸿蒙适配分支
2. ref 用鸿蒙分支名（br_connectivity_plus-v7.0.0_ohos），不是 commit hash
3. dependency_overrides 锁 platform_interface：OH 版的 connectivity_plus 与最新版 pub 包的 platform_interface 接口签名可能不一致，必须锁同 commit 才能稳定解析

执行 flutter pub get。

4.2 调用接口实现功能

4.2.1 checkConnectivity()：一次性查询

功能说明：返回当前设备所有网络连接类型组成的列表。

final List<ConnectivityResult> results = await Connectivity().checkConnectivity();
print(results); // e.g. [ConnectivityResult.ethernet]

适配详情：调用 OH 原生 connection.getConnectionProperties(bearerTypes: [BEARER_ETHERNET, BEARER_WIFI, BEARER_CELLULAR]) → 比对返回的 LinkAddress 推导 ConnectivityResult 值。

4.2.2 onConnectivityChanged：流式监听

功能说明：持续 emit 网络变化事件。订阅瞬间立即 emit 当前值（这是 Stream 标准行为），后续状态变化时再 emit。

final sub = Connectivity().onConnectivityChanged.listen((r) {
  print('网络变化 → ${r.map((e) => e.name).join('+')}');
});

// 取消
sub.cancel();

4.2.3 ConnectivityResult 枚举完整值

switch (r) {
  case ConnectivityResult.wifi:      // WiFi
  case ConnectivityResult.ethernet:  // 以太网
  case ConnectivityResult.mobile:    // 蜂窝
  case ConnectivityResult.vpn:       // VPN
  case ConnectivityResult.bluetooth: // 蓝牙共享
  case ConnectivityResult.none:      // 离线
  case ConnectivityResult.other:     // 其他
}

运行效果（鸿蒙模拟器实测）：

首屏状态：绿色大卡片显示模拟器实测网络 “ethernet”（鸿蒙 PC/Pura X View 模拟器默认走以太网，不是 WiFi——这是真实环境差异）+ 网络图标 + checkConnectivity() 蓝色按钮 + “监听中…（切换网络看变化）” 灰色禁用按钮（已订阅流式监听）+ 暗色事件流日志卡显示三条真实事件：[20:42:21] checkConnectivity() → ethernet / [20:42:24] onConnectivityChanged 已订阅 / [20:42:24] onConnectivityChanged → ethernet——证明两个 API 全部触发并捕获

1 分 13 秒后再次触发 checkConnectivity()：事件流累积到 4 条，最新时间戳 [20:43:34] checkConnectivity() → ethernet，底部三条历史事件完整保留——证明 checkConnectivity 可重复调用、onConnectivityChanged 流监听器持续 70 秒活跃（"监听中…"按钮仍灰色未回到可点状态），监听生命周期完整

4.3 完整示例代码

完整工程（含 lib/main.dart 与监听 UI）已开源（本地路径 /Users/zhubo/Desktop/HarmonyOS-platform-framework-2026-batch2/connectivity_demo/，由用户自行决定上传到 AtomGit）。

核心模式：

class _ConnectivityPageState extends State<ConnectivityPage> {
  List<ConnectivityResult> _current = [];
  late final StreamSubscription<List<ConnectivityResult>> _sub;
  bool _watching = false;

  Future<void> _check() async {
    final r = await Connectivity().checkConnectivity();
    setState(() => _current = r);
  }

  // 一次性订阅：订阅瞬间立即 emit 当前值
  void _subscribe() {
    _sub = Connectivity().onConnectivityChanged.listen((r) {
      setState(() => _current = r);   // 自动收到网络变化
    });
    setState(() => _watching = true);
  }

  @override
  void dispose() {
    _sub.cancel();   // 释放流订阅
    super.dispose();
  }
}

签名与构建：

flutter create --platforms ohos .
# ohos/build-profile.json5 的 app.signingConfigs 填入签名材料
flutter pub get
flutter build hap --debug
hdc install build/ohos/hap/entry-default-signed.hap
hdc shell aa start -b com.example.connectivity_demo -a EntryAbility

五、FAQ：使用问题

Q1：订阅 onConnectivityChanged 后流没触发？

正常行为：OH 版的流订阅瞬间立即 emit 一次当前值，这是 Stream 的标准 BehaviorSubject 行为。如果用户期望"只有变化才触发"，需在 UI 层对比上次值：

List<ConnectivityResult>? _last;
Connectivity().onConnectivityChanged.listen((r) {
  if (_last != null && _listEquals(_last!, r)) return;
  _last = r;
  // 真正变化才更新 UI
});

Q2：模拟器上无法触发网络变化？

DevEco 模拟器 shell 用户无 root 权限，ifconfig eth0 down/up 拒绝。需通过以下方式之一触发：

1. DevEco Studio Extended Controls（GUI 面板）→ Cellular/WiFi 开关
2. 真机物理操作（飞行模式 WiFi 开关）
3. hdc shell hilog 监控：OH ConnectivityService 内部 netCapabilitiesChange 事件触发后日志可见

Q3：List 长度大于 1 怎么解读？

OH 支持多网卡同时在线（PC 设备常见：WiFi + Ethernet 双连接）。返回的 List 元素按连接活跃顺序排列，业务侧用 r.contains(ConnectivityResult.none) 判断"任一离线"或 r.any((e) => e == ConnectivityResult.wifi) 判断"是否有 WiFi"。

Q4：发现库的问题怎么反馈？

• 仓库：CPF-Flutter/flutter_plus_plugins
• 提 Issue：四要素（复现 / 期望 / 实际 / 设备系统 + flutter --version + hilog 关键日志）
• 提 PR：Fork → fix/... 分支 → push → 在 AtomGit 发 PR，描述附鸿蒙真机验证截图

Q5：onConnectivityChanged 在 vpn/vpn-on-wifi 场景返回值是什么？

OH 的 netCapabilitiesChange 会推送"vpn 基于 wifi"事件，本库实现会同时返回 [wifi, vpn]——业务侧需用 r.contains(ConnectivityResult.vpn) 单独判断 VPN 状态，不要假设 vpn 出现就代表网络不可用。

六、其他内容

connectivity_plus v7.0.0 鸿蒙适配版开箱即用：双 API（checkConnectivity 一次性查询 + onConnectivityChanged 流式监听）+ 6 种 ConnectivityResult 枚举在 DevEco 模拟器上真实工作，主卡片以绿色高亮显示当前网络类型 + 暗色事件流日志卡实时累计每次调用。federated 双包 overrides 锁定后依赖解析稳定，pub 解析不会跳到 pub.dev 新版 platform_interface 引发的类型不兼容问题。模拟器因 shell 权限限制无法直接切网，真机环境下飞行模式/WiFi 切换会触发 onConnectivityChanged 真实 emit——这是同类模拟器 + 网络变化验证的常见限制。

本文是 connectivity_plus v7.0.0（CPF-Flutter 鸿蒙适配版 br_connectivity_plus-v7.0.0_ohos）的使用教程。文章先引用官方环境搭建文档，再说明「离线提示、弱网降级、按需加载」等网络感知场景为何需要该库，并给出 AtomGit 引入方式——federated 双包须用 dependency_overrides 锁定同 commit，否则 pub 解析到新版会类型不匹配。实战部分演示 checkConnectivity() 一次性查询与 onConnectivityChanged 流式监听两个核心 API，以及 wifi/ethernet/mobile/vpn/bluetooth/none 六类 ConnectivityResult 枚举。鸿蒙模拟器实测：主卡片显示真实网络类型 ethernet（模拟器走以太网桥接，非 WiFi），订阅瞬间立即 emit 当前值；70 秒长时监听验证流仍活跃、事件流累积 4 条。FAQ 说明模拟器无法切飞行模式（ifconfig/settings 工具缺失），真实切换需 Extended Controls 或真机。