纸怎么从背景里被找出来、阴影怎么被抹平、二值化后的画面怎么还能被认出来——这篇文章用一个跑在鸿蒙真机上的 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 Native0.84.1
React19.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)
hvigorDevEco Studio 自带(HVIGOR_JS 可覆盖)
react-native-ohos-ocr0.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 }
步骤代码关键参数为什么这么选
解码decodeImageRGBA_8888;长边 1600;MIN_EDGE 64OCR 不需要 4K,1600 已经够读小字,又把逐像素循环压进毫秒级
找纸subjectSegmentationmaxCount: 1;前景图开只要一张纸;拿到掩码才能做白底合成,包围盒只是裁切范围
合成documentCropToGray掩码 0…255;外扩 2%纸外压白,纸内保留;2% 是给包围盒的误差留余量
抹光normaliseIllumination盒式模糊半径 min(w,h)/20;乘 224用局部背景做除法,阴影变平,纸面变亮但不爆白
二值化otsuThreshold + binariseToRgba阈值夹在 40…210;墨 32 / 纸 252自适应阈值比固定 128 稳;夹取防止全黑或全白
识别recognisePixelMap每次 init / release;不做方向检测增强后的像素直接进 OCR,扫描件与文字同源
出图toDataUriPNG,质量 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 的返回结构:

字段类型说明
uristring输入图片 URI
width / heightnumber扫描件尺寸(裁剪后)
durationMsnumber设备端实测耗时(解码 + 分割 + 增强 + 识别 + 编码)
cropSegmentationBox | null纸张裁剪框(源图像素坐标)
imagestring二值扫描件的 data:image/png;base64,...
textstring识别全文,按块换行拼接
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:integration2026-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 + 像素级增强,换来的是零权限、零文件落盘、一次调用同时拿回扫描件与文字;代价是要自己维护整条像素管线。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐