把 419×600 的图拉到 1676×2400,Canvas 一行就够;难的是让补出来的像素看起来像真的。这篇文章用一个跑在 HarmonyOS 7 真机上的 Cordova 插件,把选图、4 倍超分、落盘和 1:1 对比这条链路拆开讲。

仓库地址:https://atomgit.com/oh-tpc/cordova-ohos-ai-vision
版本地址:https://atomgit.com/CPF-Cordova
三方库框架:https://atomgit.com/oh-tpc

0. 环境与实测设备

三方库适配信息:

三方库Cordova 版本鸿蒙化版本仓库地址社区社区地址
cordova-ohos-ai-visionv14.0.22.1.0(26)https://atomgit.com/oh-tpc/cordova-ohos-ai-vision(生态收录:https://atomgit.com/oh-tpc)CPF-Cordova 鸿蒙社区https://atomgit.com/CPF-Cordova

说明:插件以 AtomGit 仓库为分发源,没有发布到 npm registry。cordova plugin add cordova-ohos-ai-vision 这类裸包名安装不到东西,安装方式见第 7 节。

实测环境:

项版本/型号
DevEco Studio内置 SDK(HarmonyOS 26.0.0 / API 26),内置 hvigor 6.26.4
Cordovav14.0.2(CLI 13.0.0 实测)
cordova-ohos14.0.2(26),CPF-Cordova 鸿蒙社区适配
hcordova CLI1.0.7(HarmonyOS 平台管理,CPF-Cordova 鸿蒙社区提供)
cordova-ohos-ai-vision 插件2.1.0(本仓库,JS 桥 + ArkTS 原生插件)
构建链Node.js 24.12.0,TypeScript 5.9.3,esbuild 0.25.x
测试Vitest 3.2.7 + jsdom 26.1.0(37 项单测)
实测设备HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26
WebViewArkWeb(Chromium 内核)
超分模型Core Vision Kit imageSuperResolution,API 26 起,固定 4×
权限无(相册 / 文件选择器与超分模型均不需要声明权限)

这里要先把一个限制写在前面:这个模型只有 HarmonyOS 7(API 26)及以上才有,模拟器上没有可用的模型实例,真实效果必须在真机上点一次。低版本设备不会"降级成插值",而是直接报 UNSUPPORTED,插件也不会把它报成可用。

1. 超分不是"放大"

先把结果放这儿:一张 419×600 的森林照片,进插件,出来一张 1676×2400、920.3 KB 的 JPEG,耗时 344 ms。数字不夸张,但把原图和结果放到 1:1 像素下对比,差别不是"变大",是"边缘接上了"。

我最早对超分的理解很朴素:放大不就是插值吗?419×600 到 1676×2400,Canvas 的 drawImage 一行就能做,最近邻、双线性、Lanczos 随你挑。我在页面上先做了一个 4× 插值参照放在左边——结果很清楚:像素变多了,信息没变多。树叶的边缘是一圈软边,草地上的噪点被一起放大,树皮的纹理被插值抹得发糊。

这就是"超分"和"放大"的分界线。插值只能根据周围像素猜一个平滑值;超分模型要先判断"这里大概率是一条边、一撮草、一块树皮",再把高频补出来。补出来的像素不是原始照片里真实存在的那几个,是模型认为合理的细节——这一点在讲边界时还会提到。

项目也不是从零开始的。它上一版是 cordova-ohos-ocr,把 Core Vision Kit 的文字识别接进了 Cordova。OCR 跑通之后,我顺着 @kit.CoreVisionKit 往下翻,看到 imageSuperResolution:API 26 起,固定 4 倍,端侧,不需要权限。对 Cordova 来说,这正好是另一个"WebView 里做不到、系统里现成有"的能力。

于是题目变成:把系统超分模型包装成一个可复用的 Cordova 插件,输入是一张图,输出是一个真实文件 + 一组可验证的元数据。具体拆三件事:

  • 选图:系统相册和系统文件选择器怎么接、取消怎么归一化;
  • 超分:解码尺寸怎么卡、模型怎么调、结果怎么编码落盘、内存怎么放;
  • 过桥:文件路径、尺寸、字节数、耗时和四张预览图怎么安全地回到 WebView。

下面是干完之后的记录,包括几次把目录撑爆、把预览读出黑块的现场。

2. 效果展示

先看效果。

在这里插入图片描述

这是 OhosVisionDemo 在 HUAWEI MateBook Pro S 上的实机截图。画面已经滚到结果区,所以顶部的"图像超分"标题和三块 facts 不在图里;那三块写的是"4× 长宽各放大 4 倍 / 端侧 Core Vision Kit 本机推理 / 0 无需申请权限"。从"从相册选择 / 从文件选择"开始往下,是一次完整运行。截图里的森林图是测试素材,不是用户相册里的私人照片。

左边"原图"是 419×600,标注"相册图片 · 419 × 600 px";右边"超分结果"是 1676 × 2400 px、920.3 KB。两张整图缩略都缩到长边 432,所以看起来一样大——这是故意的。整图缩略只用来看构图,判断 4 倍效果得看下面的"细节对比 · 1:1 像素"。

细节区的左图是输入中心区域放大 4 倍的参照,caption 写"插值放大 4×(参考)“;右图是模型输出的同一区域原始像素,caption 写"模型输出 1:1”。同一片树荫下,左边草地的边缘是一格一格的,右边草叶的边界更连续,树皮上的亮部也没有被插值糊成一团。这个差别不是靠把图片拉大看出来的,是把两边都放在 1:1 像素下才看得到。

这里要克制一点:模型不是把原图"恢复"了,它是在合理的范围内补细节。树皮和草地的边缘更连续,噪点更少;但如果你拿它去放大一张带小字的截图,字形不会凭空变清楚,甚至可能被抹平。后面第 3 节会把这条边界说清楚。

再看一张更干净的对照。这张输入只有 360×240,输出 1440×960,文件 295.1 KB,耗时 225 ms:
在这里插入图片描述

左边是最近邻 4× 的参照,右边是模型输出。路的边缘、岩壁的纹理、远处那辆小车,右边都比左边更"连",左边则保留着明显的方块。另一次 360×245 的输入是 201 ms、79.0 KB;这个量级的图在 MateBook 上就是几百毫秒的事,第一次加载模型会稍慢,页面在按钮上写了"正在超分…(首次加载模型较慢)"。这张对比图用的是公开示例照片,不是用户相册里的图。

同一份页面在浏览器里打开是另一幅样子:环境标签"浏览器 · 仅预览",状态"未连接",按钮只会打开本地文件选择框,选完显示文件名、原图尺寸和"仅预览"状态,不会生成任何超分结果。原因很简单——浏览器里没有 imageSuperResolution,页面也不会用 Canvas 造一个假结果。这个"没有就不提供"的规则,在后面 NATIVE_UNAVAILABLE / UNSUPPORTED 的分支里还会出现。

交互细节都在:能力探针返回前按钮是 disabled 的;探针分 native 和 supported 两层,宿主里有插件但设备低于 API 26 时,页面显示"设备不支持",按钮仍然可以预览本地文件;选图期间按钮文案变成"正在打开相册…“,超分期间变成"正在超分…(首次加载模型较慢)”;取消选择只提示"已取消选择。",不报错;失败时状态变红,hint 里是原生错误原文;底部"诊断"折叠面板里是 capabilities() 和本次结果的 JSON。

结果区下面四个格子分别是放大倍数、耗时、输出文件、编码,再下面一行是落盘路径:

/data/storage/el2/base/haps/entry/files/super-resolution/sr-1794576925456-849.jpg

注意它在应用沙箱里,不在系统相册。页面没有"保存到相册"按钮,这不是漏做:写相册需要 SaveButton 安全控件或媒体权限,属于宿主应用的交互设计,插件只负责把文件写到它能写的地方,并把路径返回。

3. 4 倍之后,像素从哪来:一次超分的六段链路

写代码之前先把原理理清。

一次 4× 超分从用户点按钮开始,到页面拿到 output.path 结束,中间是六段:

第 0 段:选图。 相册用 photoAccessHelper.PhotoViewPicker,文件用 picker.DocumentViewPicker。两者都返回 URI:相册是 file://media/...,文件是 file://docs/...。这一步不需要权限,因为选择器本身就是授权边界——用户选了哪张,应用才能读哪张。

第 1 段:打开。 URI 不能直接传给 image.createImageSource,先用 fileIo.openSync(uri, READ_ONLY) 拿到 fd。fd 是原生侧的文件句柄,后续解码、读尺寸都靠它。

第 2 段:解码。 createImageSource(fd) 建解码器,getImageInfo() 读原始尺寸,按 maxInputEdge 等比缩小,再 createPixelMap({ RGBA_8888, desiredSize }) 解成位图。注意这一步不是"把原图读进来随便放",解码尺寸直接决定了模型需要的内存。

第 3 段:超分。 imageSuperResolution.ImageSRAnalyzer.create() 建分析器,process({ inputData: { pixelMap } }) 返回 ISPResponse.pixelMap,长宽各是输入的 4 倍。模型一次只处理一张图,且同一进程内同一特性不支持并发;分析器按次创建、finally 里 destroy()。

第 4 段:落盘。 image.createImagePacker() + packToFile(outputPixelMap, fd, { format, quality }) 把结果写成 JPEG 或 PNG。写完先 closeSync,再 statSync 拿字节数;顺序不能反,原因见第 6 节坑五的黑块。

第 5 段:预览与回传。 原图和输出各缩到长边 432 做整图缩略;再从输出中心裁一块 720×480 的 1:1 细节,把输入对应区域放大 4 倍做参照。四张图都是 JPEG data URL,随结果通过 successByJson 回到 JS;JS 侧把扁平字段组装成 input / output / preview,页面渲染。

完整链路:

用户点「从相册选择」
      │
      ▼  系统 UI(PhotoViewPicker / DocumentViewPicker)
file://media/... 或 file://docs/...
      │  fileIo.openSync(uri, READ_ONLY) → fd
      ▼
image.createImageSource(fd)
      │  getImageInfo → 长边 > maxInputEdge 时等比缩小
      ▼
createPixelMap({ RGBA_8888, desiredSize })
      │
      ▼  ImageSRAnalyzer.create()
analyzer.process({ inputData: { pixelMap } })
      │  ISPResponse.pixelMap(宽高 ×4)
      ▼
imagePacker.packToFile(outputPixelMap, fd, { format, quality })
      │  closeSync → statSync → bytes
      ▼
整图缩略 432 / 细节 1:1 720×480 → data:image/jpeg;base64,...
      │  successByJson({ uri, source, inputWidth, ..., detailAfter })
      ▼
parseSuperResolutionResult → 页面渲染(对比图 + 尺寸 + 字节数 + 耗时 + 路径)

这条链路里没有网络请求,也没有模型下载。Core Vision Kit 的模型是系统自带的;插件不申请权限,也不把原图复制到别处——原图只被打开一次 fd,解码两次:一次给模型,一次给 432 的缩略图。浏览器、Android、iOS 上 JS 桥仍然可用,但没有 OhosVision 服务,所有接口以 NATIVE_UNAVAILABLE 拒绝,不会用 Canvas 放大一张糊图当作结果。

3.1 内存预算:默认 1280 的依据

模型固定放大 4 倍,内存要按面积算,是 16 倍,不是 4 倍:

  • 输入 419×600,输出 1676×2400;RGBA_8888 下输出位图约 1676×2400×4 ≈ 16 MB;
  • 默认 maxInputEdge = 1280,4:3 输入 1280×960,输出 5120×3840,约 5120×3840×4 ≈ 78 MB;
  • 如果把 maxInputEdge 拉到 2560,输出长边 10240,10240×7680×4 ≈ 314 MB,还要加上输入位图、ImageSource、编码器和预览的临时对象,低内存设备很难承受。

所以默认值定在 1280,而不是"越大越好"。这个数字不是模型的要求,是插件替你做的内存预算;真要放大更大的原图,先把 maxInputEdge 调到 2048 左右,盯着设备内存和耗时再往上加。

3.2 性能数据:344 ms 花在哪

截图里 419×600 的图用了 344 ms,这个数字是整条链路的耗时:init/create、解码、推理、编码、预览都算在内,不是单独一次推理。360×240 和 360×245 的两次分别是 225 ms、201 ms;文件大小受画面复杂度影响很大,360×240 的岩石图 295.1 KB,360×245 的另一张只有 79.0 KB。

成本主要在三处:模型创建(首次加载更慢)、4 倍推理、JPEG 编码。预览是长边 432 的小图,成本可以忽略;1:1 细节图也只有 720×480,编码量不大,耗时最多的是模型推理和最终整图的编码。插件把这些事放在一次原生调用里做完,页面只等一个 Promise。

3.3 边界:它是"重建",不是"复原"

把 4× 超分能做什么、不能做什么摆在一起:

路径4× 之后代价
Canvas drawImage像素被插值拉开,边缘更糊零依赖,零新信息
WebGL 锐化 / 边缘增强边缘看起来利一点要写 shader,仍不是生成模型
WASM ESRGAN 之类真模型,细节可能更好模型体积、WebView 内存、CPU 时间
云超分质量上限可能更高图片出设备、网络、费用、排队
Core Vision Kit(本库)系统模型,端侧 4×API 26+,固定 4×,不能并发

它适合:老照片、低分辨率自然图像、照片类截图放大看、给 UI 做一张更清晰的预览图。它不适合:纯文字截图、取证、医学影像、把模糊的车牌"变清楚"、把不存在的文字"补"出来。模型补的是统计上合理的细节,不是事实;这一点不因为页面上的 4× 数字而改变。

4. 工程怎么搭:一个插件,两份代码,三类产物

先看整体结构。Demo 跑通之后,我把它整理成了标准的 Cordova 插件:根目录是可复用的 package(com.lqjmac.cordova.ohosvision),演示应用退到 example/,浏览器演示留在 demo/。

cordova-ohos-ai-vision/                  # 插件根目录(plugin.xml,v2.1.0)
├─ src/                                  # TypeScript 桥接(纯浏览器 JS)
│  ├─ native.ts                          # exec 封装、能力探针、UNSUPPORTED 判定
│  ├─ superresolution.ts                 # 选图 / 超分 / 选项校验
│  ├─ result.ts                          # 扁平载荷 → 嵌套结果、JSON 序列化
│  ├─ version.ts                         # 版本号(与 package.json 同步)
│  └─ index.ts                           # window.OhosVision 的公共对象
├─ www/ohos-vision.js                    # esbuild 产物,Cordova 直接加载
├─ types/                                # tsc 生成的 .d.ts
├─ ohos/                                 # ArkTS 原生插件
│  ├─ SuperResolution.ets                # 选择器、解码、超分、编码、预览(465 行)
│  └─ OhosVisionPlugin.ets               # 动作分发、串行队列、错误回传(225 行)
├─ __tests__/                            # Vitest(jsdom),37 项
├─ demo/                                 # 浏览器直开演示(与宿主共用 CSS/JS)
├─ example/                              # Cordova-OHOS 宿主(OhosVisionDemo)
│  ├─ config.xml                         # com.lqjmac.ohosvision.host
│  ├─ www/                               # 由 demo/ 同步而来
│  └─ harmonyos/                         # hcordova 生成的 ArkTS 工程
├─ docs/                                 # 架构、验证记录、安装校验、对比图
├─ scripts/                              # build / sync-example / screenshot
├─ plugin.xml                            # js-module + ohos source-file + feature
├─ CHANGELOG.md
└─ README.md / README.OpenHarmony.md / README.OpenHarmony_CN.md

在这里插入图片描述

这次整理的关键,是把"能跑"拆成"能复用":

  • src/ 只依赖标准 Web API 和 cordova.exec,不依赖任何宿主全局;native.ts 管探针和超时,superresolution.ts 管选图与超分,result.ts 管载荷,三件事不搅在一起;
  • ohos/ 是两个纯 ArkTS 文件,只依赖系统 Kit 和 @cordova-ohos/ohos,不碰页面;选择器、解码、模型、编码、预览、释放都在这一层闭环;
  • www/ohos-vision.js 是唯一 JS 交付物,tsc --noEmit + esbuild 一条命令产出,产物里没有 CSS、没有模板、没有 canvas、没有运行时依赖;www 随仓库提交,hcordova plugin add 后无需再构建;
  • demo/ 与 example/www/ 共用 CSS/JS,npm run sync:example 只改一个 <link> 和两个 <script> 的引用,避免三份页面各改各的;
  • 文档目录里除了架构和验证记录,还保留了一张 360×240 → 1440×960 的 1:1 对比图,说明模型到底做了什么。

和纯 JS 插件不同,这次有两份代码、三类产物:JS 桥(www/ohos-vision.js)、类型声明(types/*.d.ts)、被拷贝进宿主 entry 模块的 ArkTS(ohos/*.ets)。插件清单里三样都要声明:

<!-- plugin.xml(节选) -->
<js-module src="www/ohos-vision.js" name="OhosVision">
    <clobbers target="OhosVision" />
</js-module>

<platform name="ohos">
    <js-module src="www/ohos-vision.js" name="OhosVision">
        <clobbers target="OhosVision" />
    </js-module>

    <source-file type="ets" src="ohos/SuperResolution.ets"
        target-dir="src/main/ets/plugins/ohosvision" modules-name="entry" />
    <source-file type="ets" src="ohos/OhosVisionPlugin.ets"
        target-dir="src/main/ets/plugins/ohosvision" modules-name="entry" />

    <config-file target="src/main/resources/rawfile/config.xml" parent="/*">
        <feature name="OhosVision">
            <param name="ohos-package"
                value="entry/src/main/ets/plugins/ohosvision/OhosVisionPlugin.ets" />
        </feature>
    </config-file>
</platform>

这里有两个硬约束,提前写在这里比事后报错强:

  • 宿主 compatibleSdkVersion 必须是 26.0.0。SuperResolution.ets 静态 import 了 API 26 才有的 imageSuperResolution,低于 26 的 SDK 编译不过;
  • modules-name="entry" 假定宿主模块名是 entry,不同工程要改成实际模块名。

hcordova plugin add 时,安装器做三件事:把 www/ohos-vision.js 用 cordova.define(...) 包一层,拷进 rawfile/www/plugins/cordova-ohos-ai-vision/,并更新 cordova_plugins.js;把两个 .ets 拷进 entry/src/main/ets/plugins/ohosvision/;往 rawfile/config.xml 插入 <feature name="OhosVision">。

还有一步自动化不了:ArkTS 插件是按 webview 注册的,必须在宿主的 Index.ets 里显式把插件对象传给 MainPage:

// entry/src/main/ets/pages/Index.ets(节选)
import { MainPage, PluginEntry, pageBackPress, pageHideEvent, pageShowEvent } from '@cordova-ohos/ohos/Index';
import { OhosVisionPlugin } from '../plugins/ohosvision/OhosVisionPlugin';

@Entry
@Component
struct Index {
  cordovaPlugs: Array<PluginEntry> = [
    { pluginName: 'OhosVision', pluginObject: new OhosVisionPlugin() }
  ];

  onPageShow() {
    pageShowEvent();          // 页面显示通知 cordova
  }

  onBackPress() {
    pageBackPress();          // 返回键由 cordova 处理
    return true;
  }

  onPageHide() {
    pageHideEvent();          // 页面隐藏通知 cordova
  }

  build() {
    RelativeContainer() {
      MainPage({ cordovaPlugs: this.cordovaPlugs });
    }
    .height('100%')
    .width('100%')
  }
}

pluginName 必须和 <feature name="OhosVision"> 一模一样,否则 cordova.exec 会报 Class not found。三个生命周期回调属于 Cordova 宿主的固定约定,不是超分专用:页面显示/隐藏要通知 cordova,返回键由它处理。

宿主链路长这样:

Cordova-OHOS 宿主(ArkUI EntryAbility)
  └─ ArkWeb WebView(Chromium 内核)
      ├─ cordova.js + cordova_plugins.js                ← 平台框架注入
      ├─ plugins/cordova-ohos-ai-vision/www/ohos-vision.js ← 安装时拷入 rawfile
      └─ window.OhosVision                                ← js-module clobber 到 window
          ├─ capabilities() → cordova.exec('OhosVision', 'engineInfo')
          └─ superResolve(uri, options)
              └─ ArkTS OhosVisionPlugin → SuperResolution → Core Vision Kit

对使用方来说,最终看到的 API 是这样的:

document.addEventListener('deviceready', async () => {
  const capabilities = await window.OhosVision.capabilities();
  if (!capabilities.native) {
    console.warn(capabilities.detail);     // 浏览器 / 未注册插件
    return;
  }
  if (!capabilities.supported) {
    console.warn('需要 HarmonyOS 7(API 26)及以上');
    return;
  }

  const uri = await window.OhosVision.pickImage();     // 取消 → null
  if (uri !== null) {
    const result = await window.OhosVision.superResolve(uri, {
      quality: 92,
      format: 'jpeg',
      maxInputEdge: 1280,
    });
    console.log(result.input.width, '→', result.output.width); // 419 → 1676
    console.log(result.output.path, result.output.bytes);
    preview.src = result.preview.after;
  }
});

注意这里没有任何"演示结果"分支:native 为 false、supported 为 false 时,页面唯一正确的做法是把原因显示出来。页面启动走 5.7 的 cordova/channel 写法,避开 deviceready 的粘性竞态。

构建侧做了双挂载。scripts/build.mjs 用 esbuild 把 src/index.ts 打成单文件 IIFE,footer 同时写 module.exports 和 window.OhosVision:

// scripts/build.mjs - footer(节选)
var __OhosVision__ = OhosVisionBundle.OhosVision;
if (typeof module !== "undefined" && module.exports) { module.exports = __OhosVision__; }
if (typeof window !== "undefined") { window.OhosVision = __OhosVision__; }

Cordova 的 cordova.define 包装走 module.exports,浏览器直开 demo/index.html 走 window 挂载——同一条产物两条路都能用。demo/ 不需要 Cordova 运行时就能验证页面本身,只是超分会被明确拒绝。

5. 把代码讲透

下面把插件内部拆开讲:两个选择器、一段解码、一次模型调用、一次落盘、一组预览、一层 exec 桥,再加上宿主的接线。代码都取自 ohos/SuperResolution.ets、ohos/OhosVisionPlugin.ets 和 src/,不是伪代码。

5.1 选图:两个系统选择器,一条归一化路径

相册选择器只有十几行:

// ohos/SuperResolution.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/SuperResolution.ets - pickImageFile()
const options: picker.DocumentSelectOptions = new picker.DocumentSelectOptions();
options.maxSelectNumber = 1;
options.fileSuffixFilters = ['.png', '.jpg', '.jpeg', '.bmp', '.webp', '.heic'];
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/superresolution.ts 的 readUri 把它读出来,pickImage / pickImageFile 再归一化成 null——调用方只需要判断 null,不用理解空串的约定。选图超时单独放宽到 120 秒,因为用户完全可能在相册里翻很久。

5.2 解码:先把输入按到 maxInputEdge 之内

超分前必须把图片解成 PixelMap。这一段是整个原生侧最需要小心的地方:

// ohos/SuperResolution.ets - enhanceImage()(节选)
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 ratio: number = longest > normalized.maxInputEdge ? normalized.maxInputEdge / longest : 1;
const inputSize: image.Size = {
  width: Math.max(1, Math.round(info.size.width * ratio)),
  height: Math.max(1, Math.round(info.size.height * ratio)),
};
const decoded: image.PixelMap = await source.createPixelMap({
  editable: true,
  desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
  desiredSize: inputSize,
});
inputPixelMap = decoded;

三个决定值得单独说:

先读尺寸再解码。 getImageInfo() 只读元数据,不分配位图;拿到宽高之后才决定 desiredSize。如果先按原图解码再缩放,12 MP 的图会先占用 48 MB,缩放只是把峰值推迟,不是消除。

maxInputEdge 是模型的输入上限。 它不改变模型的 4 倍,只决定输入长边。419×600 的原图低于 1280,不会被缩,输出就是 1676×2400;一张 4000×3000 的原图会先缩到 1280×960,输出 5120×3840。只有长边超过 1280 的输入才会被压到 5120 附近,低于 1280 的图按原尺寸 ×4。

editable: true + RGBA_8888。 模型要的是可读写的 RGBA 位图;editable 让解码器返回可写位图,RGBA_8888 是超分接口期望的像素格式。两个都写死,避免不同解码器给出只读或压缩格式时,问题到 process() 里才暴露。

5.3 模型:create、process、destroy,一次都不能漏

模型调用本身很短,约束主要在生命周期:

// ohos/SuperResolution.ets - enhanceImage()(节选)
analyzer = await imageSuperResolution.ImageSRAnalyzer.create();
const imageData: visionBase.ImageData = { pixelMap: decoded };
const request: visionBase.Request = { inputData: imageData };
const response: imageSuperResolution.ISPResponse = await analyzer.process(request);
outputPixelMap = response.pixelMap;

const outputInfo: image.ImageInfo = await outputPixelMap.getImageInfo();
const outputWidth: number = outputInfo.size.width;
const outputHeight: number = outputInfo.size.height;

analyzer 按次创建,finally 里 destroy():

} finally {
  // ... 先释放 outputSource / outputFile / packer / outputPixelMap
  if (analyzer !== null) {
    try {
      await analyzer.destroy();
    } catch (error) {
      // Releasing must never hide a super-resolution error.
      console.warn('ImageSRAnalyzer destroy failed');
    }
  }
  // ... 再释放 inputPixelMap / source / file
}

几个要命的细节:

模型是 API 26 才有的。 isSupportedOnDevice() 先看 deviceInfo.sdkApiVersion >= 26,再看 canIUse('SystemCapability.AI.Vision.VisionBase')。前者是硬门槛,后者是因为少数设备有框架但没有视觉栈;最终答案还是 ImageSRAnalyzer.create(),它加载不了模型时会抛 1018700001。

// ohos/SuperResolution.ets - isSupportedOnDevice()
export function isSupportedOnDevice(): boolean {
  try {
    if (deviceInfo.sdkApiVersion < MIN_API_VERSION) {
      return false;
    }
  } catch (error) {
    return false;
  }
  try {
    return canIUse('SystemCapability.AI.Vision.VisionBase');
  } catch (error) {
    return false;
  }
}

一次请求只处理一张图。 process() 的 inputData 就是一个 pixelMap;没有批量接口。插件不做批量,也不缓存输入。

同一进程内同一特性不支持并发。 两个 enhance 同时跑,设备侧会报 Service exception;OhosVisionPlugin 用一条 Promise 链把超分串行化(见 5.6)。

分析器不跨调用缓存。 每次 create()、每次 destroy(),模型句柄不留在插件里。代价是首次/每次加载的开销,好处是页面随时可以发起新调用,不会因为上一次异常留下一个状态异常的分析器。

5.4 落盘:packToFile、closeSync、statSync,顺序不能反

模型只返回 PixelMap,不写文件、不建相册记录。落盘是插件自己的事。enhance 入口会先取 hostContext();取不到就直接拒绝(无法获取应用上下文,无法写入超分结果),不会带着 undefined 去拼 filesDir。

// ohos/SuperResolution.ets - enhanceImage()(节选)
const directory: string = ensureOutputDirectory(context);
pruneOutputs(directory);
const isPng: boolean = normalized.format === 'image/png';
const path: string = `${directory}/${outputName(isPng ? 'png' : 'jpg')}`;

packer = image.createImagePacker();
outputFile = fs.openSync(
  path,
  fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY | fs.OpenMode.TRUNC,
);
await packer.packToFile(outputPixelMap, outputFile.fd, settings);
fs.closeSync(outputFile);
outputFile = null;
const outputBytes: number = fs.statSync(path).size;

settings 是 { format: normalized.format, quality: normalized.quality },其中 normalized.format 是 image/jpeg 或 image/png 的 MIME,不是结果里的 'jpeg' / 'png'。这两个表示在 JS 和原生之间换了一次,后面 5.6 会说。

输出目录是 context.filesDir + '/super-resolution',文件名是 sr-<时间戳>-<0..999 随机数>.<jpg|png>:

function outputName(extension: string): string {
  const stamp: number = Date.now();
  const salt: number = Math.floor(Math.random() * 1000);
  return `sr-${stamp}-${salt}.${extension}`;
}

时间戳保证排序,随机数避免同一毫秒内两次调用撞名。pruneOutputs() 在写新文件之前跑,按文件名排序,删到只剩 12 个 sr-*;因为时间戳等长,字典序就是时间序。

这里有个小的 off-by-one:pruneOutputs() 是在写新文件之前调用的,所以目录里最多是 12 个旧文件 + 当前这个,实际最多 13 个,而不是 仓库说明里写的严格 12 个。要精确 12 个,把 pruneOutputs() 移到写完之后再调一次;现在这样写,至少不会让目录无限增长。

5.5 预览与 1:1 细节:为什么整图缩略看不出 4 倍

第一版只回传两张整图缩略,页面上并排一放,几乎一模一样。原因很简单:两张都缩到长边 432,看起来当然一样大。整图缩略只能看构图,不能看模型改了什么。

2.1.0 补了 1:1 细节。先看整图缩略的生成:

// ohos/SuperResolution.ets - previewFromSource()
const info: image.ImageInfo = await source.getImageInfo();
const longest: number = Math.max(info.size.width, info.size.height);
const ratio: number = longest > PREVIEW_EDGE ? PREVIEW_EDGE / longest : 1;
const size: image.Size = {
  width: Math.max(1, Math.round(info.size.width * ratio)),
  height: Math.max(1, Math.round(info.size.height * ratio)),
};
const pixelMap: image.PixelMap = await source.createPixelMap({
  desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
  desiredSize: size,
});
try {
  return await encodePixelMap(packer, pixelMap, PREVIEW_QUALITY);
} finally {
  await pixelMap.release();
}

细节对比是另一段:

// ohos/SuperResolution.ets - enhanceImage()(节选)
const detailWidth: number = Math.min(outputWidth, DETAIL_MAX_WIDTH);   // 720
const detailHeight: number = Math.min(outputHeight, DETAIL_MAX_HEIGHT); // 480
const detailX: number = Math.floor((outputWidth - detailWidth) / 2);
const detailY: number = Math.floor((outputHeight - detailHeight) / 2);

// 右图:模型输出中心区域的原始像素
const afterRegion: image.Region = {
  x: detailX,
  y: detailY,
  size: { width: detailWidth, height: detailHeight },
};
await outputPixelMap.crop(afterRegion);
detailAfter = await encodePixelMap(packer, outputPixelMap, DETAIL_QUALITY);

// 左图:输入对应区域先裁小,再放大 4 倍作参照
const cellWidth: number = Math.max(1, Math.floor(detailWidth / 4));
const cellHeight: number = Math.max(1, Math.floor(detailHeight / 4));
const beforeRegion: image.Region = {
  x: Math.floor(detailX / 4),
  y: Math.floor(detailY / 4),
  size: { width: cellWidth, height: cellHeight },
};
await inputPixelMap.crop(beforeRegion);
await inputPixelMap.scale(4, 4);
detailBefore = await encodePixelMap(packer, inputPixelMap, DETAIL_QUALITY);

左边不是模型结果,是"输入裁一块再放大 4 倍"的参照;右边才是模型输出。两张都用 JPEG quality 82,输出尺寸上限 720×480,放进 data URL 后不会把结果 JSON 撑爆。整图缩略用 quality 72、长边 432,只用于看构图。

为什么不直接把 output.uri 塞进 <img>?WebView 对 file:// 的支持因内核而异,data URL 是最稳的展示方式;全分辨率结果留在磁盘上,页面拿到的只是预览和路径,不会把一张 1676×2400 的图塞进 JS 字符串。

黑块的问题就出在这段附近:packToFile 写完后如果立刻 image.createImageSource(path) 读回,真机上右上角会出现一块黑色——数据还没完全落盘。修复方式很直接:

await packer.packToFile(outputPixelMap, outputFile.fd, settings);
fs.closeSync(outputFile);       // 先关 fd,再读回
outputFile = null;

把 closeSync 放在 createImageSource(path) 之前,黑块消失。2.1.0 的 CHANGELOG 里记的就是这一条。

5.6 选项、参数与串行队列

选项只有三个:quality(1–100,默认 92)、format(jpeg / png,默认 jpeg)、maxInputEdge(256–2560,默认 1280)。JS 侧的选择是拒绝非法值,不静默夹取:

// src/superresolution.ts - normalizeEnhanceOptions()
const quality = options?.quality ?? DEFAULT_ENHANCE_OPTIONS.quality;
if (typeof quality !== 'number' || !Number.isInteger(quality) || quality < 1 || quality > 100) {
  throw new OhosVisionError('INVALID_ARGUMENT', 'quality 必须是 1–100 的整数');
}

const format = options?.format ?? DEFAULT_ENHANCE_OPTIONS.format;
if (format !== 'jpeg' && format !== 'png') {
  throw new OhosVisionError('INVALID_ARGUMENT', `format 只支持 'jpeg' 或 'png',收到 ${String(format)}`);
}

const maxInputEdge = options?.maxInputEdge ?? DEFAULT_ENHANCE_OPTIONS.maxInputEdge;
if (
  typeof maxInputEdge !== 'number' ||
  !Number.isInteger(maxInputEdge) ||
  maxInputEdge < 256 ||
  maxInputEdge > 2560
) {
  throw new OhosVisionError('INVALID_ARGUMENT', 'maxInputEdge 必须是 256–2560 的整数');
}

原生侧再做一次夹取,防的是绕过 JS 直接手写 cordova.exec 的调用:

// ohos/SuperResolution.ets - normalizeOptions()
let quality = 92;
let format = 'image/jpeg';
let maxInputEdge = DEFAULT_MAX_INPUT_EDGE;
if (options !== undefined) {
  quality = clamp(options.quality, 1, 100);
  if (options.format === 'image/png') {
    format = 'image/png';
  }
  maxInputEdge = clamp(options.maxInputEdge, 256, 2560);
}
return { quality, format, maxInputEdge };

为什么参数是四个原始值(uri, quality, format(MIME), maxInputEdge),而不是一个 options 对象?因为 ArkTS 侧读 ESObject 属性是不受检的。手写 cordova.exec 时把 enhance 的参数塞成 [{ quality: 'x' }],也能进解码路径;四个原始值逐个 typeof 判断,再走 normalizeOptions(),至少能保证类型和范围:

// ohos/OhosVisionPlugin.ets - readOptions()
if (args.length > 1 && typeof args[1] === 'number') {
  quality = args[1] as number;
}
if (args.length > 2 && typeof args[2] === 'string') {
  format = args[2] as string;
}
if (args.length > 3 && typeof args[3] === 'number') {
  maxInputEdge = args[3] as number;
}

最后是并发。OhosVisionPlugin 里有一条 Promise 链:

private chain: Promise<void> = Promise.resolve();

private handleEnhance(args: ESObject[], callbackContext: CallbackContext): void {
  // ... 取 uri、hostContext、readOptions
  const task = (): Promise<void> => {
    return enhanceImage(uri, context, options)
      .then((result: SuperResolutionResult) => {
        callbackContext.successByJson(resultPayload(result));
      })
      .catch((error: Error) => {
        sendError(callbackContext, describeError(error));
      });
  };
  this.chain = this.chain.then(task);
}

task 自己把错误转发给 JS,所以链上不会留下 rejected Promise;后一次调用永远等前一次 settle 后再进模型。代价是连续点两次会排队,好处是不会触发"同一特性不支持并发"的 Service exception。

5.7 过桥、载荷与页面启动

src/native.ts 的 execNative 和 OCR 版是同一套:一次性 settle、超时、同步异常兜底。

// 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 OhosVisionError('NATIVE_UNAVAILABLE', NO_CORDOVA));
      return;
    }

    let settled = false;
    const timer = setTimeout(() => {
      if (settled) return;
      settled = true;
      reject(new OhosVisionError('NATIVE_TIMEOUT', `OhosVision.${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 OhosVisionError('NATIVE_ERROR', asFailure(message)));
    };

    try {
      cordova.exec(succeed, fail, SERVICE, action, args);
    } catch (error) {
      fail(error instanceof Error ? error.message : error);
    }
  });
}

超时分三个:探针 1.5 秒、选图 120 秒、超分 240 秒。超分给 240 秒,是因为第一次加载模型 + 大图 + 编码可能叠在一起,给足余量比"超时了但文件还在写"好。

能力探针失败后 3 秒内不重复探测,成功一次就缓存;并发调用共用同一个 pendingProbe:

// 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;
}

页面启动时 capabilities() 可能被调两次(deviceready 一次、3 秒兜底一次),这个缓存避免两次都发 engineInfo;失败后 3 秒又能升级到原生,覆盖"页面脚本早于 deviceready"的情况。

四个原生动作就是桥的全部约定:

动作参数成功载荷
engineInfo—{ platform, engine, bridge, visionKit, apiVersion, sdkApiVersion, supported, scale }
pickImage—{ uri },取消时为空串
pickFile—{ uri },取消时为空串
enhanceuri, quality, format(MIME), maxInputEdge扁平的超分结果(inputWidth、outputPath、previewAfter…)

能力探针除了 native,还多了一层 supported:

// src/native.ts - requireSuperResolution()
export async function requireSuperResolution(): Promise<NativeInfo> {
  const native = await requireNative();
  if (!native.supported) {
    const version = native.sdkApiVersion > 0 ? `(当前 API ${native.sdkApiVersion})` : '';
    throw new OhosVisionError(
      'UNSUPPORTED',
      `当前设备不支持图像超分${version}:需要 HarmonyOS 7(API 26)及以上,且设备具备 Core Vision Kit 视觉能力`,
    );
  }
  return native;
}

native 为 false 是"没有插件",native 为 true 但 supported 为 false 是"有插件、设备不够"。两个状态分开,页面才能给出不同的提示;测试里用 API 12 的探针返回验证了这一点,并且确认 enhance 根本没被调用。

原生返回的是扁平对象,JS 侧组装成嵌套结果:

// src/result.ts - parseSuperResolutionResult()
const record = toRecord(payload, '超分结果');
const format = readString(record, 'format', true);
if (format !== 'jpeg' && format !== 'png') {
  throw new OhosVisionError('INVALID_PAYLOAD', `超分结果的 format 不受支持:${format}`);
}
return {
  uri: readString(record, 'uri', true),
  source: readString(record, 'source', true),
  input: {
    width: readNumber(record, 'inputWidth', 1),
    height: readNumber(record, 'inputHeight', 1),
  },
  output: {
    uri: readString(record, 'outputUri', true),
    path: readString(record, 'outputPath', true),
    width: readNumber(record, 'outputWidth', 1),
    height: readNumber(record, 'outputHeight', 1),
    bytes: readNumber(record, 'outputBytes', 0),
    format,
  },
  scale: readNumber(record, 'scale', 0.01),
  durationMs: readNumber(record, 'durationMs', 0),
  preview: {
    before: readString(record, 'previewBefore', false),
    after: readString(record, 'previewAfter', false),
    beforeDetail: readString(record, 'detailBefore', false),
    afterDetail: readString(record, 'detailAfter', false),
  },
};

readString(..., true) 对空串直接抛 INVALID_PAYLOAD;预览字段允许空,因为原生侧编码失败时会给 '',页面据此隐藏对应的图,而不是显示一个加载失败的图标。source 不是页面传的,是原生按 URI 前缀打的标签:file://media → 相册图片,file://docs → 文件图片,其余 → 图片。

resultToJson() 是给需要落盘或转发的调用方用的,字段顺序固定,转义是手写的:

// src/result.ts - jsonQuote()(节选)
switch (code) {
  case 0x22:
    out += '\\"';
    break;
  case 0x5c:
    out += '\\\\';
    break;
  case 0x0a:
    out += '\\n';
    break;
  case 0x0d:
    out += '\\r';
    break;
  case 0x09:
    out += '\\t';
    break;
  default:
    if (code < 0x20) {
      out += `\\u${code.toString(16).padStart(4, '0')}`;
    } else {
      out += text.charAt(index);
    }
}

结果里有沙箱路径、data URL 和中文来源标签,手写转义主要是为了让输出稳定、可断言,字段顺序固定;测试里有一条完整的精确字符串断言,另有一条专门覆盖引号、反斜杠和控制字符。

结构化结果继续走 successByJson / errorByJson。原因和 OCR 版一样:Cordova-OHOS 的 EVAL 桥把 successByString 原样拼进 cordova.callbackFromNative(...) 的 JS 源码,JSON 里的 \n 会变成实际的换行,JSON.parse 直接失败。第 6 节还会展开。

页面启动用的是粘性 deviceready + 3 秒兜底:

// demo/app.js(节选)
if (!window.cordova) {
  startBoot(false);
} else {
  var subscribed = false;
  try {
    var channel = window.cordova.require && window.cordova.require('cordova/channel');
    if (channel && channel.onDeviceReady) {
      channel.onDeviceReady.subscribe(function () {
        startBoot(true);          // 强制重探:插件可能刚注入
      });
      subscribed = true;
    }
  } catch (error) {
    subscribed = false;
  }
  if (!subscribed) {
    document.addEventListener('deviceready', function () { startBoot(true); }, false);
  }
  window.setTimeout(function () {
    startBoot(false);
  }, 3000);
}

startBoot(true) 会强制重探(capabilities(true));3 秒兜底用普通探针,避免重复请求。浏览器里没有 window.cordova,直接 startBoot(false),页面会如实显示"浏览器 · 仅预览"。

6. 踩坑与经验

以下是这次改造和真机验证中实际遇到的坑。

坑一:插件静态 import 了 API 26 的模块,宿主 SDK 还停在 20。 第一次把插件装进旧宿主,ArkTS 直接报找不到 imageSuperResolution——不是运行时,是编译期。SuperResolution.ets 顶部 import { imageSuperResolution, visionBase } from '@kit.CoreVisionKit',这个声明只在 API 26 SDK 里有;宿主 compatibleSdkVersion 必须改成 26.0.0,targetSdkVersion 也要对齐。教训:插件的能力边界要写进宿主构建配置,不能只写在 仓库说明里。

坑二:hcordova 从仓库根目录装插件,复制出 11 GB。 改造过程中 example/package.json 曾声明 cordova-ohos-ai-vision: file:..,npm 在 example/node_modules/cordova-ohos-ai-vision 建了一个指回仓库根的软链接。之后对仓库根执行 hcordova plugin add <repo>,安装器按目录复制,顺着软链接把整个仓库(包括 example/node_modules 里的自身)反复复制,实测生成了 11 GB 的嵌套目录,最后报 ENAMETOOLONG。清理掉这个自引用依赖后,编译验证改成直接复制 ohos/*.ets;安装则用 git 地址或仓库外的副本。教训:插件仓库里放 example,example 又反向依赖插件,hcordova 的目录复制会把这个环走成死循环。

坑三:successByString 回传 JSON,页面只拿到半截文本。 第一版在 ArkTS 里 callbackContext.successByString(JSON.stringify(payload)),结果里有 \n、' 和中文路径。桥把字符串原样拼进 cordova.callbackFromNative(...) 的 JS 源码,\n 变成实际的换行,JSON.parse 直接抛 Unexpected token;带 ' 的路径还会截断语句。修复:所有结构化结果改 successByJson,JS 侧仍然兼容对象和 JSON 字符串两种输入。教训:在 Cordova-OHOS 上,JSON 只能走 JSON 通道,不能塞进字符串通道。

坑四:整图缩略两边一模一样,看不出 4 倍。 第一版只回传 preview.before / preview.after,两边都缩到长边 432。页面上并排一放,构图完全相同,用户根本看不出模型做了什么。2.1.0 补了 beforeDetail / afterDetail:右侧从输出中心裁 720×480 原始像素,左侧裁输入对应区域再放大 4 倍作参照。现在页面上的"细节对比 · 1:1 像素"才是有效证据。教训:对比图必须让两边处在同一像素尺度,整图缩略只能证明"图还在",不能证明"模型有用"。

坑五:packToFile 之后立刻读回,右上角一块黑。 写完文件马上 image.createImageSource(path) 读回做整图预览,真机上预览右上角会出现一块黑色,换几张图都一样。原因不是编码失败,是文件还没完全落盘,读回时解码到了未写入的区域。修复:packToFile 后先 fs.closeSync(outputFile),再 createImageSource(path);outputFile 置 null,finally 里不会重复关。教训:写完文件先关 fd,再读回;文件系统不是内存,await 不等于落盘。

坑六:模拟器上模型根本不存在。 页面能加载,capabilities() 返回 native: true,相册也能拉起,但一超分就失败。Core Vision Kit 的超分模型不支持模拟器,ImageSRAnalyzer.create() 拿不到可用实例;换成 HUAWEI MateBook Pro S 后一次通过。教训:native: true 只说明插件注册成功,supported 也只是粗判,create() 才是设备侧的最终答案。

坑七:真机签名,bundleName 和旧 profile 对不上。 仓库不提交 signingConfigs;真机拒绝 unsigned HAP。本机 本机 DevEco 签名配置 里只有一份绑定了旧 bundleName com.lqjmac.ohosocr.host 的 debug profile,直接套到新工程会在 SignHap 阶段报 00303074(bundleName 与 SigningConfigs 不匹配)。临时把 AppScope/app.json5 的 bundleName 指回旧值完成签名安装,跑完再改回来;正式做法是在 DevEco 里打开 example/harmonyos,重新生成自动签名。教训:签名材料绑 bundleName 和设备 UDID,换工程名不能直接复用旧证书。

坑八:两次超分并发,设备报 Service exception。 两个 superResolve 撞在一起(比如页面逻辑没等第一次返回,或者两个 webview 同时调用),第二次还没等第一次结束就进了 process(),设备侧报 Service exception。API 明确写了同一特性不支持并发;修复是 OhosVisionPlugin 里那条 Promise 链,把 enhance 串起来。教训:系统能力的"不支持并发"不是建议,是硬约束;桥接层要把队列做掉,别把错误丢给页面。

坑九:options 用对象传,ArkTS 侧读属性不受检。 第一版 enhance 的参数是一个 options 对象,ArkTS 里 options.quality 直接读,手写 cordova.exec 传 { quality: 'high' } 也能进解码路径,最后在原生路径里才暴露。改成四个原始值(uri, quality, format, maxInputEdge),逐个 typeof 判断,再走 normalizeOptions() 夹范围;JS 侧先做一次严格校验,非法值直接 INVALID_ARGUMENT。教训:跨语言边界上的对象是"无类型"的,能用原始值就别传对象。

坑十:maxInputEdge 调到 2560,输出长边 10240。 一开始觉得"输入越大越清楚",把 maxInputEdge 拉到 2560。输出是 10240 长边,RGBA_8888 下约 314 MB,加上输入位图、预览和编码器,设备内存直接紧张。默认改回 1280(输出 5120 长边、约 78 MB),并在 仓库说明里写清楚这个预算。教训:超分的内存按输出面积算,4 倍是面积 16 倍;先定内存预算,再定输入上限。

7. 现在怎么用:从 三方库 到依赖

经过上面的整理,这个工程现在是一个标准的 Cordova 插件(包名 com.lqjmac.cordova.ohosvision,版本 2.1.0),演示应用在 example/。插件以 AtomGit 仓库为分发源,没有发布到 npm registry——请从仓库地址安装:

# Cordova CLI(git 地址)
cordova plugin add https://atomgit.com/oh-tpc/cordova-ohos-ai-vision.git

# hcordova(HarmonyOS 宿主,git 地址)
hcordova plugin add https://atomgit.com/oh-tpc/cordova-ohos-ai-vision.git

如果要从本地目录安装,先把插件复制到仓库外,或者用 rsync 排掉 example/、node_modules/、.git/:

rsync -a --exclude example --exclude node_modules --exclude .git \
  ./ cordova-ohos-ai-vision/
cd example
hcordova plugin add cordova-ohos-ai-vision

不要直接对仓库根执行 hcordova plugin add——第 6 节坑二那个 11 GB 的副本就是这么来的。

更新已有插件时,先删 rawfile/www/plugins/<插件目录> 与 cordova_plugins.js 再装。hcordova 的 js-module 安装器发现目标存在时只打印 warning、不会覆盖;如果手工把新的 ohos-vision.js 拷进 rawfile,还会丢掉 cordova.define(...) 包装层,页面报 Module cordova-ohos-ai-vision.OhosVision does not exist。

安装之后还有两步:在 Index.ets 的 cordovaPlugs 里注册 OhosVision(见第 4 节),以及用 DevEco 自动签名构建真机 HAP。宿主的 compatibleSdkVersion 必须是 26.0.0,否则 ArkTS 编译不过。

接入代码在第 4 节已经给过,核心就是 capabilities() + pickImage() + superResolve()。公共 API 都挂在 window.OhosVision 上:

接口说明
version插件版本,与 package.json 一致
capabilities(force?){ native, engine, supported, detail, info };force 跳过 3 秒失败缓存
isNativeAvailable()同步缓存值;探针成功后为 true
requireNative()原生不可用时 reject,用于启动自检
requireSuperResolution()原生不可用时 reject NATIVE_UNAVAILABLE;设备低于 API 26 时 reject UNSUPPORTED
nativeInfo(){ platform, engine, bridge, visionKit, apiVersion, sdkApiVersion, supported, scale }
pickImage() / pickImageFile()系统相册 / 文件选择器;取消返回 null
superResolve(uri, options?)超分一张图,返回 SuperResolutionResult
superResolveFromGallery() / superResolveFromFile()选图 + 超分一步完成
normalizeEnhanceOptions(options?)校验并补默认值,非法值抛 INVALID_ARGUMENT
resultToJson(result)把结果序列化为 JSON 字符串

失败时统一 reject 一个 OhosVisionError,code 是这六个之一:

code触发场景
NATIVE_UNAVAILABLE没有 Cordova 运行时,或插件没注册
UNSUPPORTED设备低于 API 26,或没有视觉栈
NATIVE_TIMEOUT探针 / 选图 / 超分超时
NATIVE_ERROR原生解码、模型、编码失败
INVALID_ARGUMENT空 URI、quality / format / maxInputEdge 非法
INVALID_PAYLOAD原生返回的字段缺失或类型不对

选项和结果如下:

选项默认值允许范围说明
quality921–100 整数输出文件编码质量;PNG 忽略
format'jpeg''jpeg' / 'png'输出编码
maxInputEdge1280256–2560 整数解码后长边上限;模型输出为其 4 倍
interface SuperResolutionResult {
  readonly uri: string;                    // 选中的原图 uri
  readonly source: string;                 // 相册图片 / 文件图片 / 图片
  readonly input: { width: number; height: number };
  readonly output: {
    uri: string;                           // file:// + 沙箱路径
    path: string;                          // 绝对路径,位于应用沙箱
    width: number; height: number;
    bytes: number; format: 'jpeg' | 'png';
  };
  readonly scale: number;                  // 输出宽 / 输入宽,实测应为 4
  readonly durationMs: number;
  readonly preview: {
    before: string; after: string;             // 整图缩略:两边都缩到长边 432
    beforeDetail: string; afterDetail: string; // 同一区域 1:1 裁剪,看模型到底改了什么
  };
}

当前版本在 Cordova v14.0.2 / cordova-ohos 14.0.2 基线上验证。npm run verify 里包含 tsc --noEmit、esbuild 打包和 types/ 生成,下面是测试结果,全绿:

✓ __tests__/package.test.ts (10 tests)
✓ __tests__/result.test.ts (8 tests)
✓ __tests__/bridge.test.ts (19 tests)
Test Files  3 passed (3)
     Tests  37 passed (37)

宿主侧 hvigorw assembleHap 输出 BUILD SUCCESSFUL(首次 4 s 250 ms),ArkTS 只有 Function may throw exceptions. Special handling is required. 级别的系统调用提示,没有错误。npm pack --dry-run 产出 21 个文件、851.4 kB 包体(解包 963.9 kB);比 2.0.0 的 212.0 kB 大,主要是文档目录里的对比图也进了包,真要瘦身可以把 docs 从 files 字段里拿掉。

浏览器运行时里,capabilities() 返回 native: false、supported: false,选图 / 超分全部以 NATIVE_UNAVAILABLE 拒绝,没有返回任何示例图片:

{
  "loaded": "object",
  "version": "2.1.0",
  "service": "OhosVision",
  "capabilities": {
    "native": false,
    "engine": "none",
    "supported": false,
    "detail": "Missing Command Error",
    "info": null
  },
  "resolve": { "ok": false, "code": "NATIVE_UNAVAILABLE" },
  "hasUpscale": []
}

真机上(HUAWEI MateBook Pro S,HarmonyOS 7.0.0.111,API 26)的几次结果:

输入输出耗时输出文件备注
419 × 6001676 × 2400344 ms920.3 KB第 2 节截图里的森林图
360 × 2401440 × 960225 ms295.1 KB超分对比图的岩石公路
360 × 2451440 × 980201 ms79.0 KB另一张低清图

其中 360×240 的输出用 hdc file recv 取回后确认尺寸 1440×960、文件 302,151 字节,和页面上报的 295.1 KB / 1440×960 对得上。页面状态显示 图像超分 · HarmonyOS · ArkTS 引擎 · API 26,说明 engineInfo 探针、cordova.exec 和 ArkTS 插件在真机上都是通的。

更完整的资料在仓库里:

  • 英文,完整 API、兼容性约束和模拟器运行流程;
  • 中文,内容与英文版对应;
  • example/:Cordova-OHOS 宿主,含从 hcordova plugin add 到 hdc install 的完整步骤;
  • __tests__/:37 项 Vitest(jsdom),覆盖载荷、exec 桥、能力探针、选项校验、插件清单和"构建产物不含 canvas / 演示图";
  • 分层、时序、并发和三个真实坑;
  • 构建、安装与验证记录;
  • 360×240 → 1440×960 的 1:1 对比原图。

已知限制也列一下:

  • 结果写在应用沙箱的 files/super-resolution/,不写系统相册;保存/分享是宿主的交互;
  • preview.* 是长边 432 / 细节 720×480 的缩略图,全分辨率以 output.path 为准;
  • 模型固定 4×,没有 2× / 3× 选项,也不能只放大某个区域;
  • 只有 API 26+ 有模型,模拟器没有可用实例;
  • 同一进程内超分串行执行,连续调用会排队,不会并发抢模型;
  • 预览是 data URL,结果 JSON 里会带几张 base64;如果页面只关心路径,可以在宿主侧裁掉。

最后回答标题里的问题:4 倍放大之后,像素从哪来?从模型对边缘、纹理和噪声的预测里来,不是从原图里"恢复"出来的。这个区别决定了它的用法——拿来看、拿来预览、拿来给低清素材补一版可用的图,都合适;拿它当证据、当无损还原、当"把模糊文字变清楚"的工具,就会失望。插件把模型、文件、预览和边界都摆在页面上,剩下的保存、分享、写相册,由宿主应用决定。

Logo

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

更多推荐