Flutter for OpenHarmony 蓝牙通信实战：经典蓝牙 + BLE 双通道完整实现

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
摘要
本文聚焦OpenHarmony 跨平台 Flutter 工程蓝牙能力开发，基于 flutter_blue_plus、flutter_ble_lib、blue_thermal_printer 三大蓝牙依赖库，搭建可直接真机联调的经典蓝牙与 BLE 双通道通信骨架。文章完整覆盖工程改造、UI 集成、编译报错修复、鸿蒙权限适配、核心功能封装等全流程，解决跨平台蓝牙开发中兼容性、权限、编译失败等核心痛点，为鸿蒙 Flutter 开发者提供开箱即用的蓝牙通信解决方案。
一、项目背景与开发目标
在 OpenHarmony 跨平台 Flutter 应用开发中，蓝牙通信是智能设备连接、小票打印、数据交互的核心能力，但当前生态存在三大痛点：一是蓝牙三方库与鸿蒙 SDK 兼容性差异大；二是经典蓝牙、BLE 开发流程割裂，无统一接入方案；三是鸿蒙平台特有权限、后台扫描限制易导致功能异常。
本次开发以落地可用、易于扩展、适配鸿蒙为目标，完成 Flutter 工程蓝牙能力集成：集成三大蓝牙依赖、搭建双通道 UI 交互骨架、接入底部导航、修复编译报错、预留鸿蒙适配入口，最终实现可构建、可调试、可快速替换真实 API 的蓝牙通信模块。
二、工程基础配置：蓝牙依赖集成

1. 依赖声明（pubspec.yaml）
   在项目配置文件中添加蓝牙核心依赖，支持 BLE 通信、蓝牙打印、经典蓝牙管理，满足多场景设备交互需求：

dependencies:
  flutter:
    sdk: flutter
  # BLE 蓝牙核心库
  flutter_blue_plus: ^最新版
  # 鸿蒙兼容 BLE 辅助库
  flutter_ble_lib: ^最新版
  # 热敏蓝牙打印库
  blue_thermal_printer: ^最新版

添加后执行 flutter pub get 完成依赖拉取，确保无版本冲突。
2. OpenHarmony 权限适配（核心）
鸿蒙平台对蓝牙、位置权限有严格限制，需提前完成权限声明，核心权限包括：
蓝牙基础权限：蓝牙开启、扫描、连接权限
强制位置权限：鸿蒙 BLE 扫描必须依赖位置权限
后台权限：后台扫描、持久连接权限
设备管理权限：配对、数据传输权限
权限配置将在后续 BluetoothService 封装中统一实现，避免真机运行时权限拒绝。
三、核心功能实现：蓝牙中心页面开发

1. 页面集成与导航改造
   将工程原有「地图与位置」页面替换为蓝牙设备通信页面，挂载到底部导航第五个入口，无需额外跳转，直接满足真机联调需求。
   新增核心页面 BluetoothCenterScreen，作为蓝牙功能总入口，具备以下能力：
   经典蓝牙 / BLE 双通道切换入口
   设备扫描、配对、连接、数据发送交互骨架
   蓝牙打印测试功能
   实时运行日志、设备状态展示
   鸿蒙权限适配说明提示
2. UI 架构设计
   页面采用模块化设计，拆分四大功能区域：
   权限提示区：展示鸿蒙蓝牙 / 位置权限配置指引
   设备扫描区：双通道设备列表、扫描按钮
   操作控制区：连接设备、发送数据、打印测试独立按钮
   状态日志区：实时展示连接状态、扫描结果、报错信息
   整体 UI 极简易用，无冗余逻辑，方便后续替换原生 API。
   四、关键问题修复：编译报错解决
3. 报错原因
   工程编译失败，根源为 _InfoCard 自定义组件仅定义 title、body 参数，但在 _buildDeviceSection 中错误调用了不存在的 trailing 参数，导致 Flutter/Hvigor 编译中断。
4. 修复方案
   删除 _InfoCard 组件中所有无效的 trailing 参数调用，对齐组件定义
   重构操作区域，将「连接设备」按钮独立拆分，分别实现经典蓝牙首设备连接、BLE 首设备连接
   重新执行静态代码检查，确保无 lint 错误、无语法异常
5. 修复效果
   工程可正常执行构建命令，蓝牙页面无渲染错误，功能骨架完整可用。
   五、进阶优化：统一蓝牙服务封装（BluetoothService）
   为解决原生 API 调用混乱、兼容性差的问题，建议将所有蓝牙逻辑封装为单例 BluetoothService，集中管理核心能力：
   权限管理：鸿蒙蓝牙 / 位置权限动态申请
   扫描管理：双通道扫描控制、设备过滤、去重
   连接管理：连接保持、自动重连、断连监听
   数据通信：BLE Notify 监听、经典蓝牙串口发送
   打印功能：蓝牙打印机配对、小票指令下发
   该封装完全适配 OpenHarmony 平台特性，解决后台扫描限制、前后台切换授权、断连稳定性等鸿蒙特有问题。
   六、总结与后续规划
   本次完成了 OpenHarmony 跨平台 Flutter 工程蓝牙能力的全流程骨架搭建，实现依赖集成、UI 落地、导航接入、编译报错修复四大核心工作，当前工程可直接构建运行，无代码异常。
   后续可基于现有骨架快速迭代：
   替换 flutter_blue_plus 真实扫描、连接、Notify API
   接入 flutter_ble_lib 后台扫描与 GATT 数据收发
   实现 blue_thermal_printer 蓝牙打印完整功能
   完善鸿蒙权限自动申请、module.json5 配置
   本方案轻量化、高兼容、易扩展，完美适配 OpenHarmony 跨平台 Flutter 开发场景，可直接应用于智能设备、打印工具、物联网类跨端应用。
   运行示例