第51篇｜OCR 识别库适配 HarmonyOS
图 1：OCR识别库适配封面图，用来概括本文主题、适配对象和工程边界。
相机预览帧进入 OCR 后没有稳定释放，连续扫描几次就会出现页面卡顿。
本文围绕图片帧和文字识别展开，目标不是把库接进工程后截图结束，而是把来源、版本、配置、封装、运行和验收写成一条读者可以复现的链路。
图 2：OCR识别库适配流程图，用来说明从需求拆解、依赖接入、封装实现到回归验收的主要步骤。
图 3：OCR识别库适配结构图，用来说明配置层、适配层、服务层、页面层和排错记录之间的职责。
1. 这类库先解决哪个工程问题
OCR识别库适配不能从 API 名称开始讲，要先说清楚它解决什么工程问题。实际接入时，读者最关心的是库进入项目后由哪一层调用、失败以后看哪里、版本升级时哪些地方需要回归。
本文把问题收敛到图片帧的输入、文字识别的执行和textCount的验收指标。这样写的好处是范围明确，读者不会把选型、封装、页面和发布说明混成一团。
| 判断点 | 本文处理方式 | 读者落地时要替换的内容 |
|---|---|---|
| 输入来源 | 统一为图片帧 | 替换成真实页面、文件或设备数据 |
| 核心动作 | 收敛到文字识别 | 替换成三方库真实 API |
| 验收指标 | 使用textCount做最小判断 | 替换成业务认可的结果字段 |
2. 源码和资料定位
适配前先建立源码地图。即使没有真实项目目录，也要把建议位置写清楚，让读者知道每段代码应该放在哪一层。
| 层级 | 建议文件 | 作用 |
|---|---|---|
| 依赖入口 | oh-package.json5或entry/src/main/cpp/CMakeLists.txt | 固定版本、源码或 Native 产物 |
| 适配层 | entry/src/main/ets/adapter/OcrEngineAdapter.ets | 处理输入、错误和三方 API 差异 |
| 服务层 | entry/src/main/ets/service/OcrScanService.ets | 暴露业务可读方法 |
| 示例页面 | entry/src/main/ets/pages/OcrScanServicePage.ets | 提供可复现验收入口 |
| 验收记录 | docs/ocr-engine-acceptance.md | 保存版本、命令和限制 |
3. 环境和版本边界
版本边界需要写在正文前半部分。HarmonyOS API、DevEco Studio、ohpm 包版本、Native ABI、设备能力都会影响结果，不能默认读者的环境和作者一致。
| 环境项 | 示例值 | 检查重点 |
|---|---|---|
| HarmonyOS API | API 12+ 或项目实际版本 | 系统能力、权限和组件行为 |
| 开发工具 | DevEco Studio 5.x | 构建、预览和签名流程 |
| 依赖形式 | ArkTS 包 / Native so / 源码模块 | 决定排查入口 |
| 目标设备 | 模拟器或真机 | 多媒体、蓝牙、相机等能力要真机确认 |
| 回归入口 | 示例页 + 命令行 | 能重复触发核心能力 |
4. 配置入口先收口
配置层只负责让依赖进入工程，不要混入业务判断。包管理类库固定版本，Native 类库固定 include、lib 和 ABI，涉及权限的库还要补模块声明。
{ "name": "ocr-engine-sample", "version": "1.0.0", "dependencies": { "@demo/ocr-engine": "1.0.0" }, "metadata": { "verifiedApi": "API 12+", "entry": "OcrScanService" } }这段配置的边界是“可追踪”。它让读者知道依赖从哪里来、版本是什么、入口服务是哪一个。真正的业务规则放到服务层，不放在配置里。
5. 适配层负责输入和错误
适配层不要只包一层同名方法。它要处理空输入、格式归一化、错误转换和返回结构。这样页面拿到的结果才稳定。
exportinterfaceOcrScanServiceResult{ok:boolean;message:string;textCount:number;}exportclassOcrEngineAdapter{normalize(raw:string):string{constvalue=raw.trim();if(value.length===0){thrownewError('图片帧不能为空');}returnvalue;}execute(raw:string):OcrScanServiceResult{constvalue=this.normalize(raw);return{ok:true,message:'文字识别完成: '+value,textCount:value.length};}}这段代码保护的是业务边界。三方库可以变化，但页面和上层服务只依赖OcrScanServiceResult，不会被底层参数结构拖着改。
6. 服务层承接业务语义
服务层要把适配层结果变成业务能直接消费的状态。它可以记录来源、补默认值、控制重试，但不要把页面状态和三方库细节混在一起。
import{OcrEngineAdapter,OcrScanServiceResult}from'../adapter/OcrEngineAdapter';exportclassOcrScanService{privateadapter=newOcrEngineAdapter();run(raw:string):OcrScanServiceResult{try{returnthis.adapter.execute(raw);}catch(err){return{ok:false,message:(errasError).message,textCount:0};}}}服务层的输入来自页面或业务流程，输出用于展示、缓存或提交。后续替换三方库时，只要服务层契约稳定，业务调用方就不用大面积改动。
7. 页面验收入口要可重复
示例页是文章可信度的一部分。读者需要看到输入、按钮、结果和异常信息如何串起来，而不是只看到一段孤立代码。
import{OcrScanService}from'../service/OcrScanService';@Entry@Componentstruct OcrScanServicePage{@Stateinput:string='ocr-engine-input';@Stateoutput:string='等待运行';privateservice=newOcrScanService();build(){Column({space:12}){TextInput({text:this.input,placeholder:'输入图片帧'}).onChange((value:string)=>this.input=value)Button('执行文字识别').onClick(()=>{constresult=this.service.run(this.input);this.output=`${result.ok}/${result.message}/ textCount=${result.textCount}`;})Text(this.output).fontSize(14)}.padding(20)}}页面验收要覆盖正常输入和空输入。空输入能否被明确提示，能直接反映适配层是否真正承担了边界保护。
8. Native 或底层调用边界
如果库有 Native、SDK 或系统能力调用，需要再单独写一层底层包装。底层包装只负责调用runOcr、转换结果和释放资源，不承担页面逻辑。
#include<string>structNativeResult{boolok;intvalue;std::string message;};NativeResultRunOcrScanService(conststd::string&input){if(input.empty()){return{false,0,"empty input"};}intvalue=static_cast<int>(input.size());return{true,value,"runOcr completed"};}这段代码的重点是边界清晰。Native 层不直接返回裸指针、不让页面处理错误码、不把资源释放交给调用方猜测。
9. 命令行验证要给读者路径
文章里的命令不需要多，但要能帮读者定位问题。包管理、构建产物、运行日志是三类最常用证据。
ohpm list--allhvigorw--modemodule-pmodule=entry assembleHap hdc hilog|findstr ocr_engine执行后建议记录三项结果：依赖版本是否符合预期、HAP 是否能构建、示例页触发时是否有明确日志。这样后续换版本时可以直接对比。
10. 常见问题排查
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 页面没有结果 | 服务层吞掉错误或没有刷新状态 | 返回ok/message并展示到示例页 |
| 构建失败 | 版本、路径或 ABI 不一致 | 回到依赖入口核对实际产物 |
| 真机异常 | 权限、沙盒或设备能力不同 | 用真机日志确认失败位置 |
| 升级后行为变化 | 三方库默认参数变化 | 保留示例页作为回归入口 |
排查顺序固定为配置、构建、适配层、页面层。这个顺序能避免一开始就改 UI，最后才发现是依赖版本错了。
11. 验收断言
验收断言把“能看见效果”变成“结果满足契约”。下面的断言可以放在 smoke 流程里，也可以在示例页触发后手动核对。
exportfunctionassertOcrScanServiceReady(result:OcrScanServiceResult):void{if(!result.ok){thrownewError(`OCR识别库适配执行失败:${result.message}`);}if(result.textCount<=0){thrownewError(`textCount 不符合预期:${result.textCount}`);}}这段断言的价值在升级时更明显。只要返回结构或关键指标变了，问题会在验收阶段暴露，而不是等到业务页面上线后才发现。
12. 完成前清单
- 依赖来源、版本和许可证已记录。
- 配置入口、适配层、服务层和页面层职责分开。
- 示例页能重复触发
文字识别。 - 空输入、异常输入和正常输入都有明确结果。
- 命令行验证能定位依赖、构建和日志。
- 常见问题表能覆盖读者最可能遇到的失败。
- 图片、图注和结构说明能帮助读者复现。
这份清单建议每次升级库版本后重新执行。尤其是涉及图片帧和文字识别的场景，不能只看构建是否成功，还要确认页面状态、日志输出和错误兜底都保持一致。
13. 小结
OCR识别库适配的适配重点是把库能力变成项目可维护能力。源码、配置、封装、页面、命令和验收都写清楚，读者才能把文章内容迁移到自己的工程里，而不是只得到一个无法复现的示例。
参考资料
- OpenHarmony 三方库中心仓
- HarmonyOS 开发文档
- HarmonyOS Native 开发与三方库集成 FAQ
参考资料用于核对 API、平台能力和构建链路。正式接入前，应结合当前 SDK、三方库 README、Release 记录和项目权限配置重新确认边界。
