Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 nearby_connections

爱吃大芒果

32人浏览 · 2026-10-16 16:30:14

爱吃大芒果 · 2026-10-16 16:30:14 发布

Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 nearby_connections

近场连接（Nearby Connections）是 Google Play Services 里的设备间通信组件：它把蓝牙和 Wi-Fi 的组合链路封装成“广播-发现-连接-传数据”的 API。nearby_connections 就是它的 Flutter 封装。这个库在鸿蒙上的适配结论从一开始就很明确：Play Services 是 Google 生态的组件，鸿蒙没有也不会有对应实现。所以适配的价值不在于“能不能跑”，而在于两件事：一是把 Dart API 的契约保留完整，让业务代码可以跨平台引用；二是把“不支持”用标准错误表达清楚，而不是伪造一次成功的广播。

本文以 nearby_connections 4.3.0 为例，记录我在 HarmonyOS API 26 模拟器上的构建、安装、启动和三个入口的调用验证。

适配仓库： oh-flutter/nearby_connections

适配分支： feat/ohos_nearby_connections_4.3.0

适配 TAG： 4.3.0-ohos.1

一、先看最终效果

图 1：HarmonyOS API 26 模拟器启动 Demo。页面显示插件返回的 OpenHarmony 3.47.4，状态为等待操作。

图 2：点击“发起广播”后的真实结果。ArkTS 返回 UNSUPPORTED，Dart 层捕获后显示错误。

验证点	实测结果	证据
Flutter OH 3.47 工程构建	通过	`entry-default-signed.hap`
签名、安装和启动	通过	图 1
`getPlatformVersion`	返回 `OpenHarmony 3.47.4`	图 1
`startAdvertising`	返回 `UNSUPPORTED`	图 2
`startDiscovery`	返回 `UNSUPPORTED`	图 3
`stopAllEndpoints`	安全无操作	图 4
近场连接能力	依赖 Google Play Services，鸿蒙无等价实现	适配边界

继续在模拟器上点击其余两个按钮：

图 3：调用 startDiscovery 后返回同一套 UNSUPPORTED 语义。

图 4：调用 stopAllEndpoints 安全完成，清理路径不会因为平台差异中断。

二、这个库原来是怎么工作的

nearby_connections 的 Dart 层通过名为 nearby_connections 的 MethodChannel 传递命令，并通过 EventChannel 接收回调（对端发现、连接请求、载荷进度等）。

Dart Nearby
  -> MethodChannel('nearby_connections')     # startAdvertising / startDiscovery / sendBytesPayload 等
  -> EventChannel('nearby_connections/events')  # 对端与连接事件
  -> Google Play Services Nearby Connections

它的 API 设计里有一个和其他库不同的点：startAdvertising 和 startDiscovery 是 Future<bool>，但真正的交互发生在事件流上。也就是说这两个方法返回 true 只代表“广播/发现已发起”，对端信息走回调。鸿蒙端把这两个入口做成 UNSUPPORTED 错误——注意这不是“返回 false”，返回错误比返回 false 更有诊断价值：false 会被业务理解为“发起失败，可以重试”，而 UNSUPPORTED 明确告诉业务“这个平台永远不会有这项能力，不要再试”。

停止类接口（stopAdvertising、stopDiscovery、stopAllEndpoints）则保持安全无操作。原因和前面几个库一致：它们通常出现在页面销毁的清理代码里，如果抛异常会打断清理链。

三、实际环境

Flutter 鸿蒙环境搭建不在本文重复展开，直接参考 Flutter OH 环境搭建指南。

组件	版本
Flutter OH	`3.47.4-ohos-1.0.4`
Dart	`3.13.3`
DevEco Studio	`26.0.0 Release`
HarmonyOS SDK	API 26
测试设备	DevEco 模拟器 Pura X View（HarmonyOS `7.0.0.105`，API 26）

本次验证使用 DevEco Studio 26.0.0 自带的 Pura X View 模拟器，系统版本与目标真机同为 HarmonyOS 7.0.0.105 / API 26；HAP 的签名、安装与启动链路和真机一致。
| 目标库 | nearby_connections 4.3.0 |

四、确认上游版本并同步到 AtomGit

上游包地址是 GitHub mannprerak2/nearby_connections，版本 4.3.0 使用 BSD 2-Clause License。适配前我在 AtomGit 目标组织中搜索了同名库，没有找到可以直接使用的 OHOS 实现。

仓库初始适配提交为 d7ed0be，完成后分支最新提交为 09aa2f0。

git clone https://atomgit.com/oh-flutter/nearby_connections.git
cd nearby_connections
git switch feat/ohos_nearby_connections_4.3.0
git log --oneline -5

五、创建适配分支并检查工程结构

git switch -c feat/ohos_nearby_connections_4.3.0

关键目录如下：

nearby_connections/
├── lib/src/
│   ├── nearby.dart                       # Nearby 类：全部方法入口
│   ├── classes.dart                      # ConnectionInfo 等模型
│   └── defs.dart                         # Strategy、Status 枚举与回调类型
├── ohos/
│   ├── index.ets                         # OHOS 插件导出入口
│   └── src/main/ets/components/plugin/
│       └── NearbyConnectionsPlugin.ets   # MethodChannel 实现
├── example/lib/main.dart                  # 上机验证 Demo
├── pubspec.yaml                          # 声明 ohos 平台
└── README.OpenHarmony_CN.md              # 鸿蒙适配说明

六、适配过程：能力错误与安全停止

OHOS 插件实现：

onAttachedToEngine(binding: FlutterPluginBinding): void {
  this.channel?.setMethodCallHandler(null);
  this.channel = new MethodChannel(binding.getBinaryMessenger(), 'nearby_connections');
  this.channel.setMethodCallHandler(this);
}

onDetachedFromEngine(binding: FlutterPluginBinding): void {
  this.channel?.setMethodCallHandler(null);
  this.channel = null;
}

方法映射：

Dart 方法	OHOS 本次策略
`getPlatformVersion`	返回 `OpenHarmony 3.47.4`
`startAdvertising`	返回 `UNSUPPORTED` 错误
`startDiscovery`	返回 `UNSUPPORTED` 错误
`stopAdvertising` / `stopDiscovery`	安全无操作
`stopAllEndpoints`	安全无操作

onMethodCall(call: MethodCall, result: MethodResult): void {
  switch (call.method) {
    case 'getPlatformVersion':
      result.success('OpenHarmony 3.47.4');
      return;
    case 'startAdvertising':
      result.error("UNSUPPORTED","Nearby Connections is not available on OpenHarmony.",null);
      return;
    case 'startDiscovery':
      result.error("UNSUPPORTED","Nearby Connections is not available on OpenHarmony.",null);
      return;
    case 'stopAdvertising':
      result.success(null);
      return;
    case 'stopDiscovery':
      result.success(null);
      return;
    case 'stopAllEndpoints':
      result.success(null);
      return;
    default:
      result.notImplemented();
  }
}

Demo 从上游示例（含权限申请、图片选择、文件传输的完整演示，依赖 image_picker、location、permission_handler 等库）收敛成三个按钮的验证页。这个收敛是必要的：上游示例的依赖链在鸿蒙工具链下无法解析，保留它们会让整个示例无法构建，反而验证不了插件本身。

七、构建配置与签名

示例工程的目标 SDK 对齐到 26，AppScope/app.json5 统一成 com.example.flutter_oh_demo，与 DevEco 调试签名对应。

{
  "name": "default",
  "compatibleSdkVersion": "26.0.0",
  "targetSdkVersion": "26.0.0",
  "runtimeOS": "HarmonyOS"
}

八、通过 AtomGit 引入适配版

dependencies:
  nearby_connections:
    git:
      url: https://atomgit.com/oh-flutter/nearby_connections.git
      ref: 4.3.0-ohos.1

九、构建、安装和设备验证

cd example
flutter pub get
flutter analyze
flutter build hap --debug
hdc install -r build/ohos/hap/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.example.flutter_oh_demo

构建输出为 ✓ Built build/ohos/hap/entry-default-signed.hap.，随后安装启动成功。模拟器上依次点击三个按钮得到图 2 至图 4：广播与发现返回 UNSUPPORTED，停止调用安全完成。

十、适配结果和当前边界

层次	已完成内容	尚未完成内容
Dart API	保留 Nearby 类与全部模型枚举	无
MethodChannel	通道名与方法名对齐	事件通道的事件源
OHOS 插件	注册、版本查询、能力错误、安全停止	真实近场通信
示例工程	三按钮验证页，鸿蒙工具链可构建	上游全量演示
文档	`README.OpenHarmony_CN.md`、CHANGELOG	无

如果未来要在鸿蒙上实现近场连接，路径不是移植 Play Services，而是基于鸿蒙的分布式软总线、蓝牙 BLE 或 Wi-Fi P2P 重新设计链路，再在插件里做平台分发。当前实现保证契约稳定、行为诚实：业务代码在鸿蒙上会立刻收到明确的“不支持”信号，可以据此降级到别的传输方案。

十一、FAQ

Q1：为什么返回错误而不是返回 false？

现象： startAdvertising 在鸿蒙上抛 UNSUPPORTED，而不是返回 false。
原因： false 的语义是“发起失败可重试”，而鸿蒙上这项能力不存在，重试也不会成功。
解决方法： 业务代码捕获 PlatformException 并检查 code == 'UNSUPPORTED'，据此走降级路径。
验证结果： 图 2 与图 3 显示错误码和原因都传到了 Dart 页面。

Q2：为什么停止接口不报错？

现象： 没发起过广播，调用 stopAllEndpoints 也没有异常。
原因： 停止类调用出现在清理路径，安全无操作保证清理链完整。
解决方法： 把停止调用理解为幂等的清理动作。
验证结果： 图 4 显示停止调用完成。

Q3：示例为什么要去掉权限和文件传输演示？

现象： 示例从完整演示收敛到三个按钮。
原因： 原演示依赖 location、image_picker 等库，这些库在鸿蒙工具链下没有实现，会导致示例不可构建。
解决方法： 保留最小验证面，聚焦插件通道本身。
验证结果： analyze 与 signed HAP 构建通过。

十二、总结

这次适配为 nearby_connections 4.3.0 补齐了 OHOS 插件注册，把广播与发现两个入口映射为明确的 UNSUPPORTED 错误，把三个停止入口映射为安全无操作，示例收敛为鸿蒙可构建的验证页。Demo 通过 Flutter OH 3.47.4 构建成签名 HAP，在 HarmonyOS API 26 模拟器上完成安装、启动和调用验证。

当前成果是“能力边界清晰、契约稳定”的适配基线。适配代码和说明都在 AtomGit 适配分支，复现时建议锁定 4.3.0-ohos.1 TAG。

十三、参考资料和仓库地址

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter
y_connections/blob/feat/ohos_nearby_connections_4.3.0/README.OpenHarmony_CN.md)

欢迎加入CPF-Flutter 鸿蒙社区：https://atomgit.com/CPF-Flutter

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

基于鸿蒙ArkTs+springboot的智能健康监测疾病预测系统设计与实现毕业设计源码+论文

人工智能6S服务平台

Flutter 3.47 鸿蒙三方库适配实战：从 0 到 1 处理 otp_autofill

这次适配为补齐了 OHOS 插件注册（双通道），把 Android 专属入口映射为统一的语义，保留的安全无操作。Demo 通过 Flutter OH 3.47.4 构建成签名 HAP，在 HarmonyOS API 26 模拟器上完成安装、启动和调用验证。当前成果是“契约完整、语义诚实”的适配基线。适配代码和说明都在AtomGit 适配分支，复现时建议锁定。

人工智能6S服务平台

使用 Ultralytics YOLO 进行模型训练

Ultralytics YOLO26提供高效、灵活的训练模式，支持单/多GPU、CPU、Apple MPS及华为昇腾NPU等多平台，具备自动下载数据集、超参数自定义、云端训练与断点续训等功能。通过CLI或Python API，可轻松配置训练参数，如批量大小、学习率、数据增强与优化器（如MuSGD），并支持自动混合精度（AMP）、量化感知训练与模型可视化。其空闲GPU自动选择、多尺度训练与知识蒸馏等