Cordova 鸿蒙端侧 OCR 实战:让图片里的字“走进“WebView
选图怎么接、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-ocr | v14.0.2 | 1.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 |
| Cordova | v14.0.2 |
| cordova-ohos | 14.0.2(26),CPF-Cordova 鸿蒙社区适配 |
| hcordova CLI | 1.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) |
| WebView | ArkWeb(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 Native | ML Kit / 系统 OCR 原生模块 | 依赖第三方原生模块或自写 bridge |
| Flutter | google_mlkit_text_recognition(ML Kit) | 模型随插件分发,Android 通常依赖 GMS |
| KMP | Kotlin/Native 或 expect/actual | 需要自己接系统 OCR 与 ArkTS 桥 |
| Cordova(本库) | ArkTS 插件 + Core Vision Kit | 系统能力,零模型体积、零权限 |
| Ionic / Capacitor | Capacitor ML Kit 插件 | 经 Capacitor 桥,路径同 Cordova |
| Electron | tesseract.js / OS OCR | WASM 模型,CPU 推理,包体大 |
| 纯 Web | WASM 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。
超时按场景分成四个值:
| 场景 | 超时 | 理由 |
|---|---|---|
能力探针 engineInfo | 1.5 s | 探针只回答"在不在",不该让页面等 |
| 通用动作兜底 | 5 s | TIMEOUTS.call 的预留值,当前四个动作各自用了更具体的超时 |
选图 pickImage / pickFile | 120 s | 用户可能在相册里翻很久 |
识别 recognizeImage | 60 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 },取消时为空串 |
recognizeImage | uri | { 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 上继续做;需要更复杂的版面理解,就换更重的引擎。这些边界也是当前版本的实际范围。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)