这台开发板里的App屏幕底部是一个不断滚动的列表顶部是相机预览画面。每次靠近一个物料箱蜂鸣器响一声列表里就多一条新的二维码记录。整套东西是用Flutter跑在OpenHarmony设备上的批量二维码扫描工具从零到一折腾了大概两周。先说结论Flutter for OpenHarmony做扫码类App完全可行但相机帧数据获取、识别引擎接入、批量状态管理这三个环节坑不少网上能搜到的完整实战资料也不多。这篇文章就围绕“批量扫描”这条主线把工程搭建、相机帧流、ZXing接入、去重机制、生命周期处理和常见问题一次讲透。如果你正准备在OpenHarmony设备上做类似的连续扫码工具这些内容可以直接照着用。1. 批量扫码是什么场景为什么把宝押在Flutter上1.1 批量扫和单次扫是两种完全不同的需求很多人一提“扫码App”第一反应就是扫一个码然后跳转。但批量扫描完全是另一回事用户拿着设备对着货架上的箱子一排扫过去每个条码都要被识别、记录、确认最后还要能统一导出或提交。有些场景更严格——同一个码在短时间内不能被重复计数但隔了几分钟又回来扫同一个码时又需要允许重新计数。这种需求在仓储盘点、固定资产清查、生产批次登记、展会签到里非常常见。核心差异有三点识别结果不是终点而是数据源需要实时追加到列表并持久化。不能扫一个就停扫描动作是连续的需要一套状态机来管理“识别中—已识别—暂停—恢复—完成”。需要严格的防重复机制既要避免同一帧被重复识别也要避免同一码在短时间窗口内多次入列。这些需求决定了底层不能只调用一个一次性扫码接口就完事必须自己掌控相机帧流和识别逻辑。1.2 Flutter for OpenHarmony到底成不成熟这里必须说实话OpenHarmony上跑Flutter不是开箱即用的官方一等公民但生态已经到了一定规模。OpenHarmony SIG维护了对应的Flutter SDK分支支持Flutter引擎在OpenHarmony设备上运行社区活跃度还行。我在实际开发中感受到的现状是基础Widget、路由、状态管理这些上层能力基本没问题但只要是涉及平台通道、原生插件的能力就没有Android/iOS那么丰富很多得自己封装或者改现有插件。举几个我这边的实际体验Flutter引擎在OpenHarmony上跑起来性能帧率尚可但第一次启动耗时比Android长需要有白屏容忍度。相机、蓝牙、传感器这类偏底层的插件社区有维护但版本匹配要花时间调。官方示例工程大多是Hello World级别的像扫码这种“相机原生能力自绘UI”的组合基本要靠自己拼。但如果你团队本身就是Flutter技术栈又想覆盖OpenHarmony设备这条路远比再养一套ArkTS开发团队成本低。我们选Flutter的原因就三条团队熟悉、跨端复用、UI表达力强。剩下的坑用工程手段填上就行。1.3 技术路线对比为什么不直接用ArkTS或Web方案OpenHarmony上做扫码其实有几条路可以走我评估过之后再定的Flutter方案优势明显短板适合场景ArkTS原生系统能力调用最直接、性能上限最高需要独立学习ArkTS、代码无法跨Android/iOS复用只做OpenHarmony单端且长期投入Flutter for OpenHarmony跨端复用、团队上手快、生态成熟底层插件需要适配、部分原生能力要自封已有Flutter技术栈、需同时覆盖多端Web页面套壳开发快、热更新方便相机帧流处理弱、体验割裂、批量连续识别吃力轻量查询类工具对我来说批量扫描的核心难点是“长时间连续识别时的稳定性”这恰恰需要底层帧流控制和识别引擎的紧密配合。Web套壳在这块的主动权太小ArkTS则要重复造Flutter生态里现成的轮子。所以最终选了Flutter for OpenHarmony方向定了后面就是具体干活。2. 环境搭建让Flutter跑在OpenHarmony上的第一仗2.1 SDK与工具链的准备在OpenHarmony上跑Flutter环境准备比普通Flutter项目多几个步骤。我当时参考了社区文档整体链路是DevEco Studio OpenHarmony SDK Flutter的OHOS分支SDK三件套。需要注意几个关键点DevEco Studio版本需要对照Flutter分支的要求老版本tools可能不兼容新API。Flutter OHOS分支SDK通过Git拉取后要设置环境变量指向对应目录再用它执行flutter命令。工程里实际编译时OpenHarmony侧会产生一个临时工程Flutter代码通过交叉编译产物嵌入进去。这里最容易翻车的是版本匹配。我的做法是先在一个干净的目录里把Flutter SDK和DevEco Studio装好跑一遍官方demo工程确认能装到开发板上再开始写业务代码。不要一上来就塞一堆依赖否则出了问题根本分不清是环境问题还是代码问题。2.2 创建工程与依赖引入工程结构上Flutter for OpenHarmony和普通Flutter工程很像pubspec.yaml管理Dart依赖另外需要维护OpenHarmony侧的原生工程目录。我们工程在pubspec里加了这些核心依赖camera获取相机预览和帧数据流用适配OHOS的版本zxing2d纯Dart实现的二维码识别库免去自己编译原生sopath_provider保存批量结果文件时用vibrate用户反馈震动这里有个选择上的思考扫码引擎为什么用zxing2d而不是原生ZXing因为Flutter for OpenHarmony的原生插件生态还不够丰富如果通过platform channel每次调用原生扫码延迟和连续识别吞吐量都受限。zxing2d是纯Dart实现直接啃帧数据流处理速度快、可定制度高而且不需要维护原生代码。2.3 权限声明与真机部署准备OpenHarmony对权限管控有自己的要求相机权限需要在module.json5里声明。我最初漏了这条导致App安装后预览画面黑屏排查了半天才发现是权限没申请。权限这块建议一次到位在module.json5里声明ohos.permission.CAMERA。首次进入扫码页时动态请求权限用户拒绝后要给出引导弹窗。批量扫描场景下设备可能长时间亮屏要考虑申请keep screen on权限避免息屏中断。部署方面我是先用DevEco Studio跑真机调试确认基础功能OK后再切到纯Flutter命令构建流程。开发中期会有很多帧格式、识别率的问题需要反复看日志提前把IDE的真机日志衔接调通能省大量时间。3. 相机预览与帧回调批量扫描的“眼睛”3.1 相机插件选型与预览实现相机是扫码功能的地基地基不稳后面全是坑。我们在OpenHarmony上尝试了社区维护的camera_ohos改造版最终还是回到基于camera插件官方Frame API的思路来做。如果你只做普通预览其实很轻松初始化CameraController设置ResolutionPreset然后开startImageStream逐帧取数据。但批量扫描对帧流有更高的要求预览画面需要清晰但不能因为预览拉高分辨率导致每帧处理跟不上。帧回调频率要稳定时不时掉帧会导致漏识。相机初始化失败时要有兜底UI不能白屏。我们的做法是预览分辨率选中等档位比如1280x720识别帧直接走Stream处理UI层另起一个缩放后的预览画面。这样避免把高清预览和识别帧混在一条流里性能分配更清晰。3.2 逐帧数据的获取链路camera插件会返回Plane数据或者自定义的StreamCameraImageOpenHarmony分支在这块的实现会有差异。我这边最终拿到的是YUV格式的帧数据然后按自己的需求转成ZXing能处理的格式。帧数据链路大致是监听相机的图像流回调每一帧都带宽、高、旋转角度和像素数组。判断当前帧格式把YUV做处理转成RGBA或直接转灰度。将灰度数据交给识别引擎。识别完成后释放帧避免积压。这里有个关键点不要在主线程上处理帧数据。相机会源源不断产帧主线程一旦被识别操作堵住帧率立刻掉下来预览就会卡成PPT。我把帧处理放到独立的Isolate里通过Rust/Port传送数据识别结果再传回UI线程。3.3 分辨率、帧率与旋转角度批量扫码对分辨率的选择有讲究。分辨率太高每帧处理时间太长分辨率太低小尺寸二维码会识别不出来。我实测下来1280x720能满足大部分距离下的码识别。帧率不需要拉满稳定在20-25fps即可太高会让CPU负载持续偏高设备发烫。手持设备扫码时屏幕自动旋转需要及时把帧的旋转角度同步给识别引擎否则识别率会明显下降。旋转问题是个大坑。我们用的开发板有时竖屏有时横屏帧数据本身的R角度如果没处理同一个二维码在横竖屏切换后识别率差得离谱。后来我在帧预处理阶段统一做了一次旋转对齐把图像校正到自然方向再识别问题才解决。这块原理很简单摄像头传感器的安装方向和UI方向不一致软件层必须做补偿。4. 扫码引擎接入从像素到二维码内容4.1 为什么选zxing2d二维码识别引擎无非几种选择Google ML Kit、ZXing原生库、ZXing的Dart移植版zxing2d、自己造轮子。OpenHarmony环境下前两个都涉及原生平台适配ML Kit更是别想直接用。zxing2d是纯Dart库虽然性能比原生C版本弱一些但好处是跨端一致、调试方便。实际用下来zxing2d在1280x720的帧上识别一个普通二维码耗时大约在20-50毫秒之间完全够批量扫描用。如果遇到连续多码场景可以在预处理时先裁剪ROI区域去掉大部分无效像素速度还能再快一倍。4.2 把帧数据喂给ZXing的过程zxing2d的核心逻辑和经典ZXing一致把灰度图转成LuminanceSource再交给MultiFormatReader读取。我当时封装了一个ScannerHelper核心步骤是final luminanceSource RGBLuminanceSource( width: width, height: height, rgbPixels: convertedBytes, ); final bitmap BinaryBitmap(GlobalHistogramBinarizer(luminanceSource)); final result reader.decode( bitmap, hints: { DecodeHint.POSSIBLE_FORMATS: [BarcodeFormat.QR_CODE], DecodeHint.TRY_HARDER: true, }, );注意几个细节灰度化可以直接从YUV的Y平面取值不需要转RGB再转灰度省一次拷贝。TRY_HARDER会显著提升小码识别率但会增加耗时批量扫描时按需开启。POSSIBLE_FORMATS里只留QR_CODE可以防止其它码制干扰识别。4.3 识别结果出来了还不是终点拿到result.text只是第一步。批量扫描里识别结果需要携带一整套上下文识别时间、位置坐标、重复次数、状态已处理/已确认/已跳过。我设计了一个ScanRecord模型字段如下class ScanRecord { final String code; final DateTime timestamp; final double? centerX; final double? centerY; int duplicateCount; ScanStatus status; }这个模型在后续去重、列表渲染、导出表格时都很有用。比如用户在盘点时可能希望看到某个码被扫了几次这时duplicateCount就有价值了。5. 批量扫描的核心状态机、去重与结果管理5.1 为什么必须要有一个扫描状态机批量扫描里的“批”字决定了这不是一个简单的往列表里追加结果的循环。用户会操作设备做各种状态切换开始扫描暂停扫描比如需要核对某个箱子恢复扫描结束批量并导出中途清空错误记录没有状态机这些状态交叉管理会变成一团乱麻。我实现了一个简单的ScanState枚举idle、scanning、paused、finished。所有UI按钮和识别流程都围绕这个状态流转只有scanning状态才允许识别并追加结果paused状态到来时立刻停止帧处理避免后台继续消耗CPU。这里有个体会状态变化必须和帧处理解耦。如果直接在UI回调里写if (state scanning)这种逻辑很容易漏掉边界条件。我把状态变化通过Stream发布帧处理Isolate订阅推送识别结果也通过Stream回传天然解耦。5.2 防重复扫描时间窗口和结果去重批量扫描最关键的一个问题就是防重复。一个码在摄像头前面停两秒钟算法可能在同一帧范围内识别出三四次如果不做处理列表里就会出现三条相同记录。我的做法是双重去重时间窗口去重同一个码在N秒内的重复识别结果直接丢弃。窗口大小可以配置默认2秒。列表级去重如果码已经存在于当前批量列表且状态为“已记录”就不调整列表计数只更新最后一个识别时间。bool _isDuplicate(String code) { final now DateTime.now(); final last _lastSeen[code]; if (last ! null now.difference(last) dedupWindow) { return true; } _lastSeen[code] now; return false; }时间窗口不能设太长否则用户扫完一个码再去扫另一个马上回扫第一个时会被忽略也不能太短否则同一帧的重复识别会穿透。2-3秒是实践经验里比较稳的值。另一个细节批量列表已经导出一轮后下一次重新开始批量活动时_lastSeen必须清空否则之前扫过的码会被错误拦下。5.3 结果列表的实时渲染与批量操作扫描列表是批量扫描的“成果区”用户无时无刻不在盯它。这里我做了两个层面的优化UI层用了ListView.Builder做虚拟列表几百条记录不会卡。同时根据ScanStatus显示不同背景色新记录绿色高亮几秒重复记录灰色异常记录红色。高亮效果通过一个短期的Timer控制到点自动恢复。数据层则维护一个独立的Notifier任何新增/去重/状态变化都通知列表刷新。这里有个性能注意点不要每来一帧都setState重构整个列表只更新变化的那一行。否则识别的帧率一上去UI线程直接被列表重建打满。批量操作上我做了一个导出功能把ScanRecord列表序列化成CSV文件文件路径通过path_provider获取。实际盘点场景里用户盘点完直接把CSV发走或拷贝到电脑基本满足需求。6. 实战排坑帧格式、生命周期与内存6.1 同一个二维码横屏识别率骤降这个坑我印象极深。竖屏时识别一切正常旋转到横屏后同一个码识别率掉到一半以下。起初以为是相机对焦问题后来查日志发现camera插件的帧回调里每一帧数据的旋转角度标记和实际图像内容不一致。问题根源是传感器方向相对于UI方向有一个固定旋转角而且不同设备这个角不一样。解决方案是在帧预处理阶段把原始数据根据R角度做一次旋转——这里不是简单把Image旋转而是把像素缓冲区按照角度重新排列后再交给QR识别。我用了一个简单的坐标映射函数处理90度/180度/270度旋转识别率恢复到了竖屏水平。6.2 页面切后台再回来相机黑屏批量扫描过程中用户非常容易做出切App、看消息、锁屏的动作。等回到扫码页时相机经常直接黑屏。后来定位到是生命周期处理不彻底页面从后台恢复时没有重新初始化相机。我的修复思路分三步onPause时立即停止帧流和识别只保留控制器。onResume时先检查CameraController是否可用不可用就重新初始化。如果初始化失败显示一个“恢复扫码”按钮让用户手动重试。加了这个兜底之后黑屏问题基本消灭。但要注意OpenHarmony分支的camera插件在onResume的处理上并不完美不能完全依赖系统回调必须自己主动检查并尝试恢复。6.3 Isolate泄漏和帧缓冲区撑爆内存批量扫描是长时间运行的任务最容易出现内存问题。我在初版实现里每一帧都向Isolate发送数据并等待识别结果结果发现发送频率远超处理频率消息队列越堆越长内存一路飙升。后来给帧发送加了一个丢弃策略Isolate正在繁忙时新的帧直接丢弃不排队。识别处理能力大约是25ms每帧那么帧回调如果高于这个频率多余的帧直接忽略。这样既不会漏码同一个码会连续出现好多帧又保证了内存稳定。另外每次识别完一定要主动置空引用让Dart GC能回收临时对象。批量扫描场景跑半个小时这个细节决定了内存曲线是平稳还是线性上涨。7. 性能调优和体验打磨7.1 抽帧频率与识别区域的折中批量扫描并不需要每帧都识别。人可以保持一个相对稳定的手持姿势码在画面里停留时间至少有数百毫秒。我把识别频率控制在每秒10次左右也就是不跟相机帧率同步而是独立一个定时器从最新帧里取数据识别。这样带来的好处非常明显CPU负载大幅下降设备不发烫。电量消耗降低长时间盘点也能顶住。预留出CPU资源给UI动画和CSV导出。代价是码快速移动时偶尔会延迟识别到但实际使用场景里用户很少甩着设备扫稳定姿态下10fps识别完全够用。7.2 关闭不必要的识别增强zxing2d的TRY_HARDER模式在批量扫描里要谨慎用。它的原理是穷举更多的扫描线和对二值化阈值做更多尝试耗时可能是普通模式的两倍。除非你的目标画面里二维码经常很小、曝光不足否则我建议默认关闭只在切换到“密集小码模式”时才打开。另一个优化点DEFER_TO_OTHERS不要在批量模式里开。它会让reader尝试用上一帧的识别结果参数作为本轮优先搜索方向这在一帧里只有一个码时没问题但批量场景里用户可能连续扫不同箱子的不同码上一帧的搜索结果反而会误导下一帧的ROI搜索。7.3 震动、音效与灯光提示批量扫描的交互反馈直接影响用户的效率。每识别成功一个码如果都让用户低头看屏幕长时间使用会很累。我加了三个反馈通道震动识别成功后调用vibrate让手掌感知到。蜂鸣音用一个短的wav资源在成功时播放。注意批量频繁扫时音效不能太长100-150ms就够。高亮闪烁结果列表里新增的那一行绿色闪烁300ms用户余光能扫到。这三点加完后设备的“掌控感”立刻不一样了。很多用户甚至不用盯着屏幕只听声音就知道有没有扫进去。这个体验打磨的过程花的时间比预想的多但实际收益特别大。8. 批量扫码列表的进阶按码归组与冲突处理8.1 同一批里多种码并存我在开发中发现实际盘点的码并不是全都一样。大部分是普通二维码但有些箱子上的二维码会套着一层塑料膜反光严重还有一些是磨损过的旧码图案残缺。批量扫描的数据不能只按“识别到就存”处理还要能对这些异常码做标记。后来我引入了“归组逻辑”识别到的码先进入一个临时缓冲区不立刻写进正式列表。等它在后续帧里再次出现且结果一致时才确认入列。单帧识别到的、后续没有重复确认的码会被标记为“待确认”。这个策略大幅度降低了环境光、遮挡和塑料膜反光带来的误识别率。代价是第一次正确识别后要等第二次确认才能看到结果大概延迟不到1秒。对批量扫的人来说这个等待完全可接受换来的是结果可信度显著提升。8.2 识别冲突的兜底逻辑还有一类情况同一个画面里有两个二维码挨得很近这时引擎可能给出两个候选结果。批量扫描不能两者都收也不能随便丢一个。我的处理是如果两个结果来自同一帧且坐标距离小于一定阈值保留置信度更高的一个如果坐标距离远则都保留。识别结果里带出来的点位坐标在这种情况下相当管用。这段逻辑代码不多但边界条件很烦人。我的建议是先把坐标标准化到0-100的相对坐标系再做距离判断避免因为预览分辨率变化导致距离阈值失效。9. 灰度化、二值化对识别率的影响9.1 二值化方式的选择ZXing里最影响识别成功率的两个环节是LuminanceSource灰度图和Binarizer二值化。zx2d默认的GlobalHistogramBinarizer在明暗分布均匀时表现好但如果画面里有大面积高光或阴影局部二值化的效果往往会更好。我实测了两种情况仓库常见的日光灯环境、以及侧面光照下的条码GlobalHistogram在某些帧上会溃败。后来我改成根据整帧亮度方差动态选择二值化策略——亮度方差大时用LocalEffectBinarizer的近似实现方差小时用GlobalHistogram。识别率能稳定提升3-5个百分点。这里不展开二值化的算法细节但提一句扫码引擎的两值化不是可以盲调的黑盒环境越乱越值得在预处理上花功夫。9.2 为什么不要直接转RGB很多从Android搬Flutter的开发者习惯拿到帧先转成RGB再做二维码识别。这在Flutter for OpenHarmony上并不划算因为相机帧本身就带Y通道二维码识别本质只需要亮度信息直接切片Y平面当灰度图省掉一次完整像素拷贝。如果使用zxing2d的RGBLuminanceSource必须把数据转成RGB格式再传进去。我的做法是自定义了一个LuminanceSource子类直接把Y平面包装进去省掉一大块内存和带宽。批量扫描跑30分钟这个差异积累下来非常可观。9.3 曝光与对焦的微调OpenHarmony相机的自动曝光策略并不总是适合扫码——很多情况下它倾向于把场景调亮让二维码白色部分过曝深色模块反而识别失败。我试过在帧回调里统计亮度均值如果偏高就尝试降低曝光补偿但不同设备的实现差异较大最后采用了更可控的方式提供“增强模式”开关用户可以在扫码页手动切换提高识别稳定性。这个手动开关比盲目自动调参更符合实际同一个仓库里不同时间段的灯光条件完全不一样用户自己最清楚当前需要什么设定。10. 从原型到正式项目几个值得提前想清楚的设计决策10.1 用异步流还是回调我在早期版本里用Stream处理识别结果后期全部改成了独立的ScanCoordinator配合自定义StreamController。原因是批量扫描涉及的数据流不止一路相机帧流、识别结果流、状态流、UI事件流。如果都裸用Stream代码很快就会变成一团线。ScanCoordinator作为中介统一订阅和处理这些流。UI层只管发事件、收结果不直接碰帧数据。这个分层模式在项目变大后价值明显换相机实现、换识别引擎都不会动UI代码。10.2 扫描数据的本地存储怎么选批量扫描的数据最好在扫描过程中就持续落盘而不是等结束后一次性写CSV。原因很简单现场盘点可能进行一半设备断电一次性导出会丢失全部数据。我采用的方案是每条确认入列的数据同时追加到一个JSONL文件每行一条完整记录。App崩溃或杀掉文件还在。扫完再把JSONL转成CSV导出。这个设计代码量不大但紧急情况下的挽回价值非常高。10.3 适配不同OpenHarmony设备的摄像头能力OpenHarmony的设备形态比Android碎片化更严重有些是工业手持机有些是开发板外接摄像头有些是带屏幕的平板。它们的相机传感器、分辨率、帧率能力差异非常大。我的建议是把相机参数集中到一个配置对象里按设备型号预设一组参数。比如手持机用720p就够平板可以升到1080p。参数可远程下发的话更好我的做法是先写死配置文件后续再考虑动态下发。遇到从未见过的设备默认用最低通用配置保证能跑起来是第一优先级。写在最后这次Flutter for OpenHarmony批量扫码实战让我最深的体会是跨端框架的价值在业务逻辑层底层能力必须自己做适配层去兜底。Flutter的UI和状态管理帮助我把扫描状态机、结果列表、导出逻辑做得又快又稳但相机帧格式、旋转补偿、生命周期恢复这些活儿谁也替不了你。如果你也准备在OpenHarmony上做类似的二维码批量识别工具建议按这个顺序推进先跑通相机帧流再做单帧识别然后立刻把状态机和去重做了最后再回来打磨性能和体验。不要一上来就追求界面华丽帧流不稳、识别率不高界面再好看也白搭。最后分享一个小细节大批量扫描前我用白纸上打印了一组大号二维码做测试每个码旁边标注了序号。跑一轮下来对照列表里的识别顺序和序号能快速发现漏扫、乱序、重复计数的问题。这种土办法比任何单元测试都直接。