选图怎么接、PixelMap 怎么喂、识别结果怎么安全过桥——这篇文章记录一个跑在 HarmonyOS 上的 Cordova 插件,以及这三件事在实现里的具体做法。

仓库地址:https://atomgit.com/oh-tpc/cordova-ohos-ocr
版本地址:https://atomgit.com/CPF-Cordova
三方库框架:https://atomgit.com/oh-tpc

0. 环境与实测设备

三方库适配信息:

三方库Cordova 版本鸿蒙化版本仓库地址社区社区地址
cordova-ohos-ocrv14.0.21.0.0(26)https://atomgit.com/oh-tpc/cordova-ohos-ocr(生态收录:https://atomgit.com/oh-tpc)CPF-Cordova 鸿蒙社区https://atomgit.com/CPF-Cordova

说明:本插件以 AtomGit 仓库为分发源,没有发布到 npm registry。cordova plugin add cordova-ohos-ocr 这类裸包名安装不是支持路径,安装方式见第 7 节。

实测环境:

项版本/型号
DevEco Studio内置 SDK(HarmonyOS 26.0.0 / API 26),内置 hvigor 6.26.4
Cordovav14.0.2
cordova-ohos14.0.2(26),CPF-Cordova 鸿蒙社区适配
hcordova CLI1.0.7(HarmonyOS 平台管理,CPF-Cordova 鸿蒙社区提供)
cordova-ohos-ocr 插件1.0.0(本仓库,JS 桥 + ArkTS 原生插件)
构建链Node.js 24.12.0,TypeScript 5.9.3,esbuild 0.25.x
测试Vitest 3.2.7 + jsdom 26.1.0(32 项单测)
实测设备HarmonyOS PC(MateBook Pro S,2in1,HarmonyOS 7.0.0.111)
WebViewArkWeb(Chromium 内核)
权限无(相册 / 文件选择器与 Core Vision Kit 均不需要声明权限)

插件按 HarmonyOS API 12+ 编写(textRecognition.init() 自 API 12 起必须先调),本次在 API 26 上构建、安装、运行。

1. 识别是"假"的:从假演示到真引擎

起因很具体。我在一个 Cordova 应用里需要把图片里的字取出来——用户发来的截图、系统日志、发票照片都行。端侧 OCR 这个系列我已经写过几篇:KMP 走 Kotlin/Native,Flutter 走 MethodChannel,Electron 把设备当外挂引擎。轮到 Cordova,我起手的想法也很自然:WebView 里跑 JS,找个 WASM 的 OCR 库不就行了?

试了一圈,发现这条路成本很高。tesseract.js 能跑,但中文模型体积、首帧时间和识别率都不太体面;更关键的是,把一张 12 MP 的图从相册读进 WebView、再转成 base64 喂给 WASM,光是内存拷贝的开销就已经很大。于是我先做了一个"看起来能用"的演示版:页面内置几张语料(小票、发票、名片),按文件名和大小命中固定结果,再配一个置信度阈值、一个漂亮的耗时数字和一段"识别中"的动画。

这个版本在浏览器里非常唬人:选一张图,进度条走完,右侧出现整齐的文本块,置信度 0.97,耗时 1.2 s。拿它去识别一张真实的系统截图,输出还是那张小票的文案。这个页面从头到尾没有读过图片里的一个像素,只是一套包装过的假数据。

OCR 和玻璃材质不一样。玻璃材质可以在 WebView 里靠 CSS 采样背景实现;文字识别必须由识别引擎完成。鸿蒙把这件事做成了系统能力:Core Vision Kit 的 textRecognition。它在设备本地跑,不联网、不上传、不需要声明权限。插件只负责把系统 OCR 接到 Cordova 的 JS 世界里。

所以这个题目的边界很清楚:一个 JS 桥 + 一个 ArkTS 原生插件,只封装真实能力。具体拆成三件事:

  • 选图:系统相册和系统文件选择器怎么接、取消怎么归一化;
  • 识别:URI 怎么变成 PixelMap、Core Vision Kit 怎么调、资源怎么释放;
  • 过桥:结构化结果怎么从 ArkTS 安全地回到 JS,尤其是那个"不能走字符串通道"的坑。

2. 效果展示

先看效果,再讲原理。Demo 是一个白色基调的页面:标题"文字识别",旁边显示运行环境;右上角一行"端侧处理"。中间一张卡片,标题"从图片中提取文字",右上角是状态徽章,下面是"从相册选择"和"从文件选择"两枚按钮。

把 HAP 装到 HarmonyOS PC 上,打开示例应用 OhosOcrDemo,页面先探测原生能力,状态从"检测中"跳成"可用";选图识别之后,徽章变成绿色,旁边写着"91 个文本块":

在这里插入图片描述

这张图是实际运行截图,不是设计稿。页面头部写着 文字识别,旁边是 HarmonyOS · ArkTS 引擎 · API 26;卡片里的提示是"识别完成,耗时 955 ms。文本由 Core Vision Kit 返回,未经改写。“,预览区标注"相册图片 / 955 ms / 91 个文本块”,下方是识别结果和一枚"复制全文"按钮。

预览区没有缩略图,只有元信息:<img> 读不了 file://media,页面在这里做了降级(见坑八);文字结果一点没少。

识别对象是一张混着系统通知、终端路径和启动日志的图。结果里能直接看到 系统通知可用、ELECTRON、重新体检、复印报告,以及这种把 $、包名、毫秒数混在一起的日志行:

11/13,01:01:41 AM:$ aa start -a EntryAbility -b com.example.ohosfile14 in 238 ms
11/13,01:01:41 AM: Launch com.example.ohosfile14 success in 1 s 752 ms

中文、英文、路径、时间戳、标点都在,没有被"清洗"成一段漂亮话。blocks 是 91 个,fullText 是引擎返回的全文——只有全文为空时,才会用 blocks 拼一份兜底。页面没有置信度、没有高亮框、没有"AI 润色"——置信度 Core Vision Kit 根本不提供,坐标和版面插件也没有透出,我也没有编。

第二个按钮"从文件选择"走的是系统文件选择器,只列图片后缀,返回 file://docs/...;识别链路与相册完全一样,source 会变成"文件图片"。取消选择时两个接口都返回 null,页面只提示"已取消选择",不会弹错误。

环境标签是"浏览器 · 仅预览",状态是"未连接",提示直接写明"当前宿主没有 Cordova 运行时。浏览器只能预览所选图片,文字识别需要 HarmonyOS 宿主。“点按钮只会打开本地文件选择框,选完显示缩略图和"本地预览”,识别结果区域保持隐藏。浏览器预览模式下没有引擎,页面就不显示识别结果,也不返回示例文本。

交互细节也都在:能力探针返回前按钮是 disabled 的;选图期间按钮文案变成"正在打开相册…“,识别期间变成"正在识别…”,结束后恢复;失败时状态变红、hint 显示原生错误原文;成功时"复制全文"可用,点击后短暂变成"已复制";底部"诊断"折叠面板里是 capabilities() 的 JSON,排错时不用开控制台。

3. 文字是怎么被认出来的:一次识别的五道关

写代码之前得先把原理捋好。

一次识别从用户点按钮开始,到页面拿到 fullText 结束,中间要过五道关:

第 0 关:选图。 相册用 photoAccessHelper.PhotoViewPicker,文件用 picker.DocumentViewPicker。两者都返回一个 URI——相册是 file://media/...,文件是 file://docs/...。这一步不需要申请相册或存储权限,因为选择器本身就是系统授权的边界:用户选了哪张,应用才能拿到哪张。

第 1 关:打开。 URI 不能直接喂给 image.createImageSource,得先用 fileIo.openSync(uri, READ_ONLY) 拿到 fd。这个 fd 是原生侧的文件句柄;WebView 里的 <img> 对 file://media 的支持因内核而异,fetch 也受协议和同源限制。把解码交给原生,既绕开 URI 权限,也避免把整张图搬进 JS。

第 2 关:解码成 PixelMap。 image.createImageSource(fd) 建解码器,getImageInfo() 读原始尺寸,必要时等比缩小,再 createPixelMap() 解成 RGBA_8888 的位图。Core Vision Kit 要的是 PixelMap,不是 data URL,也不是 base64。

第 3 关:识别。 textRecognition.init() 初始化引擎,recognizeText({ pixelMap }, { isDirectionDetectionSupported: true }) 返回 value(全文)和 blocks(文本块)。引擎自动判断语言(简中 / 英 / 日 / 韩 / 繁中),我们不做语言参数。

第 4 关:回传。 ArkTS 把结果组装成 { uri, source, fullText, durationMs, blocks },用 successByJson 送回 JS;JS 侧把取消归一化成 null、校验字段、过滤空 block,最后交给页面渲染。

完整链路是这样:

用户点「从相册选择」
      │
      ▼  系统 UI(PhotoViewPicker / DocumentViewPicker)
file://media/... 或 file://docs/...
      │  fileIo.openSync(uri, READ_ONLY) → fd
      ▼
image.createImageSource(fd)
      │  getImageInfo → 长边 > 2560 时等比缩小
      ▼
createPixelMap({ RGBA_8888, desiredSize })
      │
      ▼  textRecognition.init()
textRecognition.recognizeText({ pixelMap }, { isDirectionDetectionSupported: true })
      │  value / blocks
      ▼
successByJson({ uri, source, fullText, durationMs, blocks })
      │  cordova.exec 回调
      ▼
parseImageResult → 页面渲染(全文 + 耗时 + 文本块数)

这条链路里没有网络请求,也没有模型下载。Core Vision Kit 是系统内置能力,识别在设备本地完成;插件不申请任何权限,也不复制图片、不发起网络请求。在其他宿主(Android WebView、iOS WKWebView、浏览器)里,JS 桥仍然可用,但 OhosOcr 服务不存在,所有识别接口都会以 NATIVE_UNAVAILABLE 拒绝——不返回任何示例文本。

也要说清楚能力边界:这套东西给的是"识别文字",不是"理解版面"。插件只把 blocks 里的 text 透出来,没有坐标、字号、段落层级;表格会被拆成若干行,阅读顺序由引擎决定。如果你要的是"还原一张发票的字段结构",得在 fullText 上再做规则或模型,插件不替你做这件事。它适合"把图里的字取出来"(截图、日志、票据、名片),不适合"版式还原"(复杂表格、双栏论文)。

同一个端侧 OCR 需求,不同框架选的路差别很大:

框架识别路径差异
React NativeML Kit / 系统 OCR 原生模块依赖第三方原生模块或自写 bridge
Fluttergoogle_mlkit_text_recognition(ML Kit)模型随插件分发,Android 通常依赖 GMS
KMPKotlin/Native 或 expect/actual需要自己接系统 OCR 与 ArkTS 桥
Cordova(本库)ArkTS 插件 + Core Vision Kit系统能力,零模型体积、零权限
Ionic / CapacitorCapacitor ML Kit 插件经 Capacitor 桥,路径同 Cordova
Electrontesseract.js / OS OCRWASM 模型,CPU 推理,包体大
纯 WebWASM OCR(tesseract.js 等)受 WebView 内存与算力限制

再记一下性能数据:截图里 955 ms 是整条链路的耗时——init、打开文件、解码、识别、整理 blocks 全算在内,不是单帧渲染时间。耗时主要在引擎初始化和大图解码两件事上。前者每次调用做一次、结束 release();后者用长边上限 2560 把峰值压住。12 MP 的图(4000×3000)在 RGBA_8888 下是 4000×3000×4 ≈ 48 MB,缩到长边 2560 后是 2560×1920×4 ≈ 20 MB,少了一半多。91 个文本块的图能在一秒内返回,这个量级在 2in1 上很从容。

还有一个容易忽略的成本:拷贝。如果让 JS 把图片读成 base64 再传给原生,同一张图会在 WebView 堆、字符串、原生解码器里各存一份,内存翻倍、GC 压力也翻倍。我们全程只传 URI 和 fd,图片字节一次都不进 JS。

4. 工程怎么搭:一个插件,两份代码,三种产物

先看整体结构。Demo 跑通之后,我把它整理成了标准的 Cordova 插件:根目录是可复用的 package(com.lqjmac.cordova.ohosocr),演示应用退到 example/,浏览器演示留在 demo/。

cordova-ohos-ocr/                      # 插件根目录(plugin.xml,v1.0.0)
├─ src/                                # TypeScript 桥接(纯浏览器 JS)
│  ├─ native.ts                        # exec 封装、能力探针、错误码、超时
│  ├─ ocr.ts                           # 选图 / 识别的高层 API
│  ├─ image.ts                         # 识别载荷校验与 JSON 序列化
│  ├─ version.ts                       # 版本号(与 package.json 同步)
│  └─ index.ts                         # window.OhosOcr 的公共对象
├─ www/ohos-ocr.js                     # esbuild 产物,Cordova 直接加载
├─ types/                              # tsc 生成的 .d.ts
├─ ohos/                               # ArkTS 原生插件
│  ├─ OhosOcrPlugin.ets                # 动作分发、错误回传
│  └─ OcrImage.ets                     # 选择器、PixelMap、Core Vision Kit
├─ __tests__/                          # Vitest(jsdom),32 项
├─ demo/                               # 浏览器直开演示(与宿主共用 CSS/JS)
├─ example/                            # Cordova-OHOS 宿主
│  ├─ config.xml                       # com.lqjmac.ohosocr.host
│  ├─ www/                             # 由 demo/ 同步而来
│  └─ harmonyos/                       # hcordova 生成的 ArkTS 工程
├─ docs/                               # 架构、验证记录、安装校验、截图
├─ scripts/                            # build / sync-example / screenshot
├─ plugin.xml                          # js-module + ohos source-file + feature
└─ README.OpenHarmony.md / README.OpenHarmony_CN.md

在这里插入图片描述

这次整理做的主要是把演示版拆成可复用的插件结构:

  • src/ 只依赖标准 Web API 和 cordova.exec,不依赖任何宿主全局;native.ts 管探针和超时,ocr.ts 管选图与识别,image.ts 管载荷,三件事不搅在一起;
  • ohos/ 是两个纯 ArkTS 文件,只依赖系统 Kit 和 @cordova-ohos/ohos,不碰页面;选择器、解码、识别、释放都在这一层闭环;
  • www/ohos-ocr.js 是唯一 JS 交付物,tsc --noEmit + esbuild 一条命令产出,产物里没有 CSS、没有模板、没有运行时依赖;产物随仓库提交,hcordova plugin add 后无需再构建;
  • demo/ 与 example/www/ 共用 CSS/JS,npm run sync:example 只改一个 <link> 和两个 <script> 的引用,避免三份页面各改各的。

和纯 JS 插件不同,这次有两份代码、三种产物:JS 桥(www/ohos-ocr.js)、类型声明(types/*.d.ts)、被拷贝进宿主 entry 模块的 ArkTS(ohos/*.ets)。插件清单里三样都要声明:

<!-- plugin.xml(节选) -->
<js-module src="www/ohos-ocr.js" name="OhosOcr">
    <clobbers target="OhosOcr" />
</js-module>

<platform name="ohos">
    <js-module src="www/ohos-ocr.js" name="OhosOcr">
        <clobbers target="OhosOcr" />
    </js-module>

    <source-file type="ets" src="ohos/OcrImage.ets"
        target-dir="src/main/ets/plugins/ohosocr" modules-name="entry" />
    <source-file type="ets" src="ohos/OhosOcrPlugin.ets"
        target-dir="src/main/ets/plugins/ohosocr" modules-name="entry" />

    <config-file target="src/main/resources/rawfile/config.xml" parent="/*">
        <feature name="OhosOcr">
            <param name="ohos-package"
                value="entry/src/main/ets/plugins/ohosocr/OhosOcrPlugin.ets" />
        </feature>
    </config-file>
</platform>

hcordova plugin add 时,安装器做三件事:把 www/ohos-ocr.js 用 cordova.define(...) 包一层,拷进 rawfile/www/plugins/cordova-ohos-ocr/,并更新 cordova_plugins.js;把两个 .ets 拷进 entry/src/main/ets/plugins/ohosocr/;往 rawfile/config.xml 插入 <feature name="OhosOcr">。modules-name="entry" 假定宿主模块名是 entry,工程不同要改成实际模块名。

但还有一步自动化不了:ArkTS 插件是按 webview 注册的,必须在宿主的 Index.ets 里显式把插件对象交给 MainPage:

// entry/src/main/ets/pages/Index.ets(节选)
import { MainPage, PluginEntry, pageBackPress, pageHideEvent, pageShowEvent } from '@cordova-ohos/ohos/Index';
import { OhosOcrPlugin } from '../plugins/ohosocr/OhosOcrPlugin';

@Entry
@Component
struct Index {
  cordovaPlugs: Array<PluginEntry> = [
    { pluginName: 'OhosOcr', pluginObject: new OhosOcrPlugin() }
  ];

  onPageShow() {
    pageShowEvent();          // 页面显示通知 cordova
  }

  onBackPress() {
    pageBackPress();          // 返回键交给 cordova 处理
    return true;
  }

  onPageHide() {
    pageHideEvent();          // 页面隐藏通知 cordova
  }

  build() {
    RelativeContainer() {
      MainPage({ cordovaPlugs: this.cordovaPlugs });
    }
    .height('100%')
    .width('100%')
  }
}

三个生命周期回调与 OCR 无关,是 Cordova 宿主的要求:页面显示/隐藏要通知 cordova,返回键由它处理;5.6 还会展开返回键这一条。

pluginName 必须和 <feature name="OhosOcr"> 一模一样,否则 cordova.exec 会报 Class not found。宿主链路长这样:

Cordova-OHOS 宿主(ArkUI EntryAbility)
  └─ ArkWeb WebView(Chromium 内核)
      ├─ cordova.js + cordova_plugins.js            ← 平台框架注入
      ├─ plugins/cordova-ohos-ocr/www/ohos-ocr.js  ← 安装时拷入 rawfile
      └─ window.OhosOcr                              ← js-module clobber 到 window
          ├─ capabilities() → cordova.exec('OhosOcr', 'engineInfo')
          └─ recognizeImage(uri)
              └─ ArkTS OhosOcrPlugin → OcrImage → Core Vision Kit

对使用方来说,最终看到的 API 是这样的:

document.addEventListener('deviceready', async () => {
  const capabilities = await window.OhosOcr.capabilities();
  if (!capabilities.native) {
    console.warn(capabilities.detail);   // 浏览器 / 未注册插件
    return;
  }

  const uri = await window.OhosOcr.pickImage();   // 取消 → null
  if (uri !== null) {
    const result = await window.OhosOcr.recognizeImage(uri);
    console.log(result.fullText, result.blocks.length, result.durationMs);
  }
});

注意这里没有任何"演示结果"分支:native 为 false 时,页面唯一正确的做法是把原因显示出来。这段只是 API 演示;实际页面启动走 5.6 的 cordova/channel 写法,避开 deviceready 的粘性竞态。

构建侧也做了双挂载。scripts/build.mjs 用 esbuild 把 src/index.ts 打成单文件 IIFE,footer 同时写 module.exports 和 window.OhosOcr:

// scripts/build.mjs - footer(节选)
var __OhosOcr__ = OhosOcrBundle.OhosOcr;
if (typeof module !== "undefined" && module.exports) { module.exports = __OhosOcr__; }
if (typeof window !== "undefined") { window.OhosOcr = __OhosOcr__; }

Cordova 的 cordova.define 包装走 module.exports,浏览器直开 demo/index.html 走 window 挂载——同一份产物两条路都能用。这也意味着 demo/ 不需要 Cordova 运行时就能验证页面本身,只是识别请求会明确返回不可用。

5. 把代码讲透

下面把插件内部拆开讲:两个选择器、一段解码、一次识别、一层 exec 桥、一份载荷,再加上宿主的接线。

5.1 选图:两个系统选择器,一条归一化路径

OcrImage.ets 里,相册选择器只有十几行:

// ohos/OcrImage.ets - pickImage()
const options: photoAccessHelper.PhotoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
options.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
options.maxSelectNumber = 1;
const photoPicker: photoAccessHelper.PhotoViewPicker = new photoAccessHelper.PhotoViewPicker();
const result: photoAccessHelper.PhotoSelectResult = await photoPicker.select(options);
if (result.photoUris.length === 0) {
  return '';                       // 用户取消
}
return result.photoUris[0];

文件选择器多了一个细节——把 UIAbility context 显式传进去:

// ohos/OcrImage.ets - pickImageFile()
const options: picker.DocumentSelectOptions = new picker.DocumentSelectOptions();
options.maxSelectNumber = 1;
options.fileSuffixFilters = [
  '.png', '.jpg', '.jpeg', '.bmp', '.webp', '.heic', '.gif',
];
let documentPicker: picker.DocumentViewPicker;
if (context !== undefined) {
  documentPicker = new picker.DocumentViewPicker(context);
} else {
  documentPicker = new picker.DocumentViewPicker();
}
const uris: string[] = await documentPicker.select(options);
if (uris.length === 0) {
  return '';
}
return uris[0];

DocumentViewPicker 有无参构造,但它需要在页面栈里找一个 UI 上下文;插件在 Cordova 的 webview 里被调用,创建时机不在页面栈顶,无参构造偶尔会拿不到 context,picker 干脆不弹。把 cordovaWebView.getUIContext().getHostContext() 传进去就稳了(见坑六)。

取消的处理放在 JS 侧:原生返回空串,src/ocr.ts 的 readUri 把它读出来,pickImage 再归一化成 null——调用方只需要判断 null,不用理解空串的约定。选图的超时也单独放宽到 120 秒,因为用户完全可能在相册里翻很久。

5.2 解码:从 URI 到 PixelMap,控制峰值内存

识别前必须把图片解成 PixelMap。这一段是整个原生侧最需要小心的地方:

// ohos/OcrImage.ets - recognizeImage()(节选)
file = fs.openSync(uri, fs.OpenMode.READ_ONLY);
source = image.createImageSource(file.fd);

const info: image.ImageInfo = await source.getImageInfo();
const longest: number = Math.max(info.size.width, info.size.height);
const scale: number = longest > MAX_EDGE_PX ? MAX_EDGE_PX / longest : 1;
const targetSize: image.Size = {
  width: Math.max(1, Math.round(info.size.width * scale)),
  height: Math.max(1, Math.round(info.size.height * scale)),
};

const decodingOptions: image.DecodingOptions = {
  editable: true,
  desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
  desiredSize: targetSize,
};
pixelMap = await source.createPixelMap(decodingOptions);

三个决定单独说:

先读尺寸再解码。 getImageInfo() 只读元数据,不分配位图;拿到宽高之后才决定 desiredSize。如果先按原图解码再缩放,12 MP 的图会先吃掉 48 MB,缩放只是把峰值推迟,不是消除。

长边 2560 是刻意的。 再大的长边对识别精度的收益有限,但 RGBA_8888 的内存是像素数×4。2560 长边的 4:3 图是 2560×1920×4 ≈ 20 MB,12 MP 原图是 4000×3000×4 ≈ 48 MB。识别精度几乎不变,峰值少一半多。

editable: true + RGBA_8888。 editable 让解码器返回可写位图,RGBA_8888 是识别接口期望的像素格式。两个都写死,避免不同解码器给出只读或压缩格式时,问题拖到 recognizeText 里才炸。

5.3 识别:init、recognizeText、finally 里的释放

引擎调用本身很短,难的是生命周期:

// ohos/OcrImage.ets - recognizeImage()(节选)
initialized = await textRecognition.init();
if (!initialized) {
  throw new Error('OCR engine initialization failed');
}

const visionInfo: textRecognition.VisionInfo = { pixelMap };
const configuration: textRecognition.TextRecognitionConfiguration = {
  isDirectionDetectionSupported: true,
};
const recognized: textRecognition.TextRecognitionResult =
  await textRecognition.recognizeText(visionInfo, configuration);

const blocks: OcrImageBlock[] = [];
for (let index = 0; index < recognized.blocks.length; index += 1) {
  const value: string = recognized.blocks[index].value;
  if (value.trim().length > 0) {
    blocks.push({ text: value });
  }
}
let fullText: string = recognized.value;
if (fullText.length === 0) {
  const lines: string[] = [];
  for (let index = 0; index < blocks.length; index += 1) {
    lines.push(blocks[index].text);
  }
  fullText = lines.join('\n');
}

return {
  uri,
  source: uri.startsWith('file://media') ? '相册图片'
        : uri.startsWith('file://docs') ? '文件图片' : '图片',
  fullText,
  durationMs: Date.now() - startedAt,
  blocks,
};

几个关键细节:

init() 自 API 12 起必须先调。 不调直接 recognizeText,拿到的是引擎未初始化的报错;调用完必须 release(),否则引擎资源会一直占着。

finally 的释放顺序是反的。 pixelMap.release() → source.release() → fs.closeSync(file) → textRecognition.release();先释放依赖方,再释放被依赖的资源。textRecognition.release() 单独包了 try/catch,避免释放失败盖住识别错误——用户该看到的是"识别失败",不是"释放失败"。

fullText 为空时用 blocks 拼。 引擎偶尔返回文本块但 value 为空(比如纯符号图),这时用 join('\n') 兜底;blocks 里的空块会被过滤,避免页面出现一堆空行。

source 由 URI 前缀决定。 file://media 是相册,file://docs 是文件选择器,其余归为"图片"。这个字段只是给 UI 展示,不参与识别。

耗时 durationMs 从 startedAt 开始,覆盖 init、解码、识别、整理 blocks 全过程,不是只算 recognizeText。这样页面上的数字才是用户实际等待的时间。

5.4 过桥:一次且仅一次

src/native.ts 的 execNative 很短,但把 Cordova exec 的三个坑都堵上了:回调可能不来、可能来两次、宿主可能根本没有服务。

// src/native.ts - execNative()
export function execNative(action: string, args: unknown[], timeoutMs: number): Promise<unknown> {
  return new Promise<unknown>((resolve, reject) => {
    const cordova = getCordova();
    if (cordova === null) {
      reject(new OhosOcrError('NATIVE_UNAVAILABLE', NO_CORDOVA));
      return;
    }

    let settled = false;
    const timer = setTimeout(() => {
      if (settled) return;
      settled = true;
      reject(new OhosOcrError('NATIVE_TIMEOUT', `OhosOcr.${action} 超时(${timeoutMs} ms)`));
    }, timeoutMs);

    const succeed = (message: unknown): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      resolve(message);
    };
    const fail = (message: unknown): void => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      reject(new OhosOcrError('NATIVE_ERROR', asFailure(message)));
    };

    try {
      cordova.exec(succeed, fail, SERVICE, action, args);
    } catch (error) {
      fail(error instanceof Error ? error.message : error);
    }
  });
}

settled 是核心:原生回调、超时、同步异常三条路径只能命中一条,Promise 不会先 resolve 再 reject。

超时按场景分成四个值:

场景超时理由
能力探针 engineInfo1.5 s探针只回答"在不在",不该让页面等
通用动作兜底5 sTIMEOUTS.call 的预留值,当前四个动作各自用了更具体的超时
选图 pickImage / pickFile120 s用户可能在相册里翻很久
识别 recognizeImage60 s大图 + 首次 init 可能慢,但不能无限等

能力探针还有一个缓存策略:成功一次就记住;失败后 3 秒内不重复探测,3 秒后允许重探。原因是页面脚本可能早于 deviceready 调用 capabilities()——第一次探针失败,不代表插件没装,可能只是 Cordova 还没 ready。3 秒窗口既避免疯狂重试,又给晚注入的原生插件留了一次机会。

// src/native.ts - probeNative()
if (!force && state === 'ok') {
  return Promise.resolve(true);
}
if (!force && state === 'unavailable' && Date.now() - failedAt < REPROBE_MS) {
  return Promise.resolve(false);
}
if (pendingProbe !== null) {
  return pendingProbe;          // 并发调用共用同一次探针
}

pendingProbe 是并发去重:页面启动时 capabilities() 可能被调两次(deviceready 一次、3 秒兜底一次),两次都发 engineInfo 没必要。

错误码收敛成五个:NATIVE_UNAVAILABLE(没有 Cordova 或服务未注册)、NATIVE_TIMEOUT、NATIVE_ERROR(原生失败)、INVALID_ARGUMENT(空 URI)、INVALID_PAYLOAD(载荷格式不对)。调用方可以按 code 分流、按 message 展示。

四个原生动作就是桥的全部约定:

动作参数成功载荷
engineInfo—{ platform, engine, bridge, coreVision, apiVersion }
pickImage—{ uri },取消时为空串
pickFile—{ uri },取消时为空串
recognizeImageuri{ uri, source, fullText, durationMs, blocks }

5.5 载荷:为什么这里必须用 successByJson

这是整个插件里最容易忽略、也最容易出错的一处。Cordova-OHOS 的 EVAL 桥把字符串结果拼进 JavaScript 源码时不做转义:

// NativeToJsMessageQueue.h(EVAL 桥,节选)
case PluginResult::MESSAGE_TYPE_STRING:
    sb += "'";
    sb += m_pluginResult.getMessage();   // 原样拼进 JS 源码
    sb += "'";

后果是:识别结果里的 \n 在 JS 源码里变成真正的换行,JSON.parse 直接失败;文本里出现 ' 时会把单引号字符串截断,后面的代码全乱。第一版用 successByString(JSON.stringify(result)),页面只拿到半截文本,控制台报 Unexpected token(或同类的 JSON 解析错误)。

修复分两层。原生侧所有结构化结果走 successByJson / errorByJson:

// ohos/OhosOcrPlugin.ets
callbackContext.successByJson(imageResultPayload(result));
callbackContext.errorByJson({ message: describeError(error) });

successByJson 让桥把对象序列化成 JSON、走 JSON 通道,换行和引号由序列化器处理,不会再拼进字符串字面量。

JS 侧仍然接受对象和 JSON 字符串两种输入——其他宿主、测试替身可能给字符串——但只做校验,不做猜测:

// src/image.ts - parseImageResult()
const record = toRecord(payload, '识别结果');
const source = typeof record.source === 'string' ? record.source : '';
// ... uri / fullText / durationMs ...
const rawBlocks = Array.isArray(record.blocks) ? record.blocks : [];
const blocks: OcrImageBlock[] = [];
for (const block of rawBlocks) {
  if (block !== null && typeof block === 'object') {
    const text = (block as Record<string, unknown>).text;
    if (typeof text === 'string' && text.trim().length > 0) {
      blocks.push({ text });
    }
  }
}
if (source.length === 0) {
  throw new OhosOcrError('INVALID_PAYLOAD', '识别结果缺少 source 字段');
}
return { uri, source, fullText, durationMs, blocks };

source 是必填的:没有来源标签的结果无法解释给用户,宁可报 INVALID_PAYLOAD 也不渲染一个来路不明的文本块。

插件还带了一个 imageResultToJson(),手写 JSON 转义("、\、\n、\r、\t、控制字符),供需要把结果落盘或转发的调用方使用。它的输出格式是固定的,测试里有一条精确字符串断言。

测试也记一下:__tests__/image.test.ts 的 7 项覆盖对象 / JSON 字符串、空识别、非法载荷、block 过滤、精确序列化、引号 / 反斜杠 / 控制字符转义。这类"字符串边界"的 bug,只有测试能覆盖。

5.6 接线与页面启动:粘性 deviceready 和 3 秒兜底

宿主侧除了 Index.ets 的注册,还有一个容易踩的点:deviceready 是粘性事件。如果页面脚本在它触发之后才执行,document.addEventListener('deviceready', ...) 永远收不到——事件已经过去了。表现是按钮一直是灰的,页面永远停在"正在检测运行环境"。

正确做法是订阅 cordova/channel 的 onDeviceReady,它在事件已经触发时会立即回调:

// demo/app.js(节选,略去缩进整理)
if (!window.cordova) {
  start(false);                       // 浏览器:直接启动,capabilities() 会说明没有引擎
} else {
  var subscribed = false;
  try {
    var channel = window.cordova.require && window.cordova.require('cordova/channel');
    if (channel && channel.onDeviceReady) {
      channel.onDeviceReady.subscribe(function () {
        start(true);                  // 强制重探:插件可能刚注入
      });
      subscribed = true;
    }
  } catch (error) {
    subscribed = false;
  }
  if (!subscribed) {
    document.addEventListener('deviceready', function () { start(true); }, false);
  }

  // 兜底:即使 deviceready 没来,3 秒后也启动一次;
  // capabilities() 会解释原生为什么不可用。
  window.setTimeout(function () {
    start(false);
  }, 3000);
}

start(true) 会强制重探(capabilities(true)),因为第一次可能探在插件注入之前;3 秒兜底用普通探针,避免重复请求。这个设计覆盖两种情况:宿主里走真实识别,浏览器里显示"未连接"。

系统返回键也走宿主:Index.ets 的 onBackPress 调 pageBackPress() 并返回 true,返回键由 Cordova 处理。OCR 页面没有需要单独拦截的浮层,按返回键就是正常的回退/退出;但这一步不做,ArkWeb 里的页面导航会收不到系统返回键。

页面本身只依赖 window.OhosOcr 的公共 API,不关心原生/JS 分支;sync-example 脚本(npm run sync:example)把 demo/index.html 的 CSS 和脚本引用改写成宿主版本(cordova.js + js/app.js),CSS/JS 原样复制。同一份页面,两种加载方式,不维护第二套代码。

6. 踩坑与经验

这一节的坑全部来自这次开发的真实报错和排查记录。

坑一:successByString 回传 JSON,页面只拿到半截文本。 第一版在 ArkTS 里 callbackContext.successByString(JSON.stringify(payload)),返回的 JSON 带 \n。桥把字符串原样拼进 cordova.callbackFromNative(...) 的 JS 源码,\n 变成真正的换行,JSON.parse 直接抛 Unexpected token;换一张带 ' 的图,单引号把语句截断,回调根本没跑完。修复:所有结构化结果改 successByJson,JS 侧同时兼容对象与字符串。教训:在 Cordova-OHOS 上,JSON 只能走 JSON 通道,不能塞进字符串通道。

坑二:手动拷 ohos-ocr.js,页面报 Module cordova-ohos-ocr.OhosOcr does not exist。 改完插件后我图省事,直接把新的 www/ohos-ocr.js 覆盖到 rawfile/www/plugins/...,结果运行时找不到模块。原因是 hcordova 安装时会用 cordova.define("cordova-ohos-ocr.OhosOcr", ...) 包一层,手工拷贝把包装层丢了。更隐蔽的是:hcordova 的 js-module 安装器发现目标文件已存在时只打印 warning,不覆盖,所以你重装插件也可能拿到旧文件。修复:删掉 rawfile/www/plugins/<插件目录> 和 cordova_plugins.js,重新 hcordova plugin add。教训:插件 JS 永远让安装器生成,不要手写进 rawfile。

坑三:deviceready 错过了,按钮一直灰。 页面在浏览器里好好的,装进模拟器后按钮始终 disabled,状态停在"检测中"。日志里 deviceready 已经触发过——页面脚本执行得晚,addEventListener 注册时事件已经过去了。修复:改用 cordova/channel 的 onDeviceReady.subscribe,并加 3 秒兜底启动(见 5.6)。教训:Cordova 的 deviceready 是粘性的,晚订阅要用 channel,不是 addEventListener。

坑四:模拟器上 textRecognition.init() 超时。 页面能加载,capabilities() 返回原生可用,相册也能拉起,但一识别就报:

[init] Run timed out, please try again later.

失败发生在 init(),还没读到文件。把图片放到 /data/local/tmp 用绝对路径再试,还是同一处;同一台模拟器上另一个 Core Vision Kit 示例也报同样的错,并提示"模拟器通常不支持端侧 OCR,请改用真机"。换到 HarmonyOS PC 后一次通过。教训:模拟器没有识别引擎是环境限制,不是接线问题;插件应该把原生错误原文透出来,而不是换一句"识别失败"。

坑五:真机拒 unsigned HAP。 模拟器上 hdc install 一个未签名 HAP 直接就装上了;换 HarmonyOS PC 后报 no signature file,用 SDK 的 OpenHarmony 测试证书自签又报 fail to verify pkcs7 file。最后在 DevEco 里打开 example/harmonyos,开启自动签名,重新 assembleHap,产出 entry-default-signed.hap 才装上;第 2 节那张 91 个文本块的截图,就是这次签名后跑出来的。签名材料与 bundleName、设备 UDID 绑定,换设备要重签。教训:模拟器不校验签名,不代表真机不校验;CLI 构建的 unsigned HAP 只能用于允许的模拟器。

坑六:DocumentViewPicker 偶发不弹。 相册选择器一直正常,文件选择器偶尔点了没反应。排查发现无参构造的 DocumentViewPicker 需要在页面栈里找 UI 上下文,而插件是在 webview 里被调用的,时机不在栈顶。修复:从 cordovaWebView.getUIContext().getHostContext() 取到 UIAbility context,显式传给 picker 构造函数。教训:系统选择器不是纯函数,它需要一个 UI 上下文;在插件里拿上下文要经过 webview。

坑七:12 MP 的图,RGBA_8888 峰值约 48 MB。 一开始直接按原图 createPixelMap,大图识别时内存曲线陡增,低端设备上偶发 GC 卡顿。修复:getImageInfo() 后先算缩放,长边超过 2560 才缩,desiredSize 直接给解码器,避免"先解大图再缩"。教训:图片处理的内存要按"像素数×4"算,并且在解码前算好上限,不是解码后补救。

坑八:<img> 读不了 file://media,缩略图是空的。 识别结果正常,但预览图偶尔不显示——部分 WebView 不允许 <img> 直接加载 file://media URI。修复:onerror 时把图片 hidden,只保留识别文字和元信息;结果本身不受影响。教训:预览失败不应该影响识别结果,两者要能独立失败。

7. 现在怎么用:从 三方库 到依赖

经过上面的整理,这个工程现在是一个标准的 Cordova 插件(包名 com.lqjmac.cordova.ohosocr,版本 1.0.0),演示应用在 example/。插件以 AtomGit 仓库为分发源,没有发布到 npm registry——请从仓库地址安装:

# Cordova CLI(git 地址)
cordova plugin add https://atomgit.com/oh-tpc/cordova-ohos-ocr.git

# hcordova(HarmonyOS 宿主,git 地址)
hcordova plugin add https://atomgit.com/oh-tpc/cordova-ohos-ocr.git

# 或本地路径开发(克隆后;不要带尾部斜杠)
hcordova plugin add ../cordova-ohos-ocr

安装之后还有两步:在 Index.ets 的 cordovaPlugs 里注册 OhosOcr(见第 4 节),以及用 DevEco 自动签名构建真机 HAP。接入代码在第 4 节已经给过,核心就是 capabilities() + pickImage() + recognizeImage()。

API 全表在仓库的 仓库说明里,这里只列最常用的:

接口说明
version插件版本,与 package.json 一致
capabilities(force?){ native, engine, detail, info };force 跳过 3 秒失败缓存
isNativeAvailable()同步缓存值
requireNative()原生不可用时 reject,用于启动自检
pickImage() / pickImageFile()系统相册 / 文件选择器;取消返回 null
recognizeImage(uri)返回 { uri, source, fullText, durationMs, blocks }
recognizeFromGallery() / recognizeFromFile()选图 + 识别一步完成
imageResultToJson(result)精确序列化

当前版本在 Cordova v14.0.2 / cordova-ohos 14.0.2 基线上验证:npm run verify 全绿——tsc --noEmit、esbuild 产物、types/ 生成、32 项 Vitest 全部通过。npm pack --dry-run 产出 20 个文件、187.1 kB 包体(解包 267.0 kB),只含 www、types、ohos、plugin.xml、三个 README、变更记录、LICENSE 与文档目录。

浏览器运行时里,capabilities() 返回 native: false,选图 / 识别全部以 NATIVE_UNAVAILABLE 拒绝,没有返回任何示例文本:

{
  "loaded": true,
  "version": "1.0.0",
  "native": false,
  "engine": "none",
  "pick": { "code": "NATIVE_UNAVAILABLE", "message": "Missing Command Error" },
  "recognize": { "code": "NATIVE_UNAVAILABLE", "message": "Missing Command Error" },
  "hasDemoApi": []
}

API 26 模拟器上,相册选择器能拉起,但 textRecognition.init() 超时;HarmonyOS PC(MateBook Pro S)上,用 DevEco 自动签名的 HAP 安装后,真实识别跑通——就是第 2 节那张 91 个文本块、955 ms 的截图。ArkTS 构建只报 Function may throw exceptions. Special handling is required. 级别的系统调用提示,没有错误。

更完整的资料在仓库里:

  • 英文,完整 API、兼容性约束和模拟器运行流程;
  • 中文,内容与英文版对应;
  • example/:Cordova-OHOS 宿主,含从 hcordova plugin add 到 hdc install 的完整步骤;
  • __tests__/:32 项 Vitest(jsdom),覆盖载荷、exec 桥、探针缓存、插件清单和"构建产物不含演示语料";
  • 分层、时序和两个桥接坑;
  • 构建、安装与验证记录。

最后留一句边界:这个插件解决的是"把图里的字取出来",不解决"把字排回去"。它没有坐标、没有版面、没有表格结构,也没有云端模型;它用的是系统自带的 Core Vision Kit,所以零权限、零模型体积、零网络。需要结构化字段,就在 fullText 上继续做;需要更复杂的版面理解,就换更重的引擎。这些边界也是当前版本的实际范围。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐