React Native 鸿蒙端侧文档扫描实战:把一张照片拆成纸和字
纸怎么从背景里被找出来、阴影怎么被抹平、二值化后的画面怎么还能被认出来——这篇文章用一个跑在鸿蒙真机上的 React Native 0.84 三方库,把端侧文档扫描这条管线一次讲透。
仓库地址:https://atomgit.com/oh-react-native/react-native-ohos-ocr
版本地址:https://atomgit.com/oh-react-native/ohos_react_native/tree/0.84-main
三方库框架:https://atomgit.com/oh-react-native
0. 环境与实测设备
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | <DevEco Studio 安装目录>(HarmonyOS SDK 26.0.0 / API 26) |
| React Native | 0.84.1 |
| React | 19.2.3(与 RN 0.84.1 内置 renderer 严格同版) |
| RNOH | @react-native-oh/react-native-harmony 0.84.3;OHPM @rnoh/react-native-openharmony 0.84.3 |
| 语言与构建 | TypeScript 5.9.3、Babel 7、Jest 29.7、Node.js 24.12.0 / npm 11.12.1 |
| 鸿蒙 SDK | 编译/目标 26.0.0(API 26);示例 compatibleSdkVersion 5.0.5(17) |
| hvigor | DevEco Studio 自带(HVIGOR_JS 可覆盖) |
| react-native-ohos-ocr | 0.2.0(本仓库,npm 包 + source-style HAR) |
| 实测设备 | HUAWEI ALN-AL00,HarmonyOS 7.0.0.109(API 26) |
| 端侧引擎 | HarmonyOS Core Vision Kit:subjectSegmentation + textRecognition(全离线) |
1. 从文字识别到文档扫描
这个库的第一版已经能识别字了。流程很直白:PhotoViewPicker 选一张相册图,textRecognition 跑一遍,把 21 个文本块和耗时交回 JS。真机上差不多 1.5 秒,图片没离开过设备,验收记录里写着 nativeBridge: OK。按说这事就完了。
但拿去拍一张放在桌上的文档时,回来的是这样的结果:
- 字是有的,一行一行,顺序也对;
- 图是没的。你拿到的是一张带桌面、带阴影、带手边杂物、还可能拍歪了的照片;
- 识别结果里混进了背景上的文字,正文段落因为阴影压暗,漏了几行。
用户要的是"扫描件":一块干净的纸、白底黑字、能存能发、最好还能直接复制文字。文字识别和扫描件在系统能力里是分开的——textRecognition 只负责字,不负责把纸变干净。
我一开始想走捷径:Vision Kit 不是有 DocumentScanner 吗?直接调它,页面和交互由系统提供,结果拿回来就行。翻文档才发现这条路根本不通:DocumentScanner 是一个 ArkUI 组件,要挂在一个页面栈里、由用户点快门、在界面里完成裁剪确认。而 TurboModule 的调用发生在 RN 的 JS 线程,原生侧没有可以承载它的 ArkUI 页面。TurboModule 没有界面,调不了需要界面承载的组件。
于是只剩一条路:把"扫描"拆成像素操作,自己在原生侧做完。
- 纸怎么找:
subjectSegmentation把画面里的主体分割出来,拿到掩码和包围盒; - 像怎么变干净:裁出纸、用掩码把纸外压成白色、抹平光照、Otsu 二值化;
- 字怎么回:把增强后的
PixelMap直接喂给textRecognition,让扫描件和文字来自同一份像素; - 包怎么交付:六个方法的 TurboModule、source-style HAR、RNOH autolinking,以及一个能跑的示例宿主。
这四个问题决定了后面的实现。下面是实现完成后的记录,包括我踩过的坑。
2. 效果展示
先看效果,再讲原理。示例页只保留一条主线:选一张照片 → 一次原生调用 → 扫描件 + 文字 + 耗时。
截图为文档扫描页:上半部分是「拍摄原图 1080×1151」,下半部分是「扫描结果」,状态行写着「已定位纸张」:

原图是一张新闻稿网页的截图:标题、日期、三行带箭头的要点、多段正文,纸面信息密度不低。扫描结果里,纸被从深色背景里完整裁了出来,纸外的区域被压成纯白,原来偏冷偏暗的底色被拉回接近白纸,标题「英伟达宣布CEO交接」、日期「2026年11月12日」、三行要点和正文都被逐段识别了出来——连 NVDA、Synopsys、Jensen 这些混排在中英文里的专有名词也在。
几个截图里能直接读出来的事实:
- 找纸和裁切是同一次原生调用里的第一步,页面上的「已定位纸张」不是装饰,它决定了后面所有像素操作的作用范围;
- 扫描件是在设备上重新合成的:纸内像素保留、纸外像素用掩码压白,再抹光照、做二值化,所以背景的深色没有跟着进来;
- 文字来自增强后的那张图,不是原图。阴影被抹平之后,压在暗处的行也有机会被读到。
页面之外,原生返回的 DocumentScanResult 里还有几项:扫描件尺寸 width × height、裁剪框 crop、文本块数量、设备端耗时 durationMs,以及那张以 data: URI 形式返回的 PNG 扫描件。JS 侧要做的只是:
<Image source={{ uri: scan.image }} style={{ width: '100%', height: 320 }} resizeMode="contain" />
没有沙箱文件、没有相册写权限、没有额外的一次"把图存下来再读出来"。扫描件就是一段字符串,渲染、转发、存进业务状态都由调用方决定。
这个库不接管页面:选图之后要不要展示原图、扫描件放左边还是右边、识别文本要不要可选中,都是示例页自己的事。库只负责一次调用返回扫描件和文字。
3. 一张照片到一页扫描件:四步,零模型
写代码之前先把链路捋清楚。整条管线没有训练模型、没有网络请求,所有步骤都在 scanDocument(uri) 这一次原生调用里完成:
JS(React)
└─ pickImage() ──► 系统 PhotoViewPicker ──► file://media/...
│
▼
scanDocument(uri) ──► OhosOcr.scanDocument(TurboModule,跨 C++ 桥)
│
▼
OcrDocument.scanDocument(ArkTS,全本地)
├─ decodeImage(uri, 1600) RGBA_8888 / 长边 ≤ 1600
├─ subjectSegmentation 掩码 + 纸张包围盒
├─ documentCropToGray 白底合成 + 裁剪 + 灰度
├─ normaliseIllumination 背景估计 + 224
├─ otsuThreshold / binariseToRgba 墨 32 / 纸 252
├─ textRecognition 在增强后的 PixelMap 上识别
└─ toDataUri(enhanced, png, 100) data:image/png;base64,...
│
▼
{ uri, width, height, durationMs, crop, image, text, blocks }
| 步骤 | 代码 | 关键参数 | 为什么这么选 |
|---|---|---|---|
| 解码 | decodeImage | RGBA_8888;长边 1600;MIN_EDGE 64 | OCR 不需要 4K,1600 已经够读小字,又把逐像素循环压进毫秒级 |
| 找纸 | subjectSegmentation | maxCount: 1;前景图开 | 只要一张纸;拿到掩码才能做白底合成,包围盒只是裁切范围 |
| 合成 | documentCropToGray | 掩码 0…255;外扩 2% | 纸外压白,纸内保留;2% 是给包围盒的误差留余量 |
| 抹光 | normaliseIllumination | 盒式模糊半径 min(w,h)/20;乘 224 | 用局部背景做除法,阴影变平,纸面变亮但不爆白 |
| 二值化 | otsuThreshold + binariseToRgba | 阈值夹在 40…210;墨 32 / 纸 252 | 自适应阈值比固定 128 稳;夹取防止全黑或全白 |
| 识别 | recognisePixelMap | 每次 init / release;不做方向检测 | 增强后的像素直接进 OCR,扫描件与文字同源 |
| 出图 | toDataUri | PNG,质量 100;Base64 | 二值图用 PNG 压得最好;data: URI 不落盘、不要权限 |
这条链路里有三个刻意的取舍,先说清楚。
第一,不做四点透视矫正。 subjectSegmentation 返回的是轴对齐的矩形包围盒,加上一张任意形状的主体掩码。这一版用掩码做白底合成,用包围盒做裁剪,所以纸在画面里斜一点没关系——纸外的像素被掩码压白,斜边不会带进来;但如果纸被拍成很夸张的梯形,包围盒会框进更多背景,而这一版不会把四条边拉成矩形。四点单应是同系列 KMP 版做的事(找四个极值点、解 8 个未知数);RN 这版选的是"掩码 + 包围盒 + 像素增强",换来的是不依赖自研几何、全走系统能力。需要"把梯形拉正"时,应该换 KMP 版或在原生侧补单应,而不是指望这条管线。
第二,不落盘。 扫描件以 data:image/png;base64,... 返回,而不是写进应用沙箱再给一个 file://。好处是权限和清理都不用管,<Image> 直接能读;代价是字符串会占用 JS 堆,超大图不适合走这条路。所以长边被压在 1600,页面展示 JSON 时还会把 base64 折成 <data URI · N chars>。
第三,裁剪依赖主体分割,而主体分割挑设备。 它不支持模拟器,输入建议 720p 以上、长宽比不超过 3:1。这不是可以靠代码绕过的限制:没有掩码就没有白底合成,扫描件就退化成一张裁过的照片。示例页在模拟器上会明确报错,而不是悄悄给出一张脏图。
4. 工程怎么搭:一个 npm 包、一个 source-style HAR、一个示例宿主
先看整体结构。和同系列的沉浸光感库不同,这个库由一个 npm 包 + 一个原生 HAR + 一个示例宿主组成,三层各自解决不同的问题:
react-native-ohos-ocr/ # npm 库根目录(package.json,v0.2.0)
├─ src/ # 纯 TS:引擎、spec、安全包装
│ ├─ NativeOhosOcr.ts # codegen spec:6 个方法
│ ├─ OcrEngine.ts # 确定性演示引擎(收银小票 / 发票 / 名片)
│ ├─ OcrJson.ts # JSON 契约,字段顺序固定
│ ├─ models.ts # 不可变模型与校验
│ ├─ nativeBridge.ts # 纯 TS 兜底,永不抛错
│ ├─ ohosModule.ts # 原生安全包装,不可用 resolve null
│ └─ index.ts
├─ lib/ # Babel CJS/ESM + tsc 声明(构建产物)
├─ harmony/
│ ├─ ohos_ocr/ # HAR 源模块
│ │ ├─ Index.ets / BuildProfile.ets / ts.ts
│ │ ├─ oh-package.json5 / build-profile.json5
│ │ └─ src/main/
│ │ ├─ ets/RNOhosOcrTurboModule.ts
│ │ ├─ ets/RNOhosOcrPackage.ets
│ │ ├─ ets/generated/ # codegen:ArkTS Spec + ts.ts
│ │ ├─ ets/ocr/OcrDocument.ts # 扫描管线
│ │ ├─ ets/ocr/OcrPixels.ts # 解码 / 掩码 / 归一 / Otsu / 编码
│ │ ├─ ets/ocr/OcrImage.ts # 相册选图与图片识别
│ │ └─ cpp/ # CMake + Package + codegen C++ 桥
│ └─ ohos_ocr.har # source-style HAR(随 npm 包分发)
├─ example/
│ ├─ App.tsx # 单页文档扫描演示
│ └─ harmony/ # ★ DevEco 打开这个目录运行
├─ templates/ # 手动接线的 ArkTS / C++ 模板
├─ tools/build-har.sh # 组装 source-style HAR
├─ scripts/ # HAP 构建、包校验、bundle 预置头检查
├─ __tests__/ # Jest 36 例
├─ tests/ # node:test 原生模块 7 例
├─ artifacts/ # 本机构建日志与 npm 压缩包(不进包)
├─ index.d.ts / react-native.config.js
└─ README*.md / CHANGELOG.md / VALIDATION.md

三层的分工要拎清,不然很容易在 DevEco 里打开错地方:
src/是纯 TS,负责确定性引擎、JSON 契约和没有鸿蒙宿主时的降级;harmony/ohos_ocr/是 HAR 源模块,承载 TurboModule、扫描管线和 codegen 桥;example/harmony/才是带entry的示例宿主,DevEco 打开它才能跑。
这个库要同时满足三种消费者,所以 package.json 里三套入口并存:
{
"name": "react-native-ohos-ocr",
"version": "0.2.0",
"source": "./src/index.ts",
"main": "./lib/commonjs/index.js",
"module": "./lib/module/index.js",
"types": "index.d.ts",
"react-native": "./src/index.ts",
"harmony": {
"alias": "react-native-ohos-ocr",
"autolinking": {
"ohPackageName": "react-native-ohos-ocr",
"etsPackageClassName": "RNOhosOcrPackage",
"cppPackageClassName": "RNOhosOcrPackage",
"cmakeLibraryTargetName": "rnoh_ohos_ocr"
}
}
}
- Metro 走
react-native条件,直接读src/index.ts; - 不用源码的工程走
main/module和types,读lib/里的预编译产物; - RNOH 靠
harmony.autolinking找到 OHPM 包名、ArkTS Package 类、C++ Package 类和 CMake target。
这里的 HAR 是 source-style,不是 hvigor 编出来的二进制产物。tools/build-har.sh 会把 ArkTS 源码、codegen 生成的 C++ 桥、CMakeLists.txt、module.json 和 oh-package.json5 一起装进 package/,再打成一个 tar.gz:
STAGE_DIR="$(mktemp -d)"
PKG_DIR="${STAGE_DIR}/package"
cp -R "${MODULE_DIR}/src/main/ets/." "${PKG_DIR}/src/main/ets/"
cp -R "${MODULE_DIR}/src/main/cpp/." "${PKG_DIR}/src/main/cpp/"
(cd "${STAGE_DIR}" && COPYFILE_DISABLE=1 tar --exclude='._*' --exclude='.DS_Store' \
-czf "${OUTPUT_HAR}" package)
原因很实际:RNOH autolinking 会把模块的 src/main/cpp 加进宿主构建,所以 HAR 里必须有 C++ 源码、生成的 OhosOcr.cpp 和 CMake 文件;如果只发 hvigor 编出来的 HAR,宿主那边就没有可以链接的 target。HAR 里带的是源码,编译在宿主工程里完成。
示例宿主的接线只有三处。ArkTS 侧注册 Package:
// example/harmony/entry/src/main/ets/RNPackagesFactory.ets
import { RNOHPackage, RNPackageContext } from '@rnoh/react-native-openharmony';
import { RNOhosOcrPackage } from 'react-native-ohos-ocr';
export function createRNPackages(ctx: RNPackageContext): RNOHPackage[] {
return [new RNOhosOcrPackage(ctx)];
}
C++ 侧把生成的 Package 加进 PackageProvider,CMake 侧把 target 链上:
add_subdirectory("${OH_MODULE_DIR}/react-native-ohos-ocr/src/main/cpp" ./ohos_ocr)
target_link_libraries(rnoh_app PUBLIC rnoh_ohos_ocr)
对使用方来说,最终看到的 API 只有两类:一次扫描,和一次选图。
const uri = await pickImage(); // 取消时 null
if (uri !== null) {
const scan = await scanDocument(uri); // 原生不可用时 null
if (scan !== null) {
console.log(scan.width, scan.height);
console.log(scan.text, scan.blocks, scan.durationMs);
}
}
下面就按"找纸 → 抹光 → 识别 → 过桥 → 交付"的顺序,把代码拆开讲。
5. 把代码讲透
5.1 找纸:主体分割、掩码与 2% 外扩
扫描从确定哪一块是纸开始。
OcrDocument.scanDocument 先解码,再初始化主体分割。这里有个容易忽略的生命周期问题:分割引擎在拿到结果之后不能立刻释放,因为返回的前景 PixelMap 可能依赖引擎内部资源;释放早了,后面的掩码读取会拿到空图。所以 segment() 只负责调用,release 被留到整个管线结束:
async function segment(
pixelMap: image.PixelMap,
): Promise<subjectSegmentation.SegmentationResult> {
const visionInfo: subjectSegmentation.VisionInfo = { pixelMap };
const configuration: subjectSegmentation.SegmentationConfig = {
maxCount: 1,
enableSubjectDetails: false,
enableSubjectForegroundImage: true,
};
return await subjectSegmentation.doSegmentation(visionInfo, configuration);
}
三个参数都是有意为之:maxCount: 1 是因为文档扫描只处理一张纸;enableSubjectDetails: false 关掉逐主体的细节输出,省一次无用的计算;enableSubjectForegroundImage: true 才是关键——没有前景图,就没有那张 0…255 的掩码。
拿到包围盒之后,先按 2% 外扩再裁:
function expandRect(box: SegmentationBox, ratio: number): ImageRect {
const padX = box.width * ratio;
const padY = box.height * ratio;
return {
left: box.left - padX,
top: box.top - padY,
width: box.width + padX * 2,
height: box.height + padY * 2,
};
}
为什么要外扩?主体分割的包围盒通常贴着纸的可见边缘,但纸边本身有阴影、有卷角,裁得太紧会把边缘的一行字切掉。2% 是一个偏保守的值:既能把纸边完整包进来,又不会把太多桌面带进合成范围。外扩之后还要 clampCrop 回图像边界,避免负坐标越界。
决定"纸外面是什么颜色"的是掩码。resolveAlphaMask 先检查分割返回的 mattingList 尺寸是否和原图一致;一致就直接用,不一致就退回前景图的 alpha 通道:
export async function resolveAlphaMask(
matting: Int32Array,
width: number,
height: number,
foreground: image.PixelMap,
): Promise<AlphaMask> {
if (matting.length === width * height) {
const alpha = new Uint8Array(matting.length);
for (let index = 0; index < matting.length; index += 1) {
const value = matting[index];
alpha[index] = value < 0 ? 0 : value > 255 ? 255 : value;
}
return { alpha, width, height };
}
return readAlphaMask(foreground);
}
这个分支是必需的。mattingList 在文档里承诺按输入 PixelMap 尺寸返回,但设备实现并不总是严格这样;一旦长度对不上,直接按原图索引就会越界或者错位,扫描件会出现"纸的一部分被压白、背景的一部分被保留"的锯齿。退回前景图 alpha 通道是第二套来源,两者语义相同(0 是背景,255 是纸),只是分辨率可能不同,所以在采样时按比例映射:
if (mask.width === sourceWidth && mask.height === sourceHeight) {
return mask.alpha[y * sourceWidth + x] / 255;
}
const maskX = Math.min(mask.width - 1, Math.floor((x * mask.width) / sourceWidth));
const maskY = Math.min(mask.height - 1, Math.floor((y * mask.height) / sourceHeight));
return mask.alpha[maskY * mask.width + maskX] / 255;
合成这一步只有四行核心代码,但它是照片变扫描件的关键一步:
const alpha = maskAlpha(mask, sourceX, sourceY, sourceWidth, sourceHeight);
const red = source[sourceIndex] * alpha + 255 * (1 - alpha);
const green = source[sourceIndex + 1] * alpha + 255 * (1 - alpha);
const blue = source[sourceIndex + 2] * alpha + 255 * (1 - alpha);
gray[targetIndex] = Math.round(0.299 * red + 0.587 * green + 0.114 * blue);
纸内 alpha = 1,保留原像素;纸外 alpha = 0,直接变成 255(白);纸边是软过渡,按 alpha 线性混合。这样即使掩码边缘不是硬边,也不会出现一圈黑边。灰度用 BT.601 的系数,和大多数图像库一致,后面 Otsu 的直方图才稳定。
还有一个边界:裁剪框可能超出原图(2% 外扩之后),越界的像素直接填白,而不是跳过。跳过会在数组里留下 0,也就是黑色,扫描件边上会出现一条黑边。
5.2 光照归一:行对齐、盒式模糊、224 与 Otsu
纸找出来之后,第二件事是光照归一。
先看一个特别容易踩的底层细节:PixelMap 的像素缓冲区不一定是紧排的。设备可能按不同的字节数对齐(常见是 4 的倍数),行尾带 padding。如果直接用 width * 4 * height 去索引,图会越往下越斜。readRgba 用 getBytesNumberPerRow() 判断真实行宽,行宽不等于紧排行宽时逐行重排:
const rowBytes = pixelMap.getBytesNumberPerRow();
const totalBytes = pixelMap.getPixelBytesNumber();
const buffer = new ArrayBuffer(totalBytes);
await pixelMap.readPixelsToBuffer(buffer);
const tightRowBytes = width * 4;
if (rowBytes === tightRowBytes) {
return new Uint8Array(buffer);
}
const padded = new Uint8Array(buffer);
const pixels = new Uint8Array(tightRowBytes * height);
for (let y = 0; y < height; y += 1) {
const from = y * rowBytes;
const to = y * tightRowBytes;
for (let offset = 0; offset < tightRowBytes; offset += 1) {
pixels[to + offset] = padded[from + offset];
}
}
return pixels;
这段代码不复杂,但没有它,后面所有像素操作都是在读错位的数据。更麻烦的是它不会报错:扫描件只是看起来"整体向右下歪了一点",很容易被当成透视问题去查。
光照归一的思路是"除以局部背景"。先用可分离的盒式模糊估一张背景图,再用原图逐像素除以背景:
export function normaliseIllumination(gray: Uint8Array, width: number, height: number): Uint8Array {
const radius = Math.max(4, Math.round(Math.min(width, height) / 20));
const background = boxBlur(gray, width, height, radius);
const output = new Uint8Array(gray.length);
for (let index = 0; index < gray.length; index += 1) {
const base = background[index] < 8 ? 8 : background[index];
const value = (gray[index] / base) * 224;
output[index] = clamp(Math.round(value), 0, 255);
}
return output;
}
盒式模糊用两次一维滑动窗口实现,横一遍、竖一遍,复杂度从 O(w·h·r²) 降到 O(w·h)。半径取短边的 1/20:太小只能抹掉细节、抹不掉阴影;太大背景估计会把文字也算进背景,纸面反而变脏。base 的下限是 8,避免除零;乘 224 而不是 255,是给后面的二值化留一点余量——纯 255 的背景会把浅灰的字一起推到阈值以上,224 能让"纸"和"墨"仍然分开。
然后是 Otsu。它不需要任何参数,靠直方图找类间方差最大的阈值:
const delta = backgroundMean - foregroundMean;
const between = backgroundWeight * foregroundWeight * delta * delta;
if (between > best) {
best = between;
threshold = value;
}
最后把阈值夹在 40…210:
return clamp(threshold, 40, 210);
这个夹取很关键。遇到几乎全白的纸(比如过曝),Otsu 可能算出 250;遇到大面积深色背景,可能算出 20。直接使用会把整页判成纸或整页判成墨。40…210 是经验区间:低于 40 的阈值只可能出现在极端暗图,高于 210 的阈值只可能出现在极端亮图,两种情况下都应该往中间拉,让结果至少还能读。
二值化本身只输出两个灰度:墨 32、纸 252,alpha 固定 255。
const ink = gray[index] <= threshold;
const value = ink ? 32 : 252;
为什么不是 0 和 255?纯黑纯白在缩放预览时会出现明显的锯齿和振铃,32/252 留了一点对比余量,肉眼看起来更接近"扫描件",同时仍然远高于 OCR 的对比度要求。这个细节不影响识别率,但影响观感——而扫描件是要给人看的。
5.3 识别与出图:增强后的 PixelMap 同时用于 OCR 与编码
到这一步,手里的 binary 是 Uint8Array,还不是 PixelMap。先创建一张不透明的 RGBA 图:
const options: image.InitializationOptions = {
size: { width, height },
srcPixelFormat: image.PixelMapFormat.RGBA_8888,
pixelFormat: image.PixelMapFormat.RGBA_8888,
alphaType: image.AlphaType.OPAQUE,
editable: false,
};
return image.createPixelMap(pixels.buffer as ArrayBuffer, options);
然后把它同时传给 textRecognition 和 ImagePacker。
识别部分按次初始化和释放:
const initialized = await textRecognition.init();
if (!initialized) {
throw new Error('OCR engine initialization failed');
}
try {
const visionInfo: textRecognition.VisionInfo = { pixelMap };
const configuration: textRecognition.TextRecognitionConfiguration = {
isDirectionDetectionSupported: false,
};
const recognised = await textRecognition.recognizeText(visionInfo, configuration);
// ...
} finally {
await textRecognition.release();
}
isDirectionDetectionSupported: false 是扫描场景的优化:纸已经被裁正到轴对齐,文字方向基本是水平的,关掉方向检测能省一点时间,也避免个别竖排误判。识别结果只取 blocks[i].value,不取坐标——这个库的 DocumentScanResult 只承诺文本块,不承诺版面坐标;需要坐标时应该在原生侧扩展契约,而不是在 JS 里猜。
出图部分把同一张 PixelMap 编码成 PNG,再 Base64:
const packer = image.createImagePacker();
try {
const option: image.PackingOption = { format: mime, quality };
const encoded = await packer.packing(pixelMap, option);
const base64 = new util.Base64Helper().encodeToStringSync(new Uint8Array(encoded));
return `data:${mime};base64,${base64}`;
} finally {
await packer.release();
}
这里有个 API 版本的取舍:ImagePacker.packing 在 API 13 起被标记为 deprecated,推荐 packToData。这个库的最低兼容版本是 API 12,所以保留 packing,用注释标明迁移路径。等最低版本抬到 13,这个函数可以整体换掉,调用方无感。
data: URI 的好处前面说过:不落盘、不要权限。但它有代价:Base64 会让字节数膨胀约 33%,而且字符串要跨一次桥、进一次 JS 堆。示例页的对策是在展示 JSON 前把 data URI 折叠掉:
if (typeof value === 'string' && value.startsWith('data:')) {
compact[key] = `<data URI · ${value.length} chars>`;
}
scan.image 仍然完整保留给 <Image>,只是不把这个几百 KB 到数 MB 的字段塞进调试面板。这个处理看起来是 UI 细节,实际会影响端侧扫描在低内存设备上能否稳定运行。
5.4 桥:六个方法、一份字段顺序固定的 JSON
RN 侧对原生只有一个入口:codegen spec。src/NativeOhosOcr.ts 声明了六个方法,全部返回 Promise<string>:
export interface Spec extends TurboModule {
result(index: number, revision: number): Promise<string>;
filter(index: number, minConfidence: number): Promise<string>;
checks(): Promise<string>;
pickImage(): Promise<string>;
recognizeImage(uri: string): Promise<string>;
scanDocument(uri: string): Promise<string>;
}
export default TurboModuleRegistry.get<Spec>('OhosOcr');
为什么是字符串而不是对象?因为这条契约要和纯 TS 引擎逐字符对齐。对象过桥会被重新序列化,字段顺序、浮点格式、控制字符转义都可能变;字符串不会。documentScanToJson 手工拼 JSON,字段顺序就是契约的一部分:
return (
`{"uri":${jsonQuote(result.uri)}` +
`,"width":${result.width}` +
`,"height":${result.height}` +
`,"durationMs":${result.durationMs}` +
`,"crop":${boxJson(result.crop)}` +
`,"image":${jsonQuote(result.image)}` +
`,"text":${jsonQuote(result.text)}` +
`,"blocks":[${blocks}]}`
);
jsonQuote 不是 JSON.stringify 的包装,而是按 Kotlin 版逐字符实现的:引号、反斜杠、换行、回车、制表符,以及所有 < 0x20 的控制字符都转成 \uXXXX。这样原生和纯 TS 的输出可以直接用字符串比较,测试里也是这么做的。
codegen 把 spec 变成两半:ArkTS 的 OhosOcr.Spec 接口,和 C++ 的异步桥。生成的 OhosOcr.cpp 里能看到每个方法的元数据,比如:
ARK_ASYNC_METHOD_METADATA(scanDocument, 1)
这行告诉 RNOH:scanDocument 是一个异步方法,有 1 个参数。它决定了桥如何包装这次调用:有这行,JS 拿到的是 Promise;没有,方法就不会以异步方式注册。codegen 还生成了 BaseReactNativeOhosOcrPackage.h,C++ Package 只要继承它就能被 autolinking 找到:
namespace rnoh {
class RNOhosOcrPackage : public BaseReactNativeOhosOcrPackage {
public:
explicit RNOhosOcrPackage(Package::Context ctx)
: BaseReactNativeOhosOcrPackage(ctx) {}
};
}
ArkTS 侧的 Package 只做一件事:把 OhosOcr 这个名字映射到实现类。
export class RNOhosOcrPackage extends RNOHPackage {
getUITurboModuleFactoryByNameMap(): Map<string, (ctx: UITurboModuleContext) => UITurboModule> {
return new Map<string, (ctx: UITurboModuleContext) => UITurboModule>([
[RNOhosOcrTurboModule.NAME,
(ctx: UITurboModuleContext): UITurboModule => new RNOhosOcrTurboModule(ctx)],
]);
}
}
JS 侧不直接碰 TurboModule,而是走 ohosModule.ts 的安全包装。原因是非鸿蒙宿主(iOS / Android / Web / Expo)上 TurboModuleRegistry.get('OhosOcr') 会返回 null 或者抛错;如果业务直接调用,整个页面会崩。包装层把这些情况统一成 null:
function getNativeModule(): OhosOcrSpec | null {
try {
return TurboModuleRegistry.get<OhosOcrSpec>('OhosOcr') ?? null;
} catch {
return null;
}
}
export async function scanDocument(uri: string): Promise<DocumentScanResult | null> {
const nativeModule = getNativeModule();
if (nativeModule === null) {
return null;
}
const json = await nativeModule.scanDocument(uri);
return JSON.parse(json) as DocumentScanResult;
}
这就形成了双轨:鸿蒙宿主上走原生扫描,其他宿主上 scanDocument 返回 null,业务可以降级到纯 TS 的确定性引擎(那个引擎不处理图片,只演示契约),或者干脆隐藏扫描入口。库不替业务决定降级策略,只保证降级不会抛错。
5.5 交付:source-style HAR 与 115 个文件的包
构建分三条线:
npm run verify:package # npm pack + HAR 内容 + 类型解析 + autolinking 元数据
npm run build:har # 组装 harmony/ohos_ocr.har
npm run build:example # Metro bundle + ohpm install + Hvigor 构建 unsigned HAP
build:har 走 tools/build-har.sh,verify:package 走 scripts/verify-package.cjs。后者不信任工作区,而是先 npm pack,再解开 tarball 逐项断言:
for (const file of [
'lib/commonjs/index.js', 'lib/module/index.js',
'lib/typescript/commonjs/index.d.ts', 'lib/typescript/module/index.d.ts',
'harmony/ohos_ocr.har',
'harmony/ohos_ocr/src/main/ets/ocr/OcrDocument.ts',
'harmony/ohos_ocr/src/main/ets/ocr/OcrPixels.ts',
// ...
]) assert.ok(paths.has(file), `Missing packaged file: ${file}`);
它还会拒绝开发期垃圾和签名材料:
assert.ok(!/(^|\/)(oh_modules|node_modules|build|\.hvigor|\.cxx|artifacts)(\/|$)/.test(file), `Build debris: ${file}`);
assert.ok(!/\.(p12|p7b|cer|keystore)$|local\.properties|signing\.local/.test(file), `Local signing file: ${file}`);
HAR 里的内容也被逐项校验:package/Index.ets、ts.ts、oh-package.json5、module.json、CMakeLists.txt、RNOhosOcrPackage.h、生成的 OhosOcr.cpp、RNOhosOcrTurboModule.ts,以及扫描管线的两个文件 OcrPixels.ts / OcrDocument.ts。再加上对 ARK_ASYNC_METHOD_METADATA 的断言,基本覆盖了"这个 HAR 拿出去能不能被宿主链接"的所有前提。
当前包的结果是 115 个文件、88,999 字节(解包后 259,292 字节),HAR、包内容、声明消费与 autolinking 元数据全部通过。示例 HAP 约 38 MB,未签名时只能构建出 entry-default-unsigned.hap,装真机前需要本地签名。
6. 我踩过的坑(真实报错与排查记录)
以下坑全部来自这次开发的报错、真机现象和排查记录。
坑一:require 不存在,JS bundle 还没执行就崩了。 第一次装到 ALN-AL00 上,页面还没出来就红屏:
[runtime not ready]: ReferenceError: Property 'require' doesn't exist
Stack: anonymous (bundle.harmony.js:2:27) / global (bundle.harmony.js:2:2086)
根因不在业务代码,而在 Metro 预置头。React Native preset 默认启用 @babel/plugin-transform-runtime,会把 require("@babel/runtime/helpers/typeof") 注入到 bundle 最前面的预置头里。鸿蒙的 JS 引擎在执行预置头时还没有全局 require,所以第 2 行就炸了——业务代码一行都没跑到。
修复分三步:example/babel.config.js 设置 enableBabelRuntime: false,把 helper 内联;构建脚本加 --reset-cache,避免旧的 Babel 转换缓存继续生效;新增 scripts/check-bundle.cjs,在打包后检查预置头里不能出现顶层 require。第三步最重要:前两步只修当前这次构建,第三步会在每次打包后检查,防止同类问题再进来。
坑二:DocumentScanner 是控件,不是 API。 我原本的计划是"系统有文档扫描,直接调"。翻完 Core Vision Kit 的文档才确认:DocumentScanner 是一个 ArkUI 页面组件,要由用户触发快门、在界面里确认裁剪;TurboModule 没有 UI 上下文,调不到它。这不是参数没传对,是架构上就不成立。
替代方案是 subjectSegmentation + 像素管线。代价是要自己实现白底合成、光照归一、Otsu 和二值图编码,收益是完全无头:一次调用、没有界面、没有用户交互,适合被任意 RN 页面调用。这条替代路径还带来一个额外约束:主体分割不支持模拟器,所以文档扫描只能真机验收;示例页在模拟器上会明确提示,而不是给一张脏图。
坑三:mattingList 不一定和原图同分辨率。 我一开始的代码假设 mattingList.length === width * height,直接按原图索引。这个假设只在掩码和原图同分辨率时成立;一旦设备返回的掩码尺寸不同,白底合成就会变成"纸被切掉一半、背景留下一条"——原因是索引错位,掩码本身没有问题。
这个坑我没有等它发生。写第一版时就按"掩码可能不同分辨率"这个前提做了双分支:长度一致直接用,不一致退回前景图的 alpha 通道;采样时按比例缩放。现在看起来理所当然,但它省掉的是真机上最难查的那类错位。
坑四:PixelMap 的行宽带 padding,图会越往下越斜。 这个问题最难查,因为它不报错。扫描件看起来"整体向右下歪",第一反应是透视或裁剪框算错了,查了半天几何都没问题。最后把 getBytesNumberPerRow() 打出来才发现:行宽不等于 width * 4,缓冲区行尾有对齐填充,而我按紧排索引在读。
修复就是 5.2 里那段逐行重排。教训是:任何直接读 PixelMap 缓冲区的代码,都必须先问行宽,而不是假设紧排。
坑五:foregroundImage 的生命周期比想象中短。 文档没有把"分割引擎释放之后前景图还能不能用"写清楚,但实现上它可能引用引擎内部资源。第一版我差点把 subjectSegmentation.release() 放在 finally 的最前面——那样一来,后面读掩码时图可能已经失效。
现在的释放顺序是:先释放增强图,再释放前景图,然后才释放分割引擎,最后释放解码得到的文件 / ImageSource / PixelMap。所有释放都包在 try/catch 里,且不能吞掉管线本身的错误——释放失败是次要问题,原始异常才是要看的。
坑六:Base64 过桥,字符串比图还大。 第一版把 scan.image 原样塞进页面上的 JSON 预览,一张 1080×1151 的扫描件让页面明显卡顿:PNG 本身不大,但 Base64 膨胀 33%,再经过一次 JSON.stringify 和一次桥传输,字符串在 JS 堆里翻了几倍。更糟的是,这个字段对调试没用——没人会去读几百 KB 到数 MB 的 base64。
修复有两层:示例页展示 JSON 前把 data: 开头的字段折成 <data URI · N chars>;原生侧把长边压在 1600,避免 4K 原图直接进管线。如果业务真的需要归档大图,正确做法是让原生把文件写进沙箱再返回路径,而不是把整张图塞进 JSON——这一版为了"零权限、零落盘"选择了 data URI,边界要写清楚。
7. 现在怎么用:从一次 pickImage 到一页扫描件
这个工程现在是一个标准的 React Native 三方库(包名 react-native-ohos-ocr,版本 0.2.0)。仓库已经按 npm 发布形态准备好,但包还没有正式发到 npm;现阶段用本地 tarball 或 path 依赖接入:
# 先生成压缩包
npm pack
# 在应用的 JS 根目录安装
npm install /absolute/path/to/react-native-ohos-ocr-0.2.0.tgz
它只使用 peer 依赖,不捆绑 react / react-native;运行时要求 react-native >= 0.68,Node.js >= 22.11(构建期)。本文的验证环境是 React 19.2.3 + RN 0.84.1 + RNOH 0.84.3。
最小用法:
import React, { useState } from 'react';
import { Image, Pressable, Text, View } from 'react-native';
import {
isOhosOcrAvailable,
pickImage,
scanDocument,
type DocumentScanResult,
} from 'react-native-ohos-ocr';
export function ScanCard() {
const [scan, setScan] = useState<DocumentScanResult | null>(null);
const [message, setMessage] = useState('选择一张文档照片');
const run = async () => {
if (!isOhosOcrAvailable()) {
setMessage('当前宿主没有注册原生 OhosOcr');
return;
}
const uri = await pickImage();
if (uri === null) {
setMessage('未选择图片');
return;
}
setMessage('正在端侧扫描…');
const result = await scanDocument(uri);
if (result === null) {
setMessage('原生扫描模块不可用');
return;
}
setScan(result);
setMessage(`扫描完成 · 端侧 ${result.durationMs}ms`);
};
return (
<View>
<Pressable onPress={run}><Text>选择图片并扫描</Text></Pressable>
<Text>{message}</Text>
{scan !== null ? (
<>
<Image source={{ uri: scan.image }} style={{ width: '100%', height: 320 }} resizeMode="contain" />
<Text selectable>{scan.text}</Text>
</>
) : null}
</View>
);
}
scanDocument 的返回结构:
| 字段 | 类型 | 说明 |
|---|---|---|
uri | string | 输入图片 URI |
width / height | number | 扫描件尺寸(裁剪后) |
durationMs | number | 设备端实测耗时(解码 + 分割 + 增强 + 识别 + 编码) |
crop | SegmentationBox | null | 纸张裁剪框(源图像素坐标) |
image | string | 二值扫描件的 data:image/png;base64,... |
text | string | 识别全文,按块换行拼接 |
blocks | { text }[] | 文本块 |
API 一览:
| API | 说明 |
|---|---|
scanDocument(uri) | 端侧扫描:裁纸 → 白底合成 → 光照归一 → Otsu → 识别 → PNG data URI;不可用时 resolve null |
pickImage() | 系统 PhotoViewPicker;取消或不可用时 resolve null,不需要相册权限 |
recognizeImage(uri) | 只识别不扫描,返回 OcrImageResult(fullText / blocks / durationMs) |
resultJson / filterJson / checksJson | 原生确定性引擎调用;不可用时 resolve null |
ocrResultJson / filterResultJson / runChecksJson | 纯 TS 桥接,永不抛错,失败返回 {"error":"..."} |
isOhosOcrAvailable() | 原生 OhosOcr 是否注册 |
OcrEngine | 纯 TS 确定性引擎(catalog / result / filter / reduce / runChecks) |
fullText / averageConfidence / toJson | 派生值与 JSON 序列化 |
构建与验证:
npm ci
npm test # Jest 36 例 + node:test 原生模块 7 例
npm run typecheck # tsc --noEmit
npm run build:har # 组装 source-style HAR
npm run build:example # 构建示例 HAP(需要 DevEco 的 hvigor / ohpm)
npm run verify:package # 校验 npm tarball、HAR、类型与 autolinking
当前版本的验证结果:
| 项目 | 状态 |
|---|---|
npm test | 通过:Jest 36 / 36;node:test 原生模块 7 / 7 |
npm run typecheck | 通过,0 错误 |
npm run codegen:harmony | 通过:OhosOcr.cpp 含 ARK_ASYNC_METHOD_METADATA(scanDocument, 1),ArkTS Spec 同步 |
npm run build:har | 通过:HAR 编译成功(BUILD SUCCESSFUL,0 个 ArkTS 错误) |
npm run build:example | 通过:Metro bundle、ArkTS / C++ 链接、unsigned HAP 生成(约 38 MB) |
npm run verify:package | 通过:115 个文件、88,999 字节;HAR、声明消费与 autolinking 元数据全部通过 |
npm run verify:integration | 2026-11-11 通过:从 npm 压缩包安装 → autolinking → 独立消费方 HAP;0.2 增量后未重跑 |
| 真机 | HUAWEI ALN-AL00(HarmonyOS 7.0.0.109 / API 26):nativeBridge: OK;相册识别 21 个文本块、约 1.5s;文档扫描页见第 2 节截图 |
能力边界也写清楚:
- 这一版不做四点透视矫正,裁切是轴对齐包围盒 + 掩码合成;纸被拍成夸张梯形时,包围盒会带进背景,需要单应时用同系列 KMP 版;
- 依赖
subjectSegmentation,不支持模拟器,输入建议 720p 以上、长宽比不超过 3:1; - 只处理单张纸(
maxCount: 1),不做多页、不做去卷曲、不做版面还原; - 扫描件以
data:URI 返回,适合展示与转发,不适合归档超大图;需要落盘时由业务把 base64 写到沙箱; - 它是扫描管线,不是文档管理器:多页排序、检索、OCR 结果编辑都由宿主负责。
更完整的说明在仓库的文档里:
- API、安装、JSON 契约与目录结构;
- RNOH 接入、手动链接、构建与真机验收步骤;
- 构建记录、包校验与已知约束;
example/App.tsx:单页扫描示例(选图 → 扫描件 + 文字 + 耗时);templates/:宿主手动接线的 ArkTS / C++ 模板。
同系列的其它实现走了不同的路:KMP 版自己做四点单应,Flutter 版走插件通道,Qt / Electron 版把桥架在进程外;RN 这条选的是 TurboModule + 像素级增强,换来的是零权限、零文件落盘、一次调用同时拿回扫描件与文字;代价是要自己维护整条像素管线。
更多推荐



所有评论(0)