react-native-vision-superres 为 React Native 鸿蒙应用提供了端侧图像超分与自然语言搜图能力。配套实战项目“本地画质增强与语义相册”(rn-harmony-vision-album)用于低清缩略图四倍放大预览与按画面描述检索本地图集,并在华为畅享 100 Pro Max 真机与 API 26 模拟器上核对超分输出、语义检索耗时及服务异常回退。
配套实战项目已开源在 abaoge/rn-harmony-vision-album,第三方库完整代码已开源在 oh-react-native/react-native-vision-superres,有问题可到第三方库仓库提 Issue,也可以来 鸿蒙系统 React Native 开源社区 交流。

前言

我在用 React Native 开发鸿蒙相册页面“本地画质增强与语义相册”时,遇到了两个具体阻碍:列表里看着还算清楚的 160×160 城堡缩略图,点进详情页放大后屋顶斜边和窗格糊成一片,RN 自带的 <Image> 拉伸只能撑大显示区域,生成不了更高分辨率的图片文件;而相册只保存流水号文件名和修改时间时,想按“城堡夜景”“金色向日葵”这类画面内容找图,也没法直接匹配到名为 1.png 或 2.png 的本地文件。

我借助 react-native-vision-superres 接入鸿蒙 API 26 的 CoreVisionKit,把沙箱短路径转存、原生图像对象释放与检索连接时序收进库里,相册工程通过外部依赖调用。在华为畅享 100 Pro Max 真机的这组记录里,160×160 的城堡图用 485 ms 输出为 640×640 PNG,文件体积也从约 2.8 KiB 增至 421.2 KiB,三组中文查询分别命中对应样图;API 26 模拟器上的两项视觉服务调用返回错误码,页面则退回原图预览与本地关键词匹配。

一、使用场景与真实痛点

1.1 本地相册放大模糊与按画面找图的卡点

📱 在旅行手账、离线壁纸夹或历史缩略图整理这类本地图片页面中,用户常做两件彼此独立的事:挑出分辨率偏低的小图做放大预览,或者输入一句自然语言描述把目标图片从本地图集里筛出来。

只靠 RN 内置的 <Image> 组件拿不到新的高像素文件。无论把 resizeMode 设成什么值,渲染管线只是对原有 160×160 位图做显示区域的采样拉伸,锯齿和模糊边缘仍在原处。想在详情页并排对照更规整的几何边缘,或者把放大结果另存为独立图片,就需要先做一次超分辨率重建再重新编码写盘。本文使用三张自绘样图验证边缘重建与文件输出流程,仅凭这组样图还不能推断真实老照片里丢失的物理纹理能恢复多少。

按内容找图则是另一条路径。应用沙箱或导出的相册图片往往只有流水号文件名,没有人工标签。如果在 RN 业务层自己集成多模态图文模型,不仅要处理模型权重分发、端侧分词器和特征向量存储,还要自己保证应用重启后的索引读写一致。把模型推理与向量索引交给鸿蒙系统的 @kit.CoreVisionKit,跨端库只管路径整理、像素对象回收和并发排队,页面代码会干净很多。

在这个实战相册里,图像超分与自然语言搜图两条功能互不绑定,可以单独调用:看大图时只把当前选中的那张低清图送去四倍超分;找图时直接拿原始图集建立端侧检索索引,不需要先把整组图片放大一遍。

图 1 从相册首页分出两条操作路径。看大图时,用户选中城堡缩略图,点超分后并排看两张图。按画面找图时,先用原图建索引,之后可以直接输入“城堡夜景”检索。

直板手机相册中放大单张照片与按画面描述找图的两条操作路径

图1 相册操作流程

1.2 所用第三方库与实战相册职责分工

📦 本实战项目接入的通用第三方库为 oh-react-native/react-native-vision-superres(版本 0.1.0,鸿蒙原生模块名 @rnoh/react-native-vision-superres,MIT 许可),配套相册工程托管在 abaoge/rn-harmony-vision-album。库内不包含任何相册业务素材,只保留一个八十余行的最小接口调用示例;完整的深色相册卡片、切图防错位与异常降级交互都放在独立实战工程里。系统底座、通用三方库与实战相册三层各自承担的职责如下:

架构层次所属模块核心职责与边界
鸿蒙系统层@kit.CoreVisionKit、ImageKit、CoreFileKit提供 ImageSRAnalyzer 四倍超分与 textSearchImage 端侧文搜图推理,负责位图编解码与沙箱文件读写
通用三方库react-native-vision-superres(@rnoh/react-native-vision-superres)封装能力探测、128 字符/字节短路径原子转存、超分尺寸预检与逆序句柄释放、文搜图串行队列与初始化代次锁
独立实战层rn-harmony-vision-album通过外部依赖接入通用库,负责样图导入、超分左右对比面板、切图预览归属校验、中文短语检索及关键词回退

表1 三层职责划分

二、真机与模拟器运行效果

2.1 运行条件与验证顺序

我把独立实战工程 rn-harmony-vision-album 编译打包后,在真机上按“启动探测 → 短路径导入 → 四倍超分 → 写入索引 → 三次中文检索 → 仅释放连接”的顺序走完一轮操作,并在 API 26 直板手机模拟器上执行同样操作观察服务报错时的页面降级表现。实测环境与样本参数见表 2:

项目实测环境与参数
RN / RNOH 基线React Native 0.84.1 / @rnoh/react-native-openharmony 0.84.6
所用通用三方库oh-react-native/react-native-vision-superres 0.1.0(@rnoh/react-native-vision-superres)
独立实战工程rn-harmony-vision-album 1.0.0(通过外部 Git 依赖标准挂载)
SDK / 系统版本HarmonyOS SDK API 26 / OpenHarmony 7.0.0.105(DevEco Studio 26.0.0.865)
真机与模拟器华为畅享 100 Pro Max(YEW-AL80)USB 投屏;Mate 90 Pro 模板 API 26 arm64-v8a 模拟器
验证图集与参数城堡 160×160(2.8 KiB),向日葵与灯塔各 320×320(14.8 KiB / 15.0 KiB);scope 为 album01,topKey 为 10

表2 运行条件

下面这段 10.5 秒动图把真机上的相册首页、超分对照、三次查询命中与释放连接共六张结果画面按操作顺序串联展示:

相册首页、超分、三次检索与释放结果轮播

图2 真机结果轮播

这组真机数据记录的是单轮操作耗时与文件体积变化,没有做多轮均值统计,也没有测试上千张实拍照片建库或 PSNR、SSIM 等客观画质指标。

2.2 短路径导入与静态能力探测

打开“画质增强与语义相册”首页后,主屏上方提供“画质增强 / 按画面找图”分段切换,横向陈列像素夜景城堡、晴空金色向日葵等样图缩略卡,下方为原图与 4× 增强后 的同框预览区;页面启动时会自动调用 getCapabilities() 读取设备 SDK 版本与路径预算,并调用 stageRawfileImage() 把宿主自带的三张 PNG 样图转存到沙箱的 vs 短目录(点击右上角“运行详情”可查看底层路径与调用日志)。

真机实战相册清爽首页与四倍超分对比待命区

图3 相册首页

在运行详情面板中核对路径信息,真机应用沙箱根路径长 39 个字符,拼上 /vs/1.png 后全长 48 个字符(纯 ASCII 路径下字符数与字节数一致),远低于 128 上限。三张样图校验尺寸、写临时文件、原子重命名并释放解码器,合计耗时 7 ms。

面板里的“超分就绪 · 搜图就绪”只反映系统 API 版本达到 26 且具备 SystemCapability.AI.Vision.VisionBase 静态系统能力;底层视觉服务在当前设备上能不能真正跑通推理,仍要以每次调用返回的 ok 与 errorCode 为准。

2.3 低清城堡图的四倍超分对照

选中 160×160 的城堡缩略图并点击“执行图像超分”后,相册把原图和 ImageSRAnalyzer 输出的新图左右并排展示,方便直接对比屋顶斜边、黄色窗格与月牙轮廓。

真机低清城堡图四倍超分对照

图4 超分对照

真机返回错误码 0,图像分辨率从 160×160 增至 640×640,宽高各放大四倍 🟢↑;输出的 PNG 文件体积从 2862 B 增至 431297 B 🟢↑(约 2.8 KiB 增至 421.2 KiB,界面简记为 KB)。并排查看时,塔楼阶梯斜边比直接拉伸原图更规整,但由于像素总面积扩大到原来的十六倍,无损 PNG 占用的存储空间也明显增加。

面板记录的 485 ms 为原生超分方法内部耗时,包含读取文件头宽高、位图解码、创建超分分析器、模型推理、PNG 编码落盘以及淘汰旧缓存,计时终点在 finally 释放句柄之前,不含前端组件渲染图片的时间。与其他缩放方案横向对比时,需要先对齐这一计时口径。

2.4 自然语言文搜图入库与三次检索

接着点击“写入文搜图索引”,相册逐张调用 insertSearchImage(sandboxPath, 'album01') 提取特征入库,随后在同一作用域依次检索“城堡夜景”“金色向日葵”与“海洋灯塔”。结果见表 3:

操作或查询词处理或首条命中文件相似度分值原生耗时
写入三张相册原图索引1.png、2.png、3.png(3/3 成功)—1640 ms
城堡夜景命中 1 张:1.png(像素夜景城堡)0.370017 ms
金色向日葵命中 1 张:2.png(晴空金色向日葵)0.340915 ms
海洋灯塔命中 1 张:3.png(海洋雪峰灯塔)0.328022 ms

表3 建库与查询

真机检索城堡夜景命中结果

图5 城堡检索

真机检索金色向日葵命中结果

图6 向日葵检索

真机检索海洋灯塔命中结果

图7 灯塔检索

可以看到,建索引耗时(1640 ms)远高于单次查询耗时(15~22 ms)。实际相册接入时应记录每张图片的入库状态,只对新增照片做后台增量入库,避免每次搜索前重复入库。同时,这三次命中的相似度分值落在 0.3280~0.3700 之间——它代表图文跨模态特征余弦距离得分而非分类准确率,如果前端误设“大于 0.8 才展示”的硬阈值,正确结果反而会被全部过滤掉。

2.5 仅释放连接回执与应用日志

相册底部提供了“仅释放句柄”与“清空全库索引并释放”两个独立按钮。点击“仅释放句柄”后,releaseTextSearch() 返回成功,耗时 16 ms,下方日志区按时间倒序保留了导入、超分、建库、检索和释放的调用记录。

真机释放连接回执与应用内调用日志

图8 释放与日志

releaseTextSearch() 只断开当前视觉服务会话连接,已经建好的相册向量索引仍留在应用数据目录中,下次进入页面可直接查询;只有当用户主动点击重置索引时,才需要调用清空底层数据库的接口。

2.6 API 26 模拟器服务异常与本地关键词回退

💻 我将同一个 HAP 安装到 Mate 90 Pro 模板的 API 26 模拟器上执行相同操作:三张样图正常转存进短路径,但超分与文搜图调用均返回服务异常错误码,页面自动切换到原图保留与本地标题、描述关键词匹配。

模拟器文搜图失败后回退本地关键词匹配

图9 模拟器回退

下面这段约 15 秒的动图记录了模拟器窗口中点击超分、入库、检索与释放的连续响应过程:

模拟器超分、入库、检索与释放的连续操作

图10 模拟器操作

真机与模拟器在同一套代码下的运行结果对照见表 4:

检验环节真机记录(畅享 100 Pro Max)模拟器复测记录
静态能力探测ok=true,状态 readyok=true,状态 ready
三张样图短路径转存7 ms,路径长 48(≤128)10 ms,路径长 48(≤128)
城堡图四倍超分485 ms,输出 640×640 PNG6 ms,返回错误码 1018700001
写入文搜图索引1640 ms,3/3 入库成功9 ms,0/3 成功,返回错误码 1013100002
仅释放服务连接16 ms,released=true未建立底层连接,直接返回 released=true(0 ms)

表4 运行环境对照

🔍 查看同次模拟器操作的系统 HiLog,可以看到文搜图初始化阶段连接底层算法能力服务失败的记录:

I AI_TEXT_SEARCH_IMAGE: [(GetAlgorithmVersion)]Received version info: {"errorMsg":"Failed to connect to capability for version info","resultCode":402}
E AI_TEXT_SEARCH_IMAGE: [(InitOnce)]TextSearchImage::InitOnce GetAlgorithmVersion failed, version.empty

模拟器虽然满足 API 26 与 VisionBase 静态系统能力,但镜像里没有预置对应的端侧视觉推理服务,公开接口直接返回 1018700001 与 1013100002。此时页面的关键词回退只能匹配已有文字描述,不能替代真实语义检索,但能保证无模型设备上页面不白屏、操作不卡死。

三、原理与核心代码分析

3.1 分层调用架构与相册切图防错位

通用库通过 RNOH TurboModule 连接 JS 与鸿蒙 ArkTS 原生层:原生侧把执行耗时、输出路径、错误码等字段序列化为 JSON 字符串返回,库的鸿蒙入口统一反序列化,并在宿主漏挂载模块或桥接抛错时兜底返回 { ok: false } 结构化对象,业务页面无需到处重复写 try/catch 和 JSON.parse()。

相册经 JS 包装层与 ArkTS 模块调用鸿蒙系统能力并返回结构化结果

图11 调用架构

单张图像超分的处理顺序和文搜图会话的调用流程

图12 调用流程

如图 11、图 12 所示,超分是单张图片的短事务(预检尺寸 → 解码位图 → 四倍推理 → 编码 PNG → 逆序释放句柄),而文搜图复用跨调用存活的系统服务会话。在实战相册 App.tsx 中,用户点击超分后如果趁着几百毫秒的推理等待期立刻切换到另一张图片,迟到的超分结果很容易把上一张的大图贴到新图右侧造成图文错位。为此相册在发起超分前先快照目标图片信息,并在返回时核对归属:

  // 调用通用库执行端侧 4x 图像超分,若推理期间用户已切换原图则丢弃过期回写
  const handleRunSuperRes = useCallback(async () => {
    if (!selectedPhoto) {
      appendLog('请先导入本地相册图集');
      return;
    }
    // 发起推理前先快照当前选中图片的 ID 与短路径,供异步返回时核对归属
    const targetId = selectedPhoto.id;
    const targetPath = selectedPhoto.sandboxPath;
    setBusyAction('sr');
    try {
      const res = await VisionSuperres.runSuperResolution(targetPath, targetId);
      if (!mountedRef.current) {
        return;
      }
      // 推理期间若用户已切到别的图片,丢弃旧结果,防止左右对比窗格图文错位
      if (selectedIdRef.current !== targetId || res.inputPath !== targetPath) {
        appendLog(`已忽略旧选中图(${targetId})的在途超分回写,避免覆盖当前图片预览`);
        return;
      }
      setSrResult(res);
      if (res.ok) {
        appendLog(
          `超分成功: ${res.inputWidth}×${res.inputHeight} -> ${res.outputWidth}×${res.outputHeight} (${res.elapsedMs} ms)`,
        );
      } else {
        appendLog(`超分返回错误(${res.errorCode}): ${res.errorMessage}`);
      }
    } catch (err) {
      appendLog(`超分调用异常: ${String(err)}`);
    } finally {
      if (mountedRef.current) {
        setBusyAction('');
      }
    }
  }, [appendLog, selectedPhoto]);

配合切换缩略图时同步清空旧 srResult,以及渲染层通过 albumHelpers.ts 中的 isMatchingSrPreview 二次比对 srResult.inputPath === selectedPhoto.sandboxPath,就能避免快速切图时出现预览串图。

3.2 沙箱短路径原子转存与超分资源回收

textSearchImage 要求传入的 imagePath 长度不超过 128 个字符,库还额外加上了 UTF-8 编码不超过 128 字节的保守预算,防止深层目录加上多字节中文文件名后越界。通用库为此提供了两个转存入口:宿主自带资源走 stageRawfileImage(按 Uint8Array 的 byteOffset 与 byteLength 精确截取有效字节视图写入),系统选图器拷贝进沙箱的长路径图片则走下面的 stageSandboxImage:

  /** 将沙箱长路径或 file:// URI 图像校验后转存至 <filesDir>/vs/ 短路径(满足 128 字符限制与字节预算) */
  async stageSandboxImage(sourcePath: string, shortFileName: string): Promise<string> {
    const t0 = Date.now();
    const cleanSource = this.normalizeSandboxPath(sourcePath);
    // 剥离 file:// 后先确认目标是普通文件,防止误传目录或空路径
    if (cleanSource.length === 0 || !this.safeIsRegularFileSync(cleanSource)) {
      return this.buildStageFailure(cleanSource, t0, -1, `源沙箱图片不存在或不是普通文件: "${cleanSource}"`);
    }

    let tempPath = '';
    try {
      const target = this.resolveShortTargetPath(cleanSource, shortFileName);
      if (!target.ok) {
        return this.buildStageFailure(cleanSource, t0, -1, target.errorMessage);
      }
      // 先解码校验宽高合法,避免损坏图片写进短目录或覆盖原有同名文件
      const imgSize = await this.readImageDimensions(cleanSource);
      if (cleanSource !== target.dstPath) {
        this.stageSequence += 1;
        // 先复制到临时副本再原子重命名,避免写入中途失败留下半截目标图
        tempPath = `${target.workDir}/.tmp_${this.stageSequence}_${target.shortFileName}`;
        fileIo.copyFileSync(cleanSource, tempPath);
        fileIo.renameSync(tempPath, target.dstPath);
        tempPath = '';
      }
      return this.buildStagedSuccess(cleanSource, target.shortFileName, target.dstPath, imgSize, t0);
    } catch (err) {
      if (tempPath.length > 0 && this.safeAccessSync(tempPath)) {
        try {
          fileIo.unlinkSync(tempPath);
        } catch (_unlinkErr) {
          // 忽略临时副本清理异常
        }
      }
      const parsed = this.extractError(err as BusinessError);
      return this.buildStageFailure(cleanSource, t0, parsed.errorCode, parsed.errorMessage);
    }
  }

计算目标文件名时,resolveShortTargetPath 还做了三层保护:一是自动命名时附加八位源路径十六进制摘要减少同名碰撞,若字节预算紧张则优先完整保留 .png 等文件扩展名;二是若调用方传入的短名以超分缓存前缀 sr_ 开头,自动改写为 in_ 前缀,防止原图被超分缓存淘汰逻辑误删;三是失败时只清理本次生成的 .tmp_ 临时文件,不破坏已有的目标图片。

进入超分执行链路后,原生模块在 srQueue 串行队列内先用 ImageSource.getImageInfo() 检查宽高是否落在 ImageSRAnalyzer 要求的 (16, 2048) 开区间(即 17~2047 像素),尺寸合法才解码分配可编辑的 RGBA_8888 PixelMap,避免超大图白占几十兆图形内存。无论推理成功还是写盘中途抛错,最终都会在 finally 中按“关闭文件描述符 → 释放 ImagePacker → 释放输出与输入 PixelMap(防同引用二次释放)→ 释放 ImageSource → 销毁 ImageSRAnalyzer”的逆序逐项独立回收句柄,前一项释放异常不会阻断后续回收。

3.3 文搜图串行队列与初始化代次锁

文搜图最容易踩中的竞态出在页面快速进出:用户刚点进相册触发入库或搜索,textSearchImage.init() 还在异步等待系统连接返回,用户就退出页面触发了 releaseTextSearch()。如果不加协调,要么释放先跑完后迟到的 init() 又把状态翻回已就绪,要么状态虽被重置但刚建好的底层连接却漏调 release()。

我在原生模块中用 textSearchQueue 串行化所有文搜图操作,用递增的 textSearchEpoch 标记生命周期代次,并把“业务可继续查询(textSearchInitialized)”与“底层连接已建立(textSearchConnected)”拆成两个独立布尔值:

  /** 在串行锁内统一初始化 textSearchImage,并在异步返回后校验生命周期代次防止释放竞态 */
  private async ensureTextSearchInitialized(expectedEpoch: number): Promise<InitGuardStatus> {
    if (this.destroyed) {
      return { ok: false, errorCode: -1, errorMessage: 'RNVisionSuperres 实例已销毁,已拒绝新建连接' };
    }
    if (expectedEpoch !== this.textSearchEpoch) {
      return { ok: false, errorCode: -1, errorMessage: 'textSearchImage 服务已释放,取消在途初始化' };
    }
    if (this.textSearchInitialized) {
      return { ok: true, errorCode: 0, errorMessage: '' };
    }

    try {
      const ready = await textSearchImage.init();
      // 先记录底层连接是否建立,供队尾排队的 release 任务准确判断是否需要关闭会话
      this.textSearchConnected = ready;
      // 初始化等待期间若页面已调释放使代次递增,禁止把业务状态重新翻回就绪
      if (this.destroyed || expectedEpoch !== this.textSearchEpoch) {
        this.textSearchInitialized = false;
        return { ok: false, errorCode: -1, errorMessage: 'textSearchImage 初始化期间被释放,已拦截后续请求' };
      }
      this.textSearchInitialized = ready;
      if (!ready) {
        return { ok: false, errorCode: -1, errorMessage: 'textSearchImage.init() 返回 false' };
      }
      return { ok: true, errorCode: 0, errorMessage: '' };
    } catch (err) {
      // 初始化抛错时同步清零双标记,保留下次调用重新尝试建连的机会
      this.textSearchInitialized = false;
      this.textSearchConnected = false;
      const parsed = this.extractError(err as BusinessError);
      return { ok: false, errorCode: parsed.errorCode, errorMessage: parsed.errorMessage };
    }
  }

调用 releaseTextSearch() 时,模块先递增 textSearchEpoch 让排队中的旧请求失效,再把释放动作排进串行队列末尾。即使前面的 init() 刚刚连上系统服务,textSearchConnected 也已如实记为 true,轮到队尾释放任务执行时仍能准确调到底层 release() 收回会话。此外,增删查途中若捕获到服务断连异常,模块会自动清空连接标记,让下一次调用重新尝试初始化;RN 实例整体销毁时,__onDestroy__() 也会标记销毁并排队释放连接。

四、踩坑与边界条件

4.1 路径字节预算与检索参数范围

🔍 鸿蒙应用沙箱根目录(如 /data/storage/el2/base/haps/entry/files)本身已占去 39 字节,业务自选图片若拼上多层子目录或中文长文件名,很容易触碰 128 字符或 128 字节上限。接入自有图库时,统一先调 stageSandboxImage 转存并取返回的 sandboxPath 入库最稳妥;需严格区分不同业务图片时,建议调用方显式传入自管的唯一短文件名。

文搜图的检索作用域 scope 只接受 1~32 位英文字母或数字,带下划线或连字符(如 my_album)会被参数校验直接拦截,改用 album01 这类纯字母数字即可,且入库、查询与单图删除必须传入同一个 scope。查询条数 topKey 有效范围为 1~100,库内部已对非有限数或小于 1 的值归整为默认 10,超过 100 则截断为 100。

4.2 超分临时输出淘汰与持久化保存

💣 四倍超分输出的是体积较大的无损 PNG。为避免 RN <Image> 因路径不变命中旧图缓存,库给每次超分输出生成带递增序号的 sr_{tag}_{seq}.png,并只滚动保留最近十二份临时输出(清理时逐条独立捕获文件状态异常,不因并发删除中断)。

因此 runSuperResolution 返回的 outputPath 只适合当场预览。如果用户点击“保存到相册”或准备拿放大后的图片建立长期检索索引,业务层应先将该文件复制到自己的持久化目录,不要把随时可能在第 13 次超分时被淘汰删除的临时路径直接写入业务数据库。

4.3 仅释放连接与清空全库的边界

⚠️ 官方接口中的 textSearchImage.release() 只断开当前服务连接,而 textSearchImage.clearData() 会一次性清空当前应用名下的全部文搜图索引,且不按 scope 过滤。

初版调试时我曾误把清空接口放进页面卸载回调,结果退出一次相册就把刚建好的索引全部清零。日常退出页面或切换路由时只能调用 releaseTextSearch();只有用户在设置页主动点击“重置全部离线索引”并二次确认后,才调用 clearAndReleaseSearch()(冷启动尚未建连就直接重置时,库内部会自动先补做一次初始化再执行清库)。

4.4 自动化测试覆盖与设备支持边界

我在通用库中保留了十八项自动化测试(含包契约与开源合规检查、非鸿蒙回退与纯 ESM 加载测试,以及十项基于系统接口替身与真实临时目录的并发代次、尺寸预检、十二份缓存淘汰与紧字节预算保留扩展名测试);独立相册工程另配五项测试校验外部依赖挂载、isMatchingSrPreview 切图归属判断及 filterPhotosByLocalKeywords 本地关键词排序。替身测试用于锁定异步时序与异常收尾顺序,不能代替端侧模型推理。

当前成功路径实测基于华为畅享 100 Pro Max(OpenHarmony 7.0.0.105,API 26 真机),服务异常与降级回退基于同版本 API 26 直板手机模拟器;Android 与 iOS 仅提供返回 { ok: false } 的同构降级入口。不同鸿蒙机型或固件是否内置对应视觉模型,接入时需以目标真机首次调用的实际回执为准。

五、结论与可直接复用的建议

5.1 安装官方三方库与宿主原生挂载

💡 如果你的 React Native 鸿蒙项目需要低清图四倍放大预览或本地图集自然语言检索,可在 RN 0.84.1 与 @rnoh/react-native-openharmony 0.84.6 宿主工程根目录安装官方社区三方库 oh-react-native/react-native-vision-superres(版本 0.1.0);想直接对照并排预览、切图防错位与关键词降级界面,可参考配套实战项目仓库 abaoge/rn-harmony-vision-album。

npm install "git+https://atomgit.com/oh-react-native/react-native-vision-superres.git"

在鸿蒙工程 harmony/entry/oh-package.json5 中映射本地原生模块依赖:

{
  "dependencies": {
    "@rnoh/react-native-openharmony": "0.84.6",
    "@rnoh/react-native-vision-superres": "file:../../node_modules/react-native-vision-superres/harmony/vision_superres"
  }
}

发布的包已在 ets/generated 与 cpp/generated 中附带生成好的 TurboModule 胶水代码,宿主无需运行库的生成脚本,只需核对三处原生接线并执行 ohpm install 即可编译运行:

  1. 在 harmony/build-profile.json5 的 modules 中挂载 vision_superres 模块(路径指向 ../node_modules/react-native-vision-superres/harmony/vision_superres);
  2. 在宿主 RNPackagesFactory.ets 与 PackageProvider.cpp 中导入并注册 RNVisionSuperresPackage;
  3. 在宿主 CMakeLists.txt 中添加 vision_superres 的 C++ 子目录,并将 rnoh_vision_superres 链接到 rnoh_app。

5.2 带注释的最短接入调用示例

接入后可直接按 TypeScript 类型读取返回对象,下面给出包含长路径转存超分、增量入库检索与页面退出安全释放的最短调用代码:

import VisionSuperres, {
  type SuperResolutionResult,
  type TextSearchResult,
} from 'react-native-vision-superres';

// 1. 将选图器读入沙箱的图片原子转存为 ≤128 字符短路径,再执行 4× 超分
export async function enhancePhoto(sourceUri: string, shortName: string): Promise<SuperResolutionResult> {
  const staged = await VisionSuperres.stageSandboxImage(sourceUri, shortName);
  if (!staged.ok) {
    throw new Error(`短路径转存失败(${staged.errorCode}): ${staged.errorMessage}`);
  }
  const sr = await VisionSuperres.runSuperResolution(staged.sandboxPath, 'album');
  if (!sr.ok) {
    throw new Error(`超分失败(${sr.errorCode}): ${sr.errorMessage}`);
  }
  return sr;
}

// 2. 将短路径图片写入指定字母数字作用域,并按自然语言描述检索
export async function searchAlbum(shortPath: string, query: string, scope = 'album01'): Promise<TextSearchResult> {
  const ins = await VisionSuperres.insertSearchImage(shortPath, scope);
  if (!ins.ok) {
    throw new Error(`索引写入失败(${ins.errorCode}): ${ins.errorMessage}`);
  }
  // 页面卸载时只需调 VisionSuperres.releaseTextSearch() 关闭连接,切勿误调全库清空
  return VisionSuperres.searchImagesByText(query, scope, 10);
}

5.3 生产接入核对清单

  • 选图与短路径配合:先通过鸿蒙 PhotoViewPicker 获取用户选图并拷入应用沙箱,再交给 stageSandboxImage 转存到短目录。
  • 增量管理索引:记录已入库图片避免重复提取特征,删除照片时同步调用 deleteSearchImage,并用自有样本实测相似度分布后再定筛选规则。
  • 按真实回执降级:遇到 1018700001 或 1013100002 等服务异常时保留原图预览并回退到本地标题或文件名匹配。

小结

做完这个相册项目,小图放大边缘发虚和流水号图片没法按画面查找这两个问题都落了地:真机完成了 160×160 到 640×640 的四倍超分输出与 15~22 ms 的中文短语搜图,缺少视觉服务的模拟器也能按错误回执退回原图预览与本地关键词匹配。回头看整个接入过程,把静态系统能力标记和每次调用的真实返回码分开检查,再把短路径预算、像素句柄逆序回收与初始化代次锁收进库里,页面频繁切换时才不容易出乱子。🎉

参考资料

Logo

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

更多推荐