👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
  💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀

前言

调用超分接口之前,有一件事很容易被跳过——图片的输入条件检查。

官方文档对 superResolution 的输入约束写得相当清楚,但开发者在第一次接入时往往直接传入业务图片,等到出现 401 错误或处理结果不符合预期,才回头翻文档。这篇文章就来把这些约束整理清楚,并把检查逻辑组织成一个可复用的前置管线。

一、为什么不能拿任意图片直接调用?

imageEnhancer.superResolution 属于 CoreVisionKit 提供的 AI 推理能力,底层依赖设备侧的推理引擎。这类接口通常对输入数据有严格的格式和尺寸要求,原因是推理模型本身在训练时对输入规格做了假设。

用一句话概括:超分接口不是通用图片处理管线,它对输入图片的格式、尺寸、方向均有明确约束,不满足条件的图片传进去轻则返回错误码,重则直接导致推理引擎初始化失败。

这不是边界场景,而是日常开发中非常容易遇到的问题——用户相册里的图片来源各异,横拍照片、PNG截图、相机直出的 JPEG 解码后的格式各不相同,直接传入根本无法保证通过。

二、官方约束逐项整理

根据官方文档(@kit.CoreVisionKit · imageEnhancer,API 14,HarmonyOS 5.0.0(12) 起支持),superResolution 的输入约束如下:

约束项具体要求
宽度范围2 ≤ width ≤ 1080(像素)
高度范围2 ≤ height ≤ 1920(像素)
宽高奇偶性宽和高均须为偶数
宽高关系宽不大于高(仅支持竖图或正方形,不支持横图)
像素格式BGRA_8888 或 NV21
设备能力设备需支持 SystemCapability.AI.ImageEnhancer
API LevelAPI 14 及以上

这六条里,**“宽不大于高"和"格式必须是 BGRA_8888 或 NV21”**最容易被忽略。

相机横拍照片通常宽 > 高;PNG 和 JPEG 解码后默认格式因解码配置不同而异,不一定是 BGRA_8888。这两点是实际接入时最常见的来源。

三、搭一个最小实践场景

目标:在调用 superResolution 之前,对 PixelMap 做一次完整的前置检查,把所有不满足条件的情况分类处理,而不是直接扔进接口等报错。

需要的配置:

  • HarmonyOS 工程,API Level 14
  • 导入 @kit.CoreVisionKit 和 @kit.ImageKit
  • Stage 模型

不需要额外权限配置,SystemCapability.AI.ImageEnhancer 是系统能力,通过 canIUse 检查即可,无须在 module.json5 中声明权限。

四、核心代码实现

4.1 检查设备是否支持超分能力

这是第一道门槛,不支持的设备上调用接口会直接抛出 1008302001(推理引擎加载失败)。

import { canIUse } from '@kit.AbilityKit';

function isSuperResolutionSupported(): boolean {
  return canIUse('SystemCapability.AI.ImageEnhancer');
}

4.2 读取 PixelMap 的尺寸和格式信息

getImageInfo() 返回的 ImageInfo 包含 size.width、size.height 和 pixelFormat,这是后续检查的数据来源。

import { image } from '@kit.ImageKit';

async function getPixelMapMeta(pixelMap: image.PixelMap): Promise<image.ImageInfo> {
  return await pixelMap.getImageInfo();
}

4.3 实现前置检查函数

这段代码把官方六条约束逐一映射为可读的检查结果,并给出具体的不满足原因,方便后续决定怎么处理。

import { image } from '@kit.ImageKit';

export interface CheckResult {
  passed: boolean;
  reason?: string;
}

export function checkSuperResolutionInput(info: image.ImageInfo): CheckResult {
  const { width, height } = info.size;
  const fmt = info.pixelFormat;

  // 约束1:宽高下限
  if (width < 2 || height < 2) {
    return { passed: false, reason: `尺寸过小:${width}x${height},宽高均需 ≥ 2` };
  }

  // 约束2:宽度上限
  if (width > 1080) {
    return { passed: false, reason: `宽度超限:${width},上限为 1080` };
  }

  // 约束3:高度上限
  if (height > 1920) {
    return { passed: false, reason: `高度超限:${height},上限为 1920` };
  }

  // 约束4:宽高需为偶数
  if (width % 2 !== 0 || height % 2 !== 0) {
    return { passed: false, reason: `宽高需为偶数,当前 ${width}x${height}` };
  }

  // 约束5:宽不大于高(仅支持竖图或方图)
  if (width > height) {
    return { passed: false, reason: `横图不支持:宽(${width}) > 高(${height}),需旋转后处理` };
  }

  // 约束6:格式必须是 BGRA_8888 或 NV21
  const BGRA_8888 = image.PixelMapFormat.BGRA_8888; // 枚举值 4
  const NV21 = image.PixelMapFormat.NV21;           // 枚举值 8
  if (fmt !== BGRA_8888 && fmt !== NV21) {
    return { passed: false, reason: `格式不支持:${fmt},需为 BGRA_8888 或 NV21` };
  }

  return { passed: true };
}

4.4 不满足条件时的格式转换

格式问题是可以通过 convertPixelFormat 处理的(API 12 起支持),尺寸问题则需要裁剪或缩放后再处理。

import { image } from '@kit.ImageKit';

// 将格式转为 BGRA_8888
async function ensureBGRA8888(pixelMap: image.PixelMap): Promise<void> {
  const info = await pixelMap.getImageInfo();
  const BGRA_8888 = image.PixelMapFormat.BGRA_8888;
  if (info.pixelFormat !== BGRA_8888) {
    await pixelMap.convertPixelFormat(BGRA_8888);
  }
}

格式转换在原 PixelMap 上就地操作,不会创建新对象。转换完成后重新取一次 getImageInfo() 验证。

尺寸超限或宽高为奇数的场景,根据官方接口设计,建议在业务层通过 image.createPixelMap 或解码参数在来源侧控制,而不是在检查环节强行修改。

4.5 调用超分接口

检查通过后,才进入实际的超分调用。

import { imageEnhancer } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

// ResolutionQuality.MEDIUM = 0(默认),ResolutionQuality.HIGH = 1
async function runSuperResolution(
  pixelMap: image.PixelMap,
  quality: imageEnhancer.ResolutionQuality = imageEnhancer.ResolutionQuality.MEDIUM
): Promise<image.PixelMap | null> {
  try {
    const result = await imageEnhancer.superResolution(pixelMap, quality);
    return result;
  } catch (e) {
    const err = e as BusinessError;
    console.error(`[SuperRes] 超分失败 code=${err.code} msg=${err.message}`);
    return null;
  }
}

4.6 完整的处理管线

把设备检查、格式修正、条件验证、超分调用串成一个完整流程。

import { imageEnhancer } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { canIUse } from '@kit.AbilityKit';

export async function processSuperResolution(
  pixelMap: image.PixelMap,
  quality: imageEnhancer.ResolutionQuality = imageEnhancer.ResolutionQuality.MEDIUM
): Promise<image.PixelMap | null> {

  // Step 1:设备支持检查
  if (!canIUse('SystemCapability.AI.ImageEnhancer')) {
    console.warn('[SuperRes] 当前设备不支持超分能力');
    return null;
  }

  // Step 2:格式归一化(尝试转为 BGRA_8888)
  await ensureBGRA8888(pixelMap);

  // Step 3:完整条件检查
  const info = await pixelMap.getImageInfo();
  const check = checkSuperResolutionInput(info);
  if (!check.passed) {
    console.warn(`[SuperRes] 输入条件不满足:${check.reason}`);
    return null;
  }

  // Step 4:执行超分(建议在 TaskPool 中调用,避免阻塞主线程)
  return await runSuperResolution(pixelMap, quality);
}

五、几个关键点拆开看

5.1 HIGH 档位不是默认值

官方枚举 ResolutionQuality 只有两个值:MEDIUM = 0 和 HIGH = 1。接口签名中 resolutionQuality 是非必填参数,默认为 MEDIUM。

HIGH 档位处理质量更好,但官方明确说明耗时更长,对设备性能要求更高。如果你的业务场景是批量处理图片,或者在低性能设备上运行,默认 MEDIUM 通常是更稳妥的选择。不要因为 HIGH 听起来"更好"就默认使用它。

5.2 宽不大于高是对竖图的硬性限制

这一条经常被误解为"建议"。实际上这是硬性约束:横图(宽 > 高)不支持,传入会触发参数校验失败(错误码 401)。

如果业务中来源图片可能是横图,在管线入口处就要判断,不能等到接口报错再处理。处理方式通常是在业务层对图片进行旋转后再传入,而不是修改超分接口的调用方式。

5.3 像素格式要在解码阶段确定

从相册取图或从网络下载图片时,最终 PixelMap 的像素格式取决于解码参数配置。image.DecodingOptions 中的 desiredPixelFormat 字段可以在解码时直接指定为 BGRA_8888,这比解码完再 convertPixelFormat 更高效。

如果图片来源在你的控制范围内,建议在解码阶段直接指定格式,而不是依赖后期转换。

5.4 超分是耗时操作,不要在主线程直接调用

官方开发指南明确建议:超分处理是耗时操作,应该放在子线程(Worker 或 TaskPool)中执行,避免阻塞 UI 线程。即使 superResolution 接口返回的是 Promise,也不代表在主线程 await 就没有问题,推理计算本身会占用 CPU,对主线程调度有影响。

六、容易踩坑的地方

格式问题不会在编译时报错。 getImageInfo().pixelFormat 返回的是枚举数值,传错了格式在运行时才会收到 401 或 1008302002,开发阶段如果只用固定测试图,很容易漏掉这个检查。

HIGH 档位在低端设备上可能直接返回失败。 1008302001 是推理引擎加载失败,1008302002 是超分处理失败,前者在不支持设备上会出现,后者在引擎加载成功但处理过程中遇到问题时出现。这两个错误码需要分开处理,前者说明设备根本不支持,后者可能是临时性资源不足。

超分完成后要主动释放原始 PixelMap。 超分返回的是一张新 PixelMap(尺寸是输入的 2 倍),原始 PixelMap 如果不手动调用 release(),会持续占用内存。大图场景下,输入的 PixelMap 本身就已经不小,加上超分后输出图是输入的 4 倍面积,内存压力很明显。

宽高奇数的问题来源往往是裁剪。 如果你的业务在超分前做了图片裁剪,裁剪结果的宽高有可能是奇数。这不是罕见情况,需要在裁剪阶段就保证偶数对齐。

七、排查顺序

遇到超分接口报错或返回 null 时,建议按照下面的顺序检查:

  1. 设备是否支持 → canIUse('SystemCapability.AI.ImageEnhancer') 是否为 true
  2. API Level 是否匹配 → 工程 compileSdkVersion 是否 ≥ 14,运行设备系统版本是否 ≥ HarmonyOS 5.0.0(12)
  3. 像素格式 → getImageInfo().pixelFormat 是否为 BGRA_8888(4)或 NV21(8)
  4. 宽高关系 → 是否满足宽 ≤ 高(横图需要先旋转)
  5. 宽高范围 → 是否在 [2, 1080] × [2, 1920] 范围内
  6. 宽高奇偶性 → 宽和高是否都是偶数
  7. 错误码区分 → 1008302001 是引擎问题,1008302002 是处理失败,401 是参数问题,三者原因不同

八、开发经验总结

  • 超分接口的输入约束有六条,其中格式和宽不大于高是实际项目中最常被忽略的两条,建议把检查逻辑封装为独立函数,在每次调用前复用。
  • ResolutionQuality.HIGH 质量更好,代价是更长的处理时间和更高的设备性能要求,按实际场景选择,不要默认选 HIGH。
  • 超分处理放在 TaskPool 或 Worker 中执行,处理完成后及时 release() 原始 PixelMap。
  • 如果图片来源可控,在解码阶段通过 desiredPixelFormat 直接指定 BGRA_8888,比事后 convertPixelFormat 更稳妥。
  • 把条件检查、格式转换、接口调用组织成串行管线,比在各处分散判断更容易维护和排查。

如果你的项目中图片来源比较复杂(相册、网络、相机实时帧都有),可以重点检查一下每条来源路径上的 PixelMap 格式和尺寸是否都经过了统一的前置处理,这通常比反复调试接口报错更有效率。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐