一个只对 ArkTS 开放的系统能力、一条同进程的回环 HTTP 桥、一份四个语言逐字节对齐的 JSON 契约——这篇文章记录一个 Qt 6 CMake 库加一套可导入 DevEco 的 ArkTS 壳,以及这三个问题各自的解法。

仓库地址:https://atomgit.com/oh-tpc/qt-ohos-ocr-lines
三方框架版本:https://wiki.qt.io/Qt_for_HarmonyOS
组织仓库链接:https://atomgit.com/ohos-qt

0. 环境与实测设备

实测环境:

项版本/型号
Qt6.11.0(桌面,Homebrew qtbase/qtdeclarative);库基线 Qt 6.5+;设备端 Qt for HarmonyOS 6.12 technology preview 载具
系统 SDKHarmonyOS SDK API 26;compatibleSdkVersion 6.0.0(20) / targetSdkVersion 26.0.0
DevEco Studio6.x(真机运行、签名、HAP 调试)
构建桌面 CMake 4.3.2 + Ninja(macOS arm64,Xcode 26.2 SDK);设备端 hvigor 6.26.4 / ohpm 6.0.1
测试QtTest 19 项(JSON 契约 9 + 引擎状态机 10;mock 传输,不需要设备)
识别引擎Core Vision Kit textRecognition(API 12 起可用,端侧离线)
设备HUAWEI MateBook Pro S(MOR-W52),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26

1. 桥为什么必须存在:一个错误的起手假设

起因很简单。端侧 OCR 这个系列我做到了第五篇:KMP 用 Kotlin/Native 走 C ABI + N-API,Flutter 用 MethodChannel,React Native 用 TurboModule,Electron 干脆把设备当外挂引擎、用 hdc 驱动一个 ArkTS agent。轮到 Qt,我先试的是最直接的一条路:Qt 是 C++,鸿蒙有 NDK,找个 C++ 绑定调一下 textRecognition 就完事。

动手翻文档才发现这个假设从根上就不成立:Core Vision Kit 的 textRecognition 只对 ArkTS 开放——没有 NDK、没有 C++ 绑定;而 C++ 与 ArkTS 的官方互操作通道 N-API,方向是 ArkTS → C++,没有“C++ 反向调用 ArkTS”的官方机制。Qt for HarmonyOS 的载具(QAbility / QAbilityStage)只负责把 UIAbility 的生命周期交给 libqohos.so,没有给 native 留一个能回调 ArkTS 运行时的扩展点。结论很直接:从 C++ 里直接调系统 OCR 没有可用入口。

再往下看,Qt for HarmonyOS 应用本身就是“Qt 半边 + ArkTS stage 壳半边”,两部分运行在同一个进程、同一个沙箱里,缺的只是两边之间的通信方式。socket 是两边都能用的最低层接口:ArkTS 侧用 @ohos.net.socket 起一个 127.0.0.1 微型 HTTP 服务,Qt 侧用 QNetworkAccessManager 调用——回环不出设备、不出沙箱,textRecognition 的 ArkTS-only 限制就这么绕过去了。

所以这个题目的边界很清楚:库代码按 Qt 6.5+ 编写(桌面可编译可单测),桥接层作为可替换传输接口,ArkTS 半边从 flutter_ohos_ocr 移植。具体拆成三件事:

  • 回环 HTTP 桥怎么设计(路由、传输规则、端口发现,这是核心);
  • 识别质量怎么守(长图条带、置信度不伪造、重复行保留的家族差异);
  • JSON 契约怎么与第四个语言对齐(C++ 手写 toJson() 与 Kotlin/ArkTS/Dart 逐字节一致)。

2. 效果展示

先看效果,再讲原理。先看鸿蒙这一半——这是 examples/ohos-app 直接跑在 2in1 真机上的演示页,不是模拟器截图:

在这里插入图片描述

窗口标题 qt-ohos-ocr demo,页面第一行是 qt-ohos-ocr 文字识别,副标题 HarmonyOS Core Vision Kit · 端侧离线识别。两个按钮:蓝色主按钮 选择图片识别、灰色 重识别示例。状态行写着 识别到 15 行 · 原生耗时 207 ms,下面是刚识别的图——一张 1747×584 的文件管理器截图(screenshot_20261112_012314_com.huawei.hmos.filemanager.jpg),右边是文件名、尺寸与原生耗时。

再往下就是结果:识别结果 · 15 行,逐条编号——rnOBJ、tauriOBJ、cordovaOBJ、gtOBJ、electronOBJ、今天 上午1:21、今天 上午12:14、昨天 下午11:50、昨天 下午9:20、昨天 下午9:08,然后连续五个 文件夹。底部一行小字把链路的身份写完了:bridge listening · 127.0.0.1:52141 · protocol 1 · v0.1.0。

五个 文件夹 是这张图的关键。上游 kmp/flutter 的模型要求块文本唯一、会按文本去重;Qt 版刻意保留重复行——5 个 文件夹 就是 5 行。要是照抄上游的 distinctBy,这张图只剩 11 行,用户拿到的行数与原图对不上。小票上两个 ¥0.00、文件列表里五个 文件夹,都是原文的一部分,丢掉一行就是丢字。这是这个系列里第一次在“块语义”上出现差异,5.4 与第 6 节还会讲。

3. 识别怎么回来:同一进程里的 C++ 与 ArkTS

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

这套东西从头到尾是一条链,链上每一段都在同一个应用进程里:

QML(examples/quick/Main.qml)
  │  import QtOhosOcr 1.0
  ▼
QOhosOcrEngine(C++)                 Idle → Busy → recognized / failed
  │  recognizeBytes / recognizeFile / pickAndRecognize
  ▼
IOcrTransport(接口) ── OcrHttpBridge(QNAM)
  │  POST application/octet-stream · 20 s 超时 · Connection: close
  ▼
127.0.0.1:52141                      同进程回环,不出沙箱
  │
  ▼
OcrBridgeService(ArkTS,478 行)     手写 HTTP/1.1 子集
  ├─ GET  /v1/ping                    → 桥身份(name / protocol / version)
  ├─ POST /v1/recognize?source=&language=   → OcrResult JSON + width/height
  └─ POST /v1/pick?language=          → 结果 JSON 或 {"cancelled":true}
  │
  ▼
VisionOcr(移植自 flutter_ohos_ocr)
  ├─ textRecognition.init()           每进程一次,6 秒超时
  ├─ ImageSource → PixelMap → recognizeText
  └─ >3000 px 的高图切 160 px 重叠条带,按行归属合并
  │
  ▼
Core Vision Kit(系统服务 · 端侧 · 离线)
  │
  ▼
OhosOcrResult(Q_GADGET)← fromJson() ← 同一份 JSON
  │
  ▼
QML:编号列表 / 复制全文 / 状态栏 / 错误横幅

把链路拆开看,每一段只做一件事。

桥是回环,不是网络。 服务只监听 127.0.0.1,请求不出应用沙箱;图片以 application/octet-stream 裸字节发送,不做 base64——回环带宽不是瓶颈,编码解码的 CPU 和体积膨胀才是多余的。唯一的权限是 system_grant 的 ohos.permission.INTERNET,安装即授予、没有运行时弹窗。

一次一条连接。 HTTP/1.1 的最小子集:Connection: close、一连接一请求、Content-Length 定界、客户端 20 秒超时。三条路由不值得引入完整 HTTP 栈;curl 又能直接调,诊断成本几乎为零。

识别在 ArkTS 里完成。 VisionOcr 把字节解码成 PixelMap,调 textRecognition.recognizeText,把 blocks/lines 整理成家族模型;ImageSource / PixelMap 在 finally 里释放。长图先切条带,再按行中心归属合并。

结果按契约回来。 ArkTS 手写 toJson(),C++ 手写 fromJson();字段顺序、分隔符、浮点格式、转义表全部逐字节对齐。QML 拿到的 OhosOcrResult 是 Q_GADGET,列表直接绑 blocks。

可诊断性是设计的一部分。 GET /v1/ping 返回桥身份(protocol 1 / v0.1.0),服务启动后还会把 {"port":...} 写进应用沙箱的 files/qt_ohos_ocr_bridge.json;Qt 侧把 bridgeName/bridgeProtocol/bridgeVersion 暴露成属性,示例页底部那行 bridge listening · 127.0.0.1:52141 · protocol 1 · v0.1.0 就是它。桥通没通,不用猜。

为什么是回环 HTTP,而不是别的? 把候选方案摆在一起就很清楚:

方案说明评估
NDK 直调C++ 直接调 textRecognition不可行:官方没有 NDK 绑定
N-API 注入回调ArkTS 启动时把回调注册给 native方向反了:native 需要持有 ArkTS 运行时引用并在其线程执行,Qt 载具不提供这个扩展点
QML 嵌 ArkUI 原生视图把 ArkUI 页面嵌进 Qt 窗口再转发事件复杂、体验割裂,也没有官方混合视图承诺
本地 HTTP 回环(本方案)ArkTS 起 127.0.0.1 微型 HTTP,C++ 用 QNAM 调用双方只用稳定公开 API;同进程、不出沙箱、可 curl 调试

和系列其它 OCR 路径摆在一起,Qt 这一格的特殊之处是“载具本身没有 C++ → ArkTS 通道”:

载具与 ArkTS 的通道谁调系统 API
原生 ArkTS同语言直接调用ArkTS
KMP(kmp-ohos-ocr)Kotlin/Native → C ABI → N-API(JSON)ArkTS
Flutter(flutter_ohos_ocr)MethodChannelArkTS 插件
React Native(react-native-ohos-ocr)TurboModule(codegen 生成 C++ 异步桥)ArkTS
Electron(electron-ohos-ocr)hdc 驱动设备侧 ArkTS agent设备上的 agent
Qt(本库)同进程 127.0.0.1 回环 HTTP(QNAM)ArkTS 桥服务

KMP 至少还能把 Kotlin/Native 的 C ABI 暴露给 N-API,由 ArkTS 主动调进来;RN 有 TurboModule 这层官方桥;Qt 的 QAbility 只把生命周期交给 libqohos.so。选回环桥不是为了省事:它是不需要修改 Qt 载具的那条路。

约束也如实说:识别链路只在 HarmonyOS/OpenHarmony 上工作,且必须带 Core Vision Kit。桌面环境没有 ArkTS 运行时,桥探测失败(available == false、OCR_BRIDGE_UNAVAILABLE)是设计内的状态——引擎、模型和 19 项单测照常跑。图片字节在进程内多一次拷贝,大图建议压到 4~8 MB;一次只允许一个在途识别(OCR_BUSY);系统不返回逐行置信度,confidence 固定 0.0、hasConfidence 为 false,UI 干脆不展示百分比(整列隐藏),不伪造一个数字。坐标(cornerPoints)未透出,PDF、批量图、相机流属于宿主业务层。

性能数据也顺带记一笔:真机上 1747×584、15 行的原生耗时是 207 ms;1242×6500、140 行的长图约 3.5 s。成本的大头在识别本身,回环 HTTP 的往返是毫秒级噪声;每请求一条连接、不做 keep-alive,握手开销在 OCR 这种低频操作上测不出来——这个取舍 5.2 里再展开。

4. 工程怎么搭:一份 CMake 库,一套 ArkTS 工程壳

先看整体结构。库本体是标准 Qt 6 CMake 工程,ohos/ 是待合并进载具的 ArkTS 工程壳,另有桌面示例和可直接导入 DevEco 的完整鸿蒙示范工程:

qt-ohos-ocr/
├─ include/qt-ohos-ocr/                    # 公共头:引擎 / 模型 / 传输接口
│  ├─ qohosocrengine.h                     # QML/C++ 异步门面(两状态机)
│  ├─ ohosocrresult.h                      # Q_GADGET 值类型 + JSON 契约
│  └─ ocrbridge/
│     ├─ OcrTransport.h                    # 传输接口(mock 注入点)
│     └─ OcrHttpBridge.h                   # QNAM 回环实现
├─ src/                                    # 实现:引擎、模型、桥
├─ ohos/                                   # ArkTS 桥接层(合并进 Qt 载具)
│  └─ entry/src/main/ets/
│     ├─ ocrbridge/OcrBridgeService.ets    # 127.0.0.1:52141 微型 HTTP
│     ├─ ocr/VisionOcr.ets                 # 条带切分 + Core Vision Kit
│     ├─ ocr/OcrModels.ets · OcrJson.ets   # 家族 JSON 契约
│     ├─ entryability/EntryAbility.ets     # 两个 merge 块
│     └─ pages/Index.ets                   # ArkTS 冒烟页(第 2 节第一张图)
├─ examples/
│  ├─ quick/                               # Qt Quick 示例(FileDialog + 截图模式)
│  └─ ohos-app/                            # DevEco 直接导入的完整工程
├─ tests/                                  # QtTest 19 项(mock 传输)
├─ tools/mock_bridge.py                    # 桌面 UI 开发用的模拟桥
├─ docs/                                   # API、架构、验证记录
└─ CMakeLists.txt · README.md · README.OpenHarmony*.md · CHANGELOG.md

在这里插入图片描述

这次设计最关键的决定有三个:

传输是接口,不是实现。 IOcrTransport 只定义 ping / postRecognize / postPick 三个操作;OcrHttpBridge 是它的 QNAM 实现。单测注入 MockTransport,19 项测试全部离线跑;未来官方开放 C++ → ArkTS 通道,换一个实现类即可,引擎与 QML 不动。这个注入口就是整个库的可测试性所在。

桌面先行是设计选择。 库按 Qt 6.5+ API 编写,任何桌面环境直接编译;桥探测失败是明确可预期的状态。仓库自带 tools/mock_bridge.py,用同样的三个路由返回固定结果,QML 的列表、复制全文、错误横幅、桥状态都能在桌面上开发和截图。业务逻辑先写完测完,再搬上设备。

ArkTS 工程壳按 merge 块组织。 载具工程已经生成的 QAbility 不替换,只把 ocrbridge/ 与 ocr/ 两个目录拷进 entry 的 ets/,在 onCreate / onDestroy 各加一行(merge 块在文件里有标注)。嫌麻烦就直接用 examples/ohos-app/——一套能导入、能签名、能跑的完整 stage 工程。

对使用方来说,QML 侧只有这几行:

import QtOhosOcr 1.0

QOhosOcrEngine {
    id: ocr
    onRecognized: (result) => lines.model = result.blocks   // 识别行
    onFailed: (error) => banner.text = error                 // "CODE: message"
}

Button { onClicked: ocr.recognizeFile(fileDialog.selectedFile) }

C++ 侧加载 QML 前注册一次类型:qtOhosOcrRegisterQmlTypes()。

下面把库内部拆开讲:一个两状态的引擎、一个手写的 HTTP 子集、一段把长图切回完整行的识别代码、一份逐字节对齐的契约,最后是上鸿蒙的合并链路。

5. 把代码讲透

5.1 引擎:两个状态,UI 线程保持空闲

QOhosOcrEngine 的头文件注释把状态机画得很直白:

Idle ── recognizeBytes()/recognizeFile()/pickAndRecognize() ──▶ Busy
Busy ── transport reply ──▶ recognized(OhosOcrResult) | failed(err) ──▶ Idle

两段关键代码:文件读取怎么丢给工作线程,以及 mock 的同步回调怎么和 QNAM 的异步回调对齐到同一个线程:

// src/qohosocrengine.cpp(节选)
void QOhosOcrEngine::recognizeFile(const QUrl &fileUrl, const QString &language)
{
    if (m_busy) {
        rejectCall(QStringLiteral("OCR_BUSY: a recognition is already running"));
        return;
    }
    QString path;
    if (fileUrl.isLocalFile())
        path = fileUrl.toLocalFile();
    else if (fileUrl.scheme() == QLatin1String("qrc"))
        path = QLatin1Char(':') + fileUrl.path();     // qrc:/x → :/x,QFile 只认这个
    else
        path = fileUrl.toString(QUrl::PreferLocalFile);

    setBusy(true);                                    // 读文件 + 识别全程占用

    auto *watcher = new QFutureWatcher<QByteArray>(this);
    connect(watcher, &QFutureWatcherBase::finished, this, [this, watcher, path, language]() {
        const QByteArray bytes = watcher->result();
        watcher->deleteLater();
        if (bytes.isEmpty()) {
            failRecognition(QStringLiteral("OCR_IO_ERROR: cannot read ") + path);
            return;
        }
        startRecognizeBytes(bytes, QFileInfo(path).fileName(), language);
    });
    watcher->setFuture(QtConcurrent::run([path]() -> QByteArray {
        QFile file(path);
        if (!file.open(QIODevice::ReadOnly))
            return QByteArray();
        return file.readAll();
    }));
}

OhosOcrTransportCallback QOhosOcrEngine::queued(
        std::function<void(const OhosOcrTransportReply &)> handler)
{
    // Capture by value: the mock may fire before this function returns.
    return [this, handler](const OhosOcrTransportReply &reply) {
        QMetaObject::invokeMethod(this, [this, handler, reply]() {
            handler(reply);
        }, Qt::QueuedConnection);
    };
}

四个设计点:

Busy 期间的新调用立即失败(OCR_BUSY)而不是排队——OCR 是重操作,静默排队会让用户以为卡死;唯一被允许并行的是 probeAvailability(),探测不该被一次大图识别阻塞。UI 线程永远空闲:传输本身是 QNAM 异步,文件读取丢给 QtConcurrent 工作线程。

回调必须归一。 mock 可能在 postRecognize() 返回前就同步回调,QNAM 走的是异步信号——queued() 用 QMetaObject::invokeMethod(..., Qt::QueuedConnection) 把所有回调压到引擎线程,状态机是单线程的,测试才稳定。

QML 值类型名必须小写。 qmlRegisterUncreatableType<OhosOcrResult>(uri, ..., "ohosOcrResult", ...) 里注册名是小写的 ohosOcrResult / ohosOcrBlock;QML 的值类型名以小写字母开头,大写会注册失败或 QML 侧拿不到类型。这是 Qt 的规矩,不是本库的发明。

qrc: 与 :/ 是两套写法。 QFile 不认 qrc: scheme,只认 :/。内置示例用 qrc:/samples/ocr_sample.png 打包进二进制,recognizeFile() 里必须做一次映射,否则桌面点“识别内置示例”直接吃 OCR_IO_ERROR。

5.2 桥服务:四百多行里的一个 HTTP 子集

ArkTS 侧 OcrBridgeService 用 @ohos.net.socket 的 TCPSocketServer 监听回环,路由一共三条:

方法路径请求体响应
GET/v1/ping—{"name":"qt-ohos-ocr-bridge","protocol":1,"version":"0.1.0","vision":true}
POST/v1/recognize?source=&language=原始图片字节OcrResult JSON + width/height
POST/v1/pick?language=—结果 JSON 或 {"cancelled":true}

传输规则刻意收窄到最小:HTTP/1.1 over 127.0.0.1:52141、Connection: close、一连接一请求(不搞 keep-alive 状态机)、Content-Length 定界读 body、客户端 20 秒超时。类注释写得很直接:“enough for OCR traffic and trivial to parse on both ends”——为三条路由引入完整 HTTP 栈才是过度设计。

核心解析只有两段。第一段处理“这个方法到底带不带 body”:

// ohos/entry/src/main/ets/ocrbridge/OcrBridgeService.ets(节选)
if (state.contentLength < 0) {
  // GET/HEAD/OPTIONS/DELETE carry no body, and Qt's
  // QNetworkAccessManager does not send Content-Length for them
  // (the GET /v1/ping probe is the important case).
  const method: string = OcrBridgeService.methodOf(headerText);
  if (method === 'GET' || method === 'HEAD' ||
    method === 'OPTIONS' || method === 'DELETE') {
    state.contentLength = 0;
  } else {
    this.respondPlain(client, 411, 'Length Required',
      OcrBridgeService.errorBody('OCR_BRIDGE_BAD_REQUEST',
        'Content-Length is required'));
    return;
  }
}

const total: number = state.bodyStart + state.contentLength;
if (state.received.length < total) {
  return; // wait for the rest of the body
}

第二段把响应写回去——状态行、Content-Length、Connection: close,一个不多一个不少:

// 同上(节选)
const header: string =
  `HTTP/1.1 ${status} ${reason}\r\n` +
  `Content-Type: application/json; charset=utf-8\r\n` +
  `Content-Length: ${bodyBytes.length}\r\n` +
  `Connection: close\r\n` +
  `\r\n`;

两个边界细节要写对:半包——received.length < total 就 return,等下一个 message;头部上限 64 KiB——超了回 431 Request Header Fields Too Large,避免一个坏请求耗尽内存。错误也走同一层封装:{"error":{"code":"OCR_VISION_ERROR","message":"…"}},Qt 侧映射回引擎错误码。取消选图({"cancelled":true})有专属码 OCR_PICKER_CANCELLED,与“选图失败”(OCR_PICKER_ERROR)分开——用户取消不是错误。

为什么不用 keep-alive?OCR 是低频操作,握手开销测不出来;支持 keep-alive 要引入连接复用、半包、超时回收的状态机,代码量翻倍。为测不出的性能写状态机,只会增加维护成本。

5.3 长图:3000 像素、160 像素重叠和一条归属区

长图是这套识别链路里最需要额外处理的部分。Core Vision Kit 的 textRecognition 在设备上很快,但对长图有隐性上限:PC 实测 1242×4800 全量返回;1242×5000 开始丢尾行;1242×6500 只剩几块。长截图、长聊天记录恰恰普遍超过 5000 px。

解法是把高图切成重叠的横向条带分别识别再合并,三个常数决定了切分方式:

// ohos/entry/src/main/ets/ocr/VisionOcr.ets(节选)
/** Maximum strip height handed to a single recognition call (safe on PC). */
const MAX_TILE_HEIGHT: number = 3000;
/** Overlap between two strips; must exceed the tallest text line. */
const TILE_OVERLAP: number = 160;
/** A trailing strip shorter than this is absorbed by the previous one. */
const MIN_TAIL_HEIGHT: number = 600;

// Each line is owned by exactly one strip: the owned range is trimmed
// by half the overlap on both sides, so the same line is never emitted
// twice and no line at a strip boundary is dropped.
const ownedTop: number = region.y + (isFirst ? 0 : TILE_OVERLAP / 2);
const ownedBottom: number = region.y + region.size.height - (isLast ? 0 : TILE_OVERLAP / 2);

关键在归属区(owned range):条带之间重叠 160 px(必须高于最高的文字行,保证跨界行在至少一个条带里是完整的),但每个条带只保留去掉首尾各半个重叠的区间——跨界行只会落在一个条带里,不重不漏。每条认领行带全局 y 坐标,按位置合并回总列表;太短的尾条带(<600 px)会并入前一条,不为三行字多跑一次推理。实测 1242×6500 的长图 140 行全部返回,耗时约 3.5 s。

另一个坑是 init()。Core Vision Kit 需要进程内初始化一次,模拟器上这个 Promise 可能永远 pending,UI 就会一直停在“识别中”。代码用 Promise.race 给了 6 秒上限,失败后把 initPromise 置空允许重试:

// 同上(节选)
private static async ensureInitialized(): Promise<void> {
  if (!canIUse('SystemCapability.AI.OCR.TextRecognition')) {
    throw new Error('Core Vision Kit is not available on this device (1001400001)');
  }
  if (VisionOcr.initPromise === null) {
    VisionOcr.initPromise = textRecognition.init();
  }
  const timeoutMs: number = 6000;
  let ready: boolean = false;
  const timeout: Promise<boolean> = new Promise<boolean>(
    (resolve: (value: boolean) => void): void => {
      setTimeout((): void => resolve(false), timeoutMs);
    });
  ready = await Promise.race([VisionOcr.initPromise, timeout]);
  if (!ready) {
    VisionOcr.initPromise = null;
    throw new Error('Core Vision Kit init returned false (1001400001)');
  }
}

真机上是另一回事:init() 正常,recognizeText 返回行;模拟器上 init() 超时(200),直接调用 recognizeText 返回 1001400001,UI 会明确提示“请用真机”。系统不给的能力,不装作有,也不拿假数据糊过去。

5.4 JSON 契约:第四份实现,逐字节对齐

家族契约到 C++ 这是第四份实现(Kotlin → Dart → ArkTS → C++)。OhosOcrResult::toJson() 不用 QJsonDocument,而是手写字节:字段顺序 id, source, language, fullText, averageConfidence, durationMs, blocks(桥再加 width/height);块之间 ", ";整值浮点保留 .0;转义表与 Kotlin/ArkTS/Dart 一致;代理对不拆:

// src/ohosocrresult.cpp(节选)
QByteArray OhosOcrResult::toJson() const
{
    QList<QByteArray> items;
    for (const OhosOcrBlock &block : m_blocks) {
        items.append(QByteArray("{\"text\":") + jsonQuote(block.text())
                     + ",\"confidence\":" + formatDouble(block.confidence()) + '}');
    }
    QByteArray out;
    out += "{\"id\":";
    out += jsonQuote(m_id);
    out += ",\"source\":";
    out += jsonQuote(m_source);
    out += ",\"language\":";
    out += jsonQuote(m_language);
    out += ",\"fullText\":";
    out += jsonQuote(fullText());
    out += ",\"averageConfidence\":";
    out += formatDouble(averageConfidence());
    out += ",\"durationMs\":";
    out += QByteArray::number(m_elapsedMs);
    out += ",\"blocks\":[";
    out += items.join(QByteArray(", "));      // Kotlin joinToString 的默认分隔符
    out += "]}";
    return out;
}

fromJson 同样手写,规则是“宽松解析 + 严格结构”:未知键(width/height)忽略,块文本 trim,空块丢弃,重复块保留;id 为空、durationMs 为负会被引擎映射成 OCR_BRIDGE_PROTOCOL。elapsedMs 是 C++ 字段名,线上仍写 durationMs——头文件里写明对应关系。

契约不靠注释,靠断言:

// tests/tst_ohosocrresult.cpp(节选)
const QByteArray expected = QByteArray(
    R"json({"id":"vision-on-device","source":"ocr_sample.png","language":"CHINESE","fullText":"门店收银小票\n合计 ¥44.00","averageConfidence":0.0,"durationMs":142,"blocks":[{"text":"门店收银小票","confidence":0.0}, {"text":"合计 ¥44.00","confidence":0.0}]})json");
QCOMPARE(result.toJson(), expected);

toJsonMatchesContractBytes() 直接比对整段字节;另有默认值、全文与平均置信度、转义/emoji、整值浮点、最短往返小数、桥载荷解析、空行/重复行、非法载荷等 8 项。契约一旦写成测试,第四个语言就不用人工对齐。

5.5 上鸿蒙:harmonydeployqt、QAbility 和两行 merge

上鸿蒙这一段,Qt 6 的官方路径是 harmonydeployqt:它把你的应用 .so、Qt 平台插件 libqohos.so、所需 Qt 模块和 QML 模块放进官方 stage 模板,再调用 hvigor 组装 HAP。

# 0) 环境变量(macOS 示例)
export OHOS_SDK_ROOT="<OpenHarmony SDK 路径>"

# 1) 用鸿蒙 Qt 的 qt-cmake 配置 quick 示例
cd examples/quick && mkdir build-ohos && cd build-ohos
<Qt for HarmonyOS 路径>/bin/qt-cmake ..
cmake --build . --parallel

# 2) 触发 harmonydeployqt → hvigor → HAP
cmake --build . --target quick_example_make_hap

QAbility 是载具模板生成的文件,不要替换——只在它生成的生命周期里加两行桥的启停。仓库里的 EntryAbility.ets 已经标好 merge 块:

// ohos/entry/src/main/ets/entryability/EntryAbility.ets(节选)
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
  // ---- qt_ohos_ocr merge block 1/2: start the OCR bridge -------------
  OcrBridgeService.getInstance().start(this.context);
  // ---------------------------------------------------------------------
  // Qt carrier note: keep the carrier template's Qt initialization call
  // here (loading the Qt runtime / your Qt main()).
}

onDestroy(): void {
  // ---- qt_ohos_ocr merge block 2/2: stop the bridge ------------------
  OcrBridgeService.getInstance().stop();
  // Release the process-wide Core Vision Kit service; not awaited.
  VisionOcr.release().catch((): void => {
  });
}

合并清单(与 仓库说明第 7 节、OpenHarmony 示例说明 第 4.2 节一致):

  1. 把 ohos/entry/src/main/ets/ocrbridge/ 与 ohos/entry/src/main/ets/ocr/ 拷进载具 entry 模块的 ets/;
  2. QAbility.onCreate() 首行(qpa.handleAbilityOnCreate(...) 之前)加 OcrBridgeService.getInstance().start(this.context);,onDestroy() 加 stop();
  3. module.json5 的 requestPermissions 加 ohos.permission.INTERNET(system_grant,无弹窗);
  4. 改端口时 OcrBridgeService.start(context, port) 与 Qt 侧 QTOHOS_OCR_ENDPOINT 成对修改;
  5. 想脱离 Qt 单独冒烟,直接跑 examples/ohos-app/。

启动时序是这样的:系统创建 QAbility → 桥开始监听 127.0.0.1:52141 → qpa.setupQtApplication 加载 libquick_example.so 并运行它的 main() → QML 里 probeAvailability() 发 GET /v1/ping,命中 ArkTS 桥 → 识别时 QNAM 把图片原始字节 POST 到 /v1/recognize → ArkTS VisionOcr 调 Core Vision Kit textRecognition.recognizeText → 结果 JSON 原路返回并被解析成 OhosOcrResult。鸿蒙侧看到的仍然是一个 QML 应用——import QtOhosOcr 1.0 照写,变的只是底层窗口从 Cocoa 换成 OHOS、渲染从桌面 GL 换成 GLES,以及多了一条同进程的回环。

手工集成(不用 harmonydeployqt)时,Qt 运行库要进 entry/libs/arm64-v8a/,QML 模块文件(qmldir / .qml / .js,保持模块目录结构)要进 entry/src/main/resources/resfile/qml/——so 走 libs、QML 文件走 resfile,这条双轨制和 Qt 5 时代一样,少一条都 import 失败。

6. 踩坑与经验

以下坑全部来自这次开发的真实报错、代码注释和实测记录。

坑一:Qt 6.8/6.9 官方并不支持鸿蒙。 这两个版本的官方发布说明与支持平台列表里没有 OpenHarmony/HarmonyOS;doc.qt.io 的 HarmonyOS 文档从 Qt 6.12 才开始出现,且自述 technology preview;Qt Wiki 上另有 5.12.12 / 5.15.16 的开源移植版。教训:载具版本以 doc.qt.io / Qt Wiki 的官方记录为准,别拿转载当发布说明。

坑二:textRecognition 只给了 ArkTS 入口,NDK 没有 C++ 接口。 第一反应是写个 C++ 包装,翻了半天头文件才发现 Core Vision Kit 根本没有 NDK/C++ 绑定;N-API 的方向是 ArkTS → C++,不是 C++ → ArkTS。报错不是链接错误,是“这个符号根本不存在”。修复是整条回环桥。教训:先确认系统 API 的调用方向,再决定桥放在哪一层。

坑三:自家桥回了个 411 Length Required。 GET /v1/ping 一直失败,hilog 里是 411 Length Required,错误体 OCR_BRIDGE_BAD_REQUEST: Content-Length is required。原因:QNetworkAccessManager 的 GET 不带 Content-Length,而微型解析器一开始对所有方法都要求长度。修复:GET/HEAD/OPTIONS/DELETE 默认 0,其它方法才回 411。HTTP 子集越小,越要把“谁带 body”写死。

坑四:长图丢尾行,一度以为是识别质量差。 1242×4800 全量返回;1242×5000 开始丢尾行;1242×6500 只剩几块——症状是“识别不全”,原因是图高有隐性上限。修复是 5.3 的重叠条带切分(3000 高度 + 160 重叠 + 归属区裁剪),140 行长图全量返回。“识别不全”先量图高,再怀疑引擎。

坑五:模拟器上 init() 超时,UI 永远停在“识别中”。 2in1 模拟器:textRecognition.init() 返回 code=200 / Run timed out,直接 recognizeText 返回 1001400001 / Failed to run OCR。更糟的是 init 的 Promise 可能一直 pending,busy 永远不落。修复:Promise.race 6 秒超时 + 失败置空允许重试 + 明确提示改用真机。模拟器能验 UI 和桥,验不了端侧 AI。

坑六:buffer.Buffer.buffer 的池化把响应截断了。 ArkTS 侧一开始用 buffer.from(...).buffer 拼响应,设备上会出现 Content-Length 与实际字节数对不上——代码注释原话是 “its pooled backing store makes the byteOffset/length pair inconsistent on device”。修复:用 util.TextEncoder 生成独立的 Uint8Array。跨语言边界上,字节数组必须是“独立的”,不能是别人池子里的一段。

坑七:qrc: 传给 QFile 读不到。 内置示例用 qrc:/samples/ocr_sample.png 打包进二进制,桌面点“识别内置示例”报 OCR_IO_ERROR: cannot read qrc:/samples/ocr_sample.png。QFile 不认 qrc: scheme,只认 :/。修复:recognizeFile() 里 qrc: → : + path。Qt 资源路径有两套写法,跨 API 时要换。

坑八:五个“文件夹”——重复行到底去不去重。 上游 kmp/flutter 的模型要求块文本唯一,会按文本去重;把这张文件管理器截图丢进去时,如果照抄上游的 distinctBy,15 行只剩 11 行,用户看到的行数和原图对不上。修复:OcrModels 的块不去重、fromJson 也不去重(只丢空白行),README 明文写出差异。契约一致不等于语义一致,差异要写在明处。

7. 现在怎么用:从 add_subdirectory 到真机 207 ms

经过上面的整理,这个工程是“Qt 6 CMake 库 + ArkTS 工程壳”双形态交付(版本 0.1.0,MIT)。作为依赖接入两种方式:

# 方式一:add_subdirectory
add_subdirectory(third_party/qt-ohos-ocr)
target_link_libraries(your_app PRIVATE Qt6::Quick qt-ohos-ocr::qt_ohos_ocr)

# 方式二:FetchContent(注意 git 地址用 AtomGit)
include(FetchContent)
FetchContent_Declare(qt_ohos_ocr
    GIT_REPOSITORY https://atomgit.com/oh-tpc/qt-ohos-ocr-lines.git
    GIT_TAG        v0.1.0)
FetchContent_MakeAvailable(qt_ohos_ocr)

宿主检查清单五条:QML 加载前调 qtOhosOcrRegisterQmlTypes();载具 QAbility 合并两个 merge 块;entry 的 module.json5 加 ohos.permission.INTERNET;ocrbridge/ 与 ocr/ 拷入载具;改过端口则两端成对对齐。

两条运行路径:

# 桌面(桥探测失败属预期,UI 与单测照常)
cmake -S . -B build-desktop -DQT_OHOS_OCR_BUILD_EXAMPLES=ON
cmake --build build-desktop
ctest --test-dir build-desktop --output-on-failure
./build-desktop/examples/quick/quick_example

# 桌面看完整结果:模拟桥 + 内置小票 + 截图
python3 tools/mock_bridge.py &
./build-desktop/examples/quick/quick_example --sample --capture preview.png

# 鸿蒙:examples/ohos-app 直接导入 DevEco Studio,签名后运行;
# 接 Qt 则用 Qt for HarmonyOS 的 qt-cmake 配置 examples/quick,
# 再 cmake --build . --target quick_example_make_hap

更完整的 API、协议、错误码与合并步骤在仓库的文档里:

  • 中文主文档(能力边界、Qt for HarmonyOS 支持现状、构建/部署、FAQ);
  • 面向三方库使用者的英文/中文说明;
  • 引擎、模型、传输层与 ArkTS 侧 API;
  • 桥协议、线程模型、错误码总表;
  • 桌面单测、截图、2in1 模拟器与 HAP 构建记录;
  • DevEco 导入、Qt 载具合并、harmonydeployqt 命令;
  • tests/:QtTest 19 项(mock 传输,不需要设备)。

当前版本在 Qt 6.11.0(macOS arm64)与鸿蒙 2in1 上分别验证:QtTest 19 项全绿——契约字节、转义/emoji、整值浮点、最短小数、空行/重复行、忙碌拒绝、空字节、文件读取、IO 错误、选图取消、HTTP 错误映射、传输失败、探测翻转、端点覆写;桌面 Qt Quick 示例经模拟桥返回 7 行 / 186 ms,QML 渲染、复制全文、错误横幅、桥状态均正常;鸿蒙侧 examples/ohos-app 在 2in1 真机上识别一张 1747×584 的文件管理器截图,15 行 / 207 ms,五个 文件夹 原样保留,底部桥状态 protocol 1 · v0.1.0;2in1 模拟器上桥 /v1/ping 正常,但 Core Vision Kit init() 超时(200),应用明确提示改用真机;长图 1242×6500 经条带切分后 140 行全量返回,约 3.5 s。系统 OCR 由 ArkTS 侧调用,Qt 侧经一条 127.0.0.1 的回环取回 JSON;同一行字从像素出发,最后显示在 QML 的列表里。

Logo

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

更多推荐