【听见课堂 HarmonyOS NEXT 实战系列 35】OCR 返回空文本怎么办：可恢复错误态而不是伪造结果

OCR 返回空字符串时，最危险的做法不是显示错误，而是为了“让演示继续”自动填入一段预置公式，然后把页面标成识别成功。用户会把示例内容当作真实板书，后续复盘、任务提取和课堂证据都会被污染。

听见课堂把空文本主动抛为错误，P06 保留原图临时预览并允许人工录入；本地示例则通过独立入口和来源标签明确隔离。本文拆解这套恢复路径，并把已有模拟器证据与仍未验证的真图路径分开记录。

一、空字符串也是一种失败

const recognizedText: string = result.value.trim();
if (recognizedText.length === 0) {
  throw new Error('Core Vision OCR returned empty text.');
}

接口成功返回对象不代表业务成功。结果只有空格、换行或空字符串时，没有可交付文字，必须进入错误分支。

二、为什么不能显示“成功 0 字”

“OCR 成功 · 0 字”会让用户怀疑图片丢失，也让测试报表把空结果统计成成功调用。业务成功条件应包含可用非空文本，而不只是 Promise fulfilled。

服务层主动抛错后，页面可以统一进入人工复核状态。

三、页面先保留真实图片上下文

在识别前，页面已经保存：

this.scanImageUri = uri;
this.scanSourceLabel = sourceLabel;

即使 OCR 失败，P06 仍能显示用户刚拍摄或选择的图片。恢复过程以真实输入为依据，不会让用户重新回忆原图内容。

四、失败时清空 ocrText

} catch (error) {
  this.ocrText = '';
  this.scanError = '自动识别未完成，原图仍可在本页临时预览。' +
    '请手动录入文字，或返回重新扫描。';
}

清空文本可以避免上一次识别结果残留到新图片。若继续显示旧公式，用户可能误以为它来自当前照片。

五、错误文案提供两个可执行动作

用户可以在 P06 手工录入，也可以返回 P05 重新拍摄/选图。错误不是终点，而是把自动能力降级为人机协作。

若原图严重模糊，重拍更合适；若只是少量专业符号未识别，人工修正成本更低。

六、本地示例必须走独立入口

useLocalScanDemo() 会加载 Δx = λL / d 或数据库中的示例记录，并把来源设为 P05 本地扫描演示。它不会在 OCR 异常的 catch 中悄悄执行。

这条隔离非常关键：示例用于验证 UI 和保存闭环，不是错误兜底的“假答案”。

七、人工保存仍要校验非空

const normalizedText: string = this.ocrText.trim();
if (normalizedText.length === 0) {
  this.notice = '识别文字不能为空';
  return;
}

OCR 失败后允许人工输入，不代表允许保存空记录。页面在 Repository 写入前再次执行非空校验。

八、来源标签区分自动与人工

保存真实图片时，来源根据 scanError 选择：

source = this.scanError.length > 0 ?
  '人工复核 · ' + sourceBase :
  'Core Vision Kit · ' + sourceBase;

后续课堂回顾能知道这段文字是自动识别后确认，还是自动失败后由用户录入。来源证据比一个模糊的“已扫描”更诚实。

九、成功后也要提示复核

成功分支的状态是“真实图片 OCR 成功，请复核后保存”，不是“已自动保存”。OCR 输出可能有专业名词、公式和上下标错误，用户仍需在 P06 对照原图。

可编辑 TextArea 和原图/对照模式让自动结果始终处于可校正状态。

十、错误类型要在能力层和页面层分工

Service 区分初始化失败、空文本和底层异常；页面统一展示对普通用户可理解的恢复说明。技术日志保留错误细节，UI 不直接暴露堆栈。

若未来需要更精细提示，可定义结构化错误枚举，而不是依赖英文字符串 includes()。

十一、重试不能无限循环

用户可以返回重新选择图片，但系统不应在空结果后自动反复调用 OCR。相同输入和相同条件下无限重试只会增加等待、功耗和资源压力。

更合理的是给出拍摄建议、允许旋转原图、手工输入，并让用户主动决定是否重试。

十二、清晰图片成功路径仍需单独验证

已有模拟器环境没有真实图库图片，因此真实 Core Vision OCR 成功、空结果和异常都没有运行证据。不能因为代码里写了异常分支，就声称它已经在所有设备上通过。

最小补证应包含测试图、返回 URI、识别文字、人工修改、保存后回读和资源释放。

十三、空白图和模糊图是两类测试

空白图验证空结果处理；模糊图可能返回错误文本而不是空字符串。后者更需要用户复核，因为系统看起来“成功”但内容不可靠。

QA 不应只看是否抛错，还要对照人工标注检查内容质量，并避免把一次演示结果写成准确率。

十四、原图不持久化带来的取舍

当前保存后清空 scanImageUri，数据库只保留文字和来源。这符合本地最小数据原则，但也意味着重启后不能继续对照原图。

若未来需要保留原图，必须明确存储位置、生命周期、删除、加密、迁移和用户授权，不能偷偷把临时 URI 写进数据库。

十五、恢复态的无障碍要求

错误文案不能只靠黄色背景；读屏应能朗读“自动识别未完成”和可执行动作。TextArea 要有清晰占位，完成按钮在空文本时应给出可理解反馈。

大字号下还要保证原图、错误卡和输入区可滚动，不让按钮遮住正文。

十六、验收矩阵

输入/故障	期望
清晰板书图	得到非空文字，进入复核，不自动保存
空白图片	进入人工复核，不显示预置公式
损坏或不支持格式	保留可理解错误与重新选图入口
OCR 初始化失败	释放 PixelMap/ImageSource，页面可继续
用户手工输入	非空后保存，来源标记为人工复核
本地示例	明确显示示例来源，不计入真实 OCR

还应验证连续失败后内存稳定、退出页面不回写过期状态、数据库没有图片 URI。

当前能对外怎么描述

可以写：“已实现真实图片 OCR 链路、空结果保护、原图临时预览、人工复核和本地示例降级，契约与构建通过。”

不能写：“真实板书 OCR 已在真机全部通过”或“识别准确率达到某个百分比”，因为当前证据不支持。

总结

一个可信的 OCR 产品不会掩盖空结果，而会保护真实输入、允许人工修正并清楚标记来源。听见课堂已经把示例、自动识别和人工复核分成三种证据等级；下一步仍需用真机清晰图、空白图和异常图补齐运行证据。

下一篇将从 P05 走到 P06，拆解扫描材料、OCR 校对、来源时间与本地保存之间的双页面状态流。

参考：华为 Core Vision 文本识别指南、项目 recognizeText()、recognizeSelectedPhoto() 与扫描 OCR 复验报告。