Flutter 三方库 serial 的鸿蒙化适配指南
在鸿蒙（OpenHarmony）系统的工业平板、手持 PDA 及桌面协同场景中，如何通过 Web 容器直接操控外部硬件设备（如扫码枪、打印机、传感器）？serial 作为一个优秀的 window.navigator.serial API 的 Flutter 封装库，为鸿蒙开发者提供了跨平台的硬件底座。本文将深入探讨其在鸿蒙生态中的适配要点。
前言
什么是 Web Serial？它允许鸿蒙应用内的 Web 组件直接请求访问用户的串行设备。在 Flutter for OpenHarmony 的实际开发中，serial 库抹平了异步流读取、波特率配置及端口管理在不同平台上的差异。对于构建需要'触达硬件'的鸿蒙工业级 Web 应用来说，它是核心连接器。
一、原理分析 / 概念介绍
1.1 硬件通信拓扑
serial 库主要作为底层浏览器 API 的强类型桥接层。
graph LR A["鸿蒙应用 UI (Web/Flutter)"] --> B["serial (Dart Wrapper)"]
B -- "Promise / Stream" --> C["Ohos Webview (Native Serial Engine)"]
C -- "HAL / NDK" --> D["鸿蒙系统串口驱动 (UART/USB)"]
D -- "TX/RX" --> E["外部硬件外设"]
1.2 为什么在鸿蒙上使用它？
- 零驱动依赖：利用鸿蒙内置 Webview 的标准能力，无需额外编写复杂的 FFI 桥接。
- 强类型流控：通过 Dart Stream 优雅地管理数据接收，避免传统回调（Callback）带来的逻辑地狱。
- 动态选配：支持运行时动态发现串口，适配鸿蒙设备多变的扩展硬件环境。
二、鸿蒙基础指导
2.1 适配情况
- 核心限制：该库目前主要基于 Web 标准。在鸿蒙端，它依赖于底层的浏览器内核支持
navigator.serial。对于鸿蒙原生（Native）应用，如需直接操作/dev/tty，可能需要额外配合 FFI 进行适配。 - 鸿蒙权限：需在
module.json5中确保开启相关的 USB 和硬件访问权限，并在 Webview 层开启串口权限请求的拦截。 - 平台特性：需关注鸿蒙系统的 USB OTG（On-The-Go）自动识别与权限弹窗策略。
2.2 安装配置
在鸿蒙项目的 pubspec.yaml 中添加依赖：
dependencies:
serial: ^0.0.7+1
三、核心 API / 组件详解
3.1 核心调用类与方法
| 类/方法 | 功能描述 | 鸿蒙端用法建议 |
|---|---|---|
Serial.requestPort() | 弹出硬件请求对话框 | 用于手动触发硬件授权 |
SerialPort.open() | 开启串口 | 需配置波特率（9600/115200 等） |
readable.stream | 接收数据流 | 核心接收闭环 |
writable.getWriter() | 发送数据流 | 操控硬件执行指令 |
3.2 基础开仓与发送示例
import 'package:serial/serial.dart';
Future<void> openOhosSerial() async {
// 1. 请求权限并发现端口
final port = await Serial.requestPort();
// 2. 开启通信链路
await port.open(baudRate: 115200);
// 3. 发送鸿蒙指令
final writer = port.writable.getWriter();
await writer.write(Uint8List.fromList([0x01, 0x02, 0x03]));
print("数据已成功推送至鸿蒙外设");
}
3.3 异步接收解析
// 在鸿蒙端持续监听串口回传
port.readable.stream.listen((data) {
print("收到远端硬件回传：${data.length} 字节");
});
四、典型应用场景
4.1 鸿蒙智能收银：外接热敏打印机
通过串口向小票打印机发送 ESC/POS 指令，完成实时单据输出。
4.2 鸿蒙实验室：传感器数据采集
采集温湿度或压力传感器数据，在鸿蒙大屏上绘制实时波动曲线图。
五、OpenHarmony 平台适配挑战
5.1 Webview 的串口权限拦截 (Critical)
在鸿蒙系统开发中，默认的 Webview 容器处于安全考虑可能会禁用 serial API。开发者必须在鸿蒙 Native 层（ArkTS/C++）拦截 onPermissionRequest 事件，并显式授予 ohos.permission.SERIAL_PORT（根据具体版本路径有所差异），否则 Serial.requestPort() 在鸿蒙端将静默失效。
5.2 平台差异化处理 (断链重连)
鸿蒙手持设备在移动过程中，USB 连接器可能由于震动产生物理断开。serial 库支持通过 getPorts() 轮询已授权端口。建议在鸿蒙端实现一套'心跳包'与'重连机制'，确保当硬件再次插入时，应用能静默恢复通信。
六、综合实战演示
import 'package:flutter/material.dart';
import 'package:serial/serial.dart';
class OhosHardLinkDemo extends StatefulWidget {
@override
_OhosHardLinkDemoState createState() => _OhosHardLinkDemoState();
}
class _OhosHardLinkDemoState extends State<OhosHardLinkDemo> {
String _status = "等待连接鸿蒙硬件...";
void _connectDevice() async {
try {
final port = await Serial.requestPort();
await port.open(baudRate: 9600);
setState(() => _status = "✅ 串口已链接：BaudRate 9600");
} catch (e) {
setState(() => _status = "❌ 连接失败：$e");
}
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: Text("鸿蒙硬软连接工作台")),
body: Center(
child: Column(
children: [
SizedBox(height: 50),
Icon(Icons.settings_input_composite, size: 100, color: Colors.amber),
Padding(
padding: EdgeInsets.all(30),
child: Text(_status, textAlign: TextAlign.center),
),
ElevatedButton(
onPressed: _connectDevice,
child: Text("扫射鸿蒙可用串口"),
)
],
),
),
);
}
}
七、总结
serial 库为鸿蒙应用打通了 Web 虚拟世界与硬件物理世界之间的屏障。虽然适配过程中需重点关注 Webview 的底层权限授予，但其标准化带来的高开发效率是其他方案无法比拟的。
知识点回顾：
requestPort是触发鸿蒙权限弹窗的关键。- 鸿蒙 Native 层必须配合处理 Webview 的硬件授权回调。
- 利用 Dart Stream 实现非阻塞式的串口高频数据交互。
