大家好,我是鸿蒙Jack。本期以我的《时光旅记》APP 为例,聊一聊我怎样在 HarmonyOS 7.0、API 26 上接入 Core Vision Kit 的图像超分能力,并把它真正放进照片浏览这条业务链里。
《时光旅记》里存的不只是刚拍出来的高清照片。用户可能会导入多年前从旧手机迁移过来的照片,也可能保存聊天软件压缩过的旅行图、老相册翻拍图、低清截图。这些图片平时缩在卡片里看不出问题,一旦进入全屏预览,再双指放大,人物边缘、建筑纹理和远处招牌很快就会发虚。
图像超分正适合处理这个问题。从 API 26 开始,Core Vision Kit 新增了低分辨率图像的超分辨率重建能力。应用把待处理图片解码为 PixelMap,构造 visionBase.Request,交给 ImageSRAnalyzer.process(),完成后从 ISPResponse.pixelMap 取得增强结果。它不是给图片简单套一个锐化滤镜,而是由系统视觉能力完成重建;但它也不能凭空恢复现实世界里从未被记录的全部细节,所以产品措辞应该是“增强清晰度”“增强预览”,不要承诺“无损恢复原片”。
我最终把入口放在“瞬间详情”的全屏图片预览里。用户打开一张静态照片,如果当前设备支持 API 26 和对应系统能力,右上角会出现图像超分按钮。点击后保留原图,界面显示加载状态;处理成功则切到增强后的 PixelMap,再次点击可以立刻回到原图对比。用户横向切换照片、关闭预览或者处理过程中离开当前图片时,旧任务即使晚一点返回,也不会覆盖新照片。
这篇文章不只给一段 process() 示例。我会把《时光旅记》实际用到的版本判断、图库 URI 解码、Core Vision Kit 请求、超大输出图的预览尺寸控制、异步竞态处理、PixelMap 生命周期、ArkUI 渲染和错误提示都串起来。文末给出一套可以直接放进工程的完整代码,同时解释当前项目为什么这样组织。
官方资料可以查看 图像超分开发指南 和 imageSuperResolution 接口参考,设备与地区等总体约束可以查看 Core Vision Kit 简介。本文所用接口以 API 26 为基线。
超分前(原图):

超分后:

先看最终调用链
在《时光旅记》里,图像超分横跨了页面、组件、系统 Kit 和图像资源管理。整体结构如下:

图里有两个容易被忽略的点。第一,能力判断发生在入口展示之前,也发生在服务调用之前。界面判断负责不给不支持的设备展示无效按钮,服务判断负责防止其他调用者绕过界面直接触发不支持的 API。第二,系统返回结果后不能马上写入 UI 状态,因为用户可能已经滑到了下一张图片。要先确认“当前图片、请求版本、页面状态”都没有变化,才能接收结果。
再看一次用户点击后的时序:

这次到底用了哪些技术
这套功能没有引入三方图像算法库,也没有从 npm 或 ohpm 增加依赖。代码使用的都是 HarmonyOS SDK 提供的 Kit 和 ArkUI 能力。
| 技术 | 在本文中的职责 | 关键对象或接口 |
|---|---|---|
| ArkTS | 编写服务层、异步任务、类型约束和资源释放逻辑 | Promise、try/catch/finally、Map 之外的基础语言能力 |
| ArkUI | 构建全屏预览、按钮、加载态、原图/增强图切换和 Toast | Image、Stack、LoadingProgress、@State、组件生命周期 |
| Core Vision Kit | 创建图像超分分析器并处理请求 | imageSuperResolution.ImageSRAnalyzer、visionBase.Request、ISPResponse |
| Image Kit | 把文件描述符解码成 PixelMap,读取尺寸,生成受控尺寸的输出预览图 |
image.createImageSource()、createPixelMap()、getImageInfo()、createScaledPixelMap() |
| Core File Kit | 打开系统图库返回的 URI 并管理文件描述符 | fileIo.open()、fileIo.close() |
| Basic Services Kit | 读取运行设备 API 版本并接收标准业务错误 | deviceInfo.sdkApiVersion、BusinessError |
| Performance Analysis Kit | 记录输入尺寸、输出尺寸、耗时和失败信息 | hilog.info()、hilog.warn()、hilog.error() |
| Media Library Kit | 《时光旅记》已有的相册选择和媒体 URI 来源 | PhotoViewPicker,超分服务本身不直接负责选图 |
需要特别区分 CoreVisionKit 和 VisionKit。这个项目的全屏预览里同时使用了两套视觉能力:@kit.VisionKit 的 VisionImageAnalyzerController 用于文本分析、主体识别和对象搜索;本文的图像超分来自 @kit.CoreVisionKit。二者名字接近,但导入路径、对象和使用目的都不同。文章里的超分核心导入是:
import { imageSuperResolution, visionBase } from '@kit.CoreVisionKit';
而不是:
import { visionImageAnalyzer } from '@kit.VisionKit';
图像超分还会用到全局 PixelMap 类型。为了创建和释放它,我通过 @kit.ImageKit 的 image 命名空间调用图像接口。输入图片虽然来自系统图库,但 ImageSRAnalyzer.process() 不接收图库 URI,它接收的是装在 visionBase.ImageData 里的 PixelMap。这就是 Core File Kit 和 Image Kit 必须出现在调用链里的原因。
工程版本应该怎么配
《时光旅记》当前产品配置是:
{
"app": {
"products": [
{
"name": "default",
"compileSdkVersion": "26.0.0",
"targetSdkVersion": "26.0.0",
"compatibleSdkVersion": "6.1.0(23)",
"runtimeOS": "HarmonyOS"
}
]
}
}
compileSdkVersion 决定编译期能否识别 API 26 的 imageSuperResolution 接口。targetSdkVersion 表示应用以 API 26 的行为和安全规则作为目标。compatibleSdkVersion 仍然是 23,意味着应用整体仍允许安装或运行在较低 API 的系统上。因此不能因为工程“用 API 26 编译”就直接认为所有运行设备都能调用图像超分。
官方接口还明确要求 Stage 模型。《时光旅记》的 entry/build-profile.json5 使用 "apiType": "stageMode",因此满足模型约束。如果仍是 FA 模型工程,不能只复制本文调用代码后就认为已经具备接入条件。
我在服务层使用双条件判断:
const CORE_VISION_API_VERSION: number = 26;
const CORE_VISION_SYSCAP: string = 'SystemCapability.AI.Vision.VisionBase';
export function isCoreVisionApi26Available(): boolean {
return deviceInfo.sdkApiVersion >= CORE_VISION_API_VERSION &&
canIUse(CORE_VISION_SYSCAP);
}
deviceInfo.sdkApiVersion >= 26 解决系统版本问题,canIUse('SystemCapability.AI.Vision.VisionBase') 解决具体设备能力问题。只判断其中一个都不够严谨:版本达到并不等于某类设备一定带有这个系统能力;只问 SysCap 而不写清 API 基线,也会让后续维护者摸不清这段保护是为哪个版本准备的。
界面调用 isCoreVisionApi26Available() 决定是否展示按钮,服务入口再检查一次。这样不支持的设备会自然降级为普通照片预览,不弹错误、不显示灰掉的入口,也不会触发动态加载后才发现接口不可用。
是否需要权限和额外依赖
图像超分本身没有在 module.json5 中新增权限,也不需要在 oh-package.json5 里声明一个 Core Vision Kit 三方包。@kit.CoreVisionKit、@kit.ImageKit、@kit.CoreFileKit 等都来自 SDK。
权限之外还有运行范围。根据 Core Vision Kit 官方总体约束,当前支持 Phone、Tablet、PC/2in1,能力仅适用于中国境内且不包含香港特别行政区、澳门特别行政区和中国台湾,模拟器也不支持。开发和验收必须使用符合地区条件的真机,不能用模拟器上按钮不出现来判断代码接入失败。对于不在支持范围内的设备,《时光旅记》依靠 API 版本和 SysCap 判断回到普通原图预览。
如果图片由 PhotoViewPicker 让用户主动选择,应用拿到的是选择结果 URI,并在授权范围内读取对应文件。不要为了图像超分额外申请读取整个图库的广泛权限。《时光旅记》的照片已经在自己的业务流程里选好并保存了 URI,用户进入全屏预览时,超分服务只读取当前这一个 URI。
这里还有一个产品边界:动态照片不是普通静态图。项目里用 MovingPhotoView 播放动态照片的图像与视频资源,如果只替换其中静态帧,播放切换时容易出现清晰度、色彩或构图不一致。因此当前实现明确限制只有“当前页不是动态照片”时才显示超分按钮:
private shouldShowSuperResolutionButton(): boolean {
return this.enableSuperResolution && isCoreVisionApi26Available() &&
this.getCurrentMovingPhotoVideoUri().length === 0;
}
这不是 Core Vision Kit 强制要求,而是《时光旅记》基于自己的媒体模型做的业务选择。
最小调用到底有几步
不考虑页面和资源治理,图像超分的核心只有四步:创建分析器、包装输入、处理请求、读取输出。
import { imageSuperResolution, visionBase } from '@kit.CoreVisionKit';
let analyzer: imageSuperResolution.ImageSRAnalyzer =
await imageSuperResolution.ImageSRAnalyzer.create();
let imageData: visionBase.ImageData = {
pixelMap: inputPixelMap
};
let request: visionBase.Request = {
inputData: imageData
};
let response: imageSuperResolution.ISPResponse =
await analyzer.process(request);
let outputPixelMap: PixelMap = response.pixelMap;
await analyzer.destroy();
这里的 ImageData 是视觉能力统一使用的图像数据包装,Request.inputData 是请求入口,ISPResponse.pixelMap 才是超分后的输出。process() 是异步操作,页面不能把它当成同步滤镜调用,也不能在主交互上假设它瞬间完成。
最小示例没有展示输入图从哪里来,也没有处理任何异常和资源释放。放到真实 APP 里,我至少还要回答以下问题:图库 URI 怎么变成 PixelMap;图片解码成什么像素格式;分析器何时销毁;输入和输出 PixelMap 谁负责释放;用户处理中切图怎么办;输出图太大怎么办;失败后怎样恢复界面;不支持 API 26 时入口怎样降级。后面的完整代码就是围绕这些问题展开。
从图库 URI 准备输入 PixelMap
《时光旅记》保存的是媒体 URI,不能把字符串直接交给超分分析器。服务先用 Core File Kit 以只读方式打开 URI:
let sourceFile: fileIo.File = await fileIo.open(
imageUri,
fileIo.OpenMode.READ_ONLY
);
拿到文件描述符后,用 Image Kit 创建 ImageSource,再解码:
let imageSource: image.ImageSource = image.createImageSource(sourceFile.fd);
let inputPixelMap: PixelMap = await imageSource.createPixelMap({
editable: false,
desiredPixelFormat: image.PixelMapFormat.RGBA_8888
});
我显式指定 RGBA_8888,目的是让进入视觉分析器的数据格式稳定。editable: false 表示业务代码不会直接修改输入像素。解码后通过 getImageInfo() 记录输入宽高,便于调试不同来源的图片:
const inputInfo: image.ImageInfo = await inputPixelMap.getImageInfo();
hilog.info(
0xD003,
'CoreVisionApi26',
'sr input-ready width=%{public}d height=%{public}d',
inputInfo.size.width,
inputInfo.size.height
);
真实代码里日志采用统一字符串包装,本文后面的完整服务会保留项目当前的日志形式。要注意 URI 可能包含用户数据,不建议在生产日志中无条件公开完整路径。《时光旅记》当前调试日志会记录 URI 以便开发阶段定位,如果要发布为严格隐私版本,我会把 URI 改为会话内短标识或仅记录文件类型与尺寸。
文件、ImageSource 和输入 PixelMap 的生命周期不是一回事。createPixelMap() 完成后,输入像素已经在 PixelMap 中,但为了让异常路径同样正确,代码仍统一在 finally 里依次释放分析器、输入 PixelMap、ImageSource 和文件。不要只在成功分支释放,否则任意一步抛错都会留下资源。
为什么输出还要再生成一张预览 PixelMap
process() 返回的 response.pixelMap 属于本次分析结果。如果页面直接持有它,就必须把该对象的所有权从服务层交给 UI,并保证服务不再释放。这样也能做,但《时光旅记》还要控制全屏预览的内存上限,所以我从分析器输出再创建一张独立预览图。
官方接口说明中,超分输出在提高图像质量的同时,像素同步放大四倍。业务代码仍然不应凭经验写死输出宽高,而应该像本文这样读取 response.pixelMap.getImageInfo() 的实际结果,因为后续的预览缩放、内存估算和 Toast 都应以返回对象为准。process() 一次只支持传入一张图片,不支持把多张图塞进同一个 Request;批处理应该在应用层排队,逐张调用。
const outputInfo: image.ImageInfo = await analyzerOutputPixelMap.getImageInfo();
const outputMaxEdge: number = Math.max(
outputInfo.size.width,
outputInfo.size.height
);
const previewScale: number = outputMaxEdge > 4096
? 4096 / outputMaxEdge
: 1;
let outputPixelMap: PixelMap = await analyzerOutputPixelMap.createScaledPixelMap(
previewScale,
previewScale,
image.AntiAliasingLevel.HIGH
);
最长边不超过 4096 时,缩放系数是 1,仍然生成一张独立 PixelMap。这一步看起来多做了一次复制,但它换来了清晰的资源所有权:分析器响应里的 PixelMap 一定由服务在 finally 释放;独立预览 PixelMap 由调用者接管,最终由预览组件释放。
最长边超过 4096 时,输出等比压到最长边 4096,使用高等级抗锯齿。这里控制的是“交互预览资源”,不是把 Core Vision Kit 的原始输出能力限制在 4096,也不是把图片永久保存成这个尺寸。《时光旅记》当前功能只做屏幕预览和原图对比,没有把增强结果写回相册,所以没必要长期占用一张超大位图。
假设输出是 8000×6000 的 RGBA_8888 位图,单看未压缩像素理论占用就约为:
8000 × 6000 × 4 bytes = 192,000,000 bytes
这还没有算输入图、分析器内部缓冲区、ArkUI 渲染资源和其他页面状态。在照片 Swiper 里连续操作几张,内存峰值会非常明显。把预览最长边限制为 4096 后,仍能覆盖高密度屏幕下的放大观察,同时让内存边界更可控。
如果你的产品需求是“保存超分原始输出”,应该把“预览图”和“导出图”拆成两条链:预览仍使用受控尺寸,导出则对分析器原始输出调用 Image Kit 编码并写入沙箱或媒体库,编码完成后立即释放。不要让一个长期挂在页面状态里的 PixelMap 同时承担预览和原始导出两种职责。
完整服务层代码
下面是把《时光旅记》当前 CoreVisionApi26Service.ets 中图像超分部分独立整理后的完整代码。原文件还包含 API 26 的文本语义搜图逻辑,为了让本文代码聚焦,我没有把无关能力一起复制进来。这个版本的类、导入、能力判断、错误包装、日志和资源释放是完整的,可以单独保存为 JackImageSuperResolutionService.ets 使用。
import { BusinessError, deviceInfo } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
import { imageSuperResolution, visionBase } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
const CORE_VISION_API_VERSION: number = 26;
const CORE_VISION_SYSCAP: string =
'SystemCapability.AI.Vision.VisionBase';
const LOG_DOMAIN: number = 0xD003;
const LOG_TAG: string = 'JackImageSuperResolution';
const PREVIEW_MAX_EDGE: number = 4096;
export function isImageSuperResolutionAvailable(): boolean {
return deviceInfo.sdkApiVersion >= CORE_VISION_API_VERSION &&
canIUse(CORE_VISION_SYSCAP);
}
export class JackImageSuperResolutionService {
async enhanceImage(imageUri: string): Promise<PixelMap> {
if (!isImageSuperResolutionAvailable()) {
this.logWarn('unsupported: API 26 or VisionBase SysCap unavailable');
throw new Error('当前系统不支持图像超分');
}
const startedAt: number = Date.now();
this.logInfo(`start uri=${imageUri}`);
let sourceFile: fileIo.File | undefined = undefined;
let imageSource: image.ImageSource | undefined = undefined;
let inputPixelMap: PixelMap | undefined = undefined;
let analyzer: imageSuperResolution.ImageSRAnalyzer | undefined = undefined;
let analyzerOutputPixelMap: PixelMap | undefined = undefined;
let previewPixelMap: PixelMap | undefined = undefined;
try {
sourceFile = await fileIo.open(
imageUri,
fileIo.OpenMode.READ_ONLY
);
imageSource = image.createImageSource(sourceFile.fd);
inputPixelMap = await imageSource.createPixelMap({
editable: false,
desiredPixelFormat: image.PixelMapFormat.RGBA_8888
});
const inputInfo: image.ImageInfo = await inputPixelMap.getImageInfo();
this.logInfo(
`input-ready width=${inputInfo.size.width.toString()} ` +
`height=${inputInfo.size.height.toString()}`
);
analyzer = await imageSuperResolution.ImageSRAnalyzer.create();
this.logInfo('analyzer-created');
const imageData: visionBase.ImageData = {
pixelMap: inputPixelMap
};
const request: visionBase.Request = {
inputData: imageData
};
const response: imageSuperResolution.ISPResponse =
await analyzer.process(request);
analyzerOutputPixelMap = response.pixelMap;
const outputInfo: image.ImageInfo =
await analyzerOutputPixelMap.getImageInfo();
this.logInfo(
`process-success width=${outputInfo.size.width.toString()} ` +
`height=${outputInfo.size.height.toString()} ` +
`elapsedMs=${(Date.now() - startedAt).toString()}`
);
const outputMaxEdge: number = Math.max(
outputInfo.size.width,
outputInfo.size.height
);
const previewScale: number = outputMaxEdge > PREVIEW_MAX_EDGE
? PREVIEW_MAX_EDGE / outputMaxEdge
: 1;
previewPixelMap = await analyzerOutputPixelMap.createScaledPixelMap(
previewScale,
previewScale,
image.AntiAliasingLevel.HIGH
);
const previewInfo: image.ImageInfo =
await previewPixelMap.getImageInfo();
this.logInfo(
`preview-created scale=${previewScale.toString()} ` +
`width=${previewInfo.size.width.toString()} ` +
`height=${previewInfo.size.height.toString()}`
);
} catch (error) {
const businessError: BusinessError = error as BusinessError;
this.logError(
`failed code=${this.getErrorCode(businessError).toString()} ` +
`message=${this.getErrorMessage(businessError)}`
);
if (previewPixelMap !== undefined) {
try {
await previewPixelMap.release();
} catch (_releaseError) {
}
previewPixelMap = undefined;
}
throw new Error(
this.buildErrorMessage('图像超分失败', businessError)
);
} finally {
if (analyzerOutputPixelMap !== undefined) {
try {
await analyzerOutputPixelMap.release();
} catch (_releaseError) {
}
}
if (analyzer !== undefined) {
try {
await analyzer.destroy();
} catch (_destroyError) {
}
}
if (inputPixelMap !== undefined) {
try {
await inputPixelMap.release();
} catch (_releaseError) {
}
}
if (imageSource !== undefined) {
try {
await imageSource.release();
} catch (_releaseError) {
}
}
if (sourceFile !== undefined) {
try {
await fileIo.close(sourceFile);
} catch (_closeError) {
}
}
}
if (previewPixelMap === undefined) {
throw new Error('图像超分未返回有效结果');
}
return previewPixelMap;
}
private getErrorCode(error: BusinessError): number {
return typeof error.code === 'number' ? error.code : 0;
}
private getErrorMessage(error: BusinessError): string {
if (typeof error.message !== 'string') {
return '';
}
return error.message.trim();
}
private buildErrorMessage(prefix: string, error: BusinessError): string {
const code: number = this.getErrorCode(error);
const message: string = this.getErrorMessage(error);
if (code !== 0 && message.length > 0) {
return `${prefix}(${code.toString()}):${message}`;
}
if (message.length > 0) {
return `${prefix}:${message}`;
}
if (code !== 0) {
return `${prefix}(${code.toString()})`;
}
return prefix;
}
private logInfo(message: string): void {
hilog.info(LOG_DOMAIN, LOG_TAG, '%{public}s', message);
}
private logWarn(message: string): void {
hilog.warn(LOG_DOMAIN, LOG_TAG, '%{public}s', message);
}
private logError(message: string): void {
hilog.error(LOG_DOMAIN, LOG_TAG, '%{public}s', message);
}
}
export const jackImageSuperResolutionService:
JackImageSuperResolutionService =
new JackImageSuperResolutionService();
这段代码最重要的契约是:enhanceImage() 成功时返回一个仍然有效、且由调用者负责释放的 PixelMap;失败时不返回任何半成品,服务会清理自己创建过的资源。调用者拿到结果后,无论是显示、丢弃还是替换,都必须在不再使用时调用 release()。
为什么分析器在每次请求里创建
官方示例通常在页面出现时调用 ImageSRAnalyzer.create(),页面消失时调用 destroy()。这是合理的生命周期方案,适合页面进入后可能连续处理多张图片的场景。《时光旅记》当前采用另一种同样完整的策略:每次用户主动点击时创建一个分析器,本次处理结束就销毁。
我这样做是因为入口属于低频预览增强,不是批量图片工作台。分析器只在任务期间存在,服务不需要处理跨页面共享、页面后台驻留和多任务排队,资源边界非常直观。代价是每次点击都有一次创建成本。如果后续在“图片工厂”增加连续增强多张照片的能力,我会把分析器生命周期提升到批处理会话:进入批处理时创建,队列完成或离开页面时销毁,但仍然保证同一分析器的并发使用符合接口约束。
文章不能把一种生命周期写成唯一答案。判断标准是使用频率和所有权:低频单次任务适合请求内创建;连续处理适合页面或会话级复用。无论选哪种,destroy() 都必须存在,并且异常路径也要执行。
为什么所有清理都放在 finally
资源创建是逐步发生的。文件可能打开成功但图片解码失败;输入图可能解码成功但分析器创建失败;分析器可能创建成功但 process() 失败;处理成功后,创建预览图也可能因为内存不足而失败。因此变量一开始都声明为 undefined,每完成一步才赋值,finally 根据是否已经创建来释放。
释放顺序按依赖关系从高层往底层收:先释放分析器响应图,再销毁分析器,再释放输入图和 ImageSource,最后关闭文件。调用成功时,唯一不在 finally 释放的是 previewPixelMap,因为它要返回给 UI;调用失败时,catch 会释放可能已经创建的预览图并把变量重置为 undefined,然后再抛出业务可读错误。
不要用下面这种写法:
const response = await analyzer.process(request);
await response.pixelMap.release();
return response.pixelMap;
返回前已经释放的 PixelMap 对 UI 没有使用价值。也不要让服务和组件都“保险起见”释放同一个对象,重复释放同样是错误。代码需要明确所有权转移,而不是靠每一层多调用一次 release() 碰运气。
错误为什么重新包装
Kit 抛出的异常通常可以转成 BusinessError,其中包含 code 和 message。服务日志保留两者用于开发定位,对上层则抛出带业务前缀的 Error。这样 UI 不需要知道 Core Vision Kit 的所有错误码,也能拿到足够明确的信息。
throw new Error(
this.buildErrorMessage('图像超分失败', businessError)
);
不过,系统服务原始消息不一定适合直接展示给普通用户,甚至可能出现服务名、内部状态或英文说明。因此预览组件还会做一层展示文案过滤:可读的具体消息可以展示;明显偏内部的内容则统一替换成“当前照片暂时无法进行图像超分”。日志和用户文案是两个用途,不应该共用一条未经处理的字符串。
UI 不是拿到 PixelMap 就结束了
服务层解决了“怎么得到结果”,组件层要解决“这个结果现在还该不该显示”。在一个只有单张图片、禁止离开的演示页里,直接赋值可能不会暴露问题;在《时光旅记》的 Swiper 全屏预览里,用户随时可以横滑,问题马上出现。
考虑这个过程:用户在照片 A 上点超分,任务开始;等待期间用户滑到照片 B;A 的任务完成;如果回调直接执行 this.superResolutionPixelMap = result,B 的页面就可能显示 A 的增强图。这类问题不是算法错误,而是典型异步竞态。
我的组件同时记录三份状态:
@State private superResolutionPixelMap: PixelMap | undefined = undefined;
@State private superResolutionSourceUri: string = '';
@State private superResolutionLoadingUri: string = '';
private superResolutionRequestVersion: number = 0;
superResolutionPixelMap 是当前已接管的增强结果;superResolutionSourceUri 表明这张结果属于哪个原图;superResolutionLoadingUri 表明哪张图正在处理;superResolutionRequestVersion 是单调递增的请求代号。只凭 URI 还不够,因为用户可能在同一张图上发起请求、取消、再发起请求,两个任务的 URI 一样,但只有最后一次请求有效。
状态流转可以画成下面这样:

每次开始请求先增加版本号并保存局部快照:
const sourceUri: string = this.imageUri;
this.superResolutionRequestVersion =
this.superResolutionRequestVersion + 1;
const requestVersion: number = this.superResolutionRequestVersion;
this.superResolutionLoadingUri = sourceUri;
结果返回后检查:
if (this.isClosing ||
this.imageUri !== sourceUri ||
requestVersion !== this.superResolutionRequestVersion) {
void result.release();
return;
}
这里不能只 return,因为服务已经把结果所有权交给组件。既然组件决定丢弃,就必须先释放。页面关闭、横滑切图、用户恢复原图都会通过增加 superResolutionRequestVersion 让旧请求失效。底层任务未必支持物理取消,但“逻辑取消”足以保证过期结果不进入当前界面。
完整的独立预览组件
下面给出一个专门演示图像超分的完整 ArkUI 组件。它不包含《时光旅记》原组件里的动态照片、AI 识图、微表情控制和贴纸提取,因此更适合直接理解和复用。它接收一张图片 URI,支持原图显示、加载态、增强结果显示、恢复原图和退出时清理。
文件名可以是 JackSuperResolutionPreview.ets,并和前面的服务文件放在同一目录。
import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
import {
isImageSuperResolutionAvailable,
jackImageSuperResolutionService
} from './JackImageSuperResolutionService';
@Component
export struct JackSuperResolutionPreview {
imageUri: string = '';
enabled: boolean = true;
onClose?: () => void;
@State private enhancedPixelMap: PixelMap | undefined = undefined;
@State private enhancedSourceUri: string = '';
@State private loadingUri: string = '';
@State private imageLoaded: boolean = false;
@State private imageLoadFailed: boolean = false;
@State private previewScale: number = 1;
@State private previewOffsetX: number = 0;
@State private previewOffsetY: number = 0;
private requestVersion: number = 0;
private isClosing: boolean = false;
private readonly minPreviewScale: number = 1;
private readonly maxPreviewScale: number = 4;
private pinchStartScale: number = 1;
private panStartOffsetX: number = 0;
private panStartOffsetY: number = 0;
aboutToAppear(): void {
this.isClosing = false;
}
aboutToDisappear(): void {
this.isClosing = true;
this.clearEnhancedPreview();
}
build(): void {
Stack({ alignContent: Alignment.Center }) {
Column()
.width('100%')
.height('100%')
.backgroundColor('#F0000000')
if (this.imageLoadFailed) {
Column({ space: 10 }) {
Text('图片无法预览')
.fontSize(16)
.fontColor(Color.White)
Text('请返回后重新打开')
.fontSize(13)
.fontColor('#CBD5E1')
}
} else if (this.isEnhanced()) {
Image(this.getEnhancedPixelMap())
.width('100%')
.height('100%')
.objectFit(ImageFit.Contain)
.draggable(false)
.scale({ x: this.previewScale, y: this.previewScale })
.translate({
x: this.previewOffsetX,
y: this.previewOffsetY,
z: 0
})
} else {
Image(this.imageUri)
.width('100%')
.height('100%')
.objectFit(ImageFit.Contain)
.orientation(ImageRotateOrientation.AUTO)
.draggable(false)
.scale({ x: this.previewScale, y: this.previewScale })
.translate({
x: this.previewOffsetX,
y: this.previewOffsetY,
z: 0
})
.onComplete(() => {
this.imageLoaded = true;
this.imageLoadFailed = false;
})
.onError(() => {
this.imageLoaded = false;
this.imageLoadFailed = true;
})
}
if ((!this.imageLoaded || this.loadingUri.length > 0) &&
!this.imageLoadFailed) {
LoadingProgress()
.width(32)
.height(32)
.color(Color.White)
}
Row({ space: 12 }) {
if (this.shouldShowEnhanceAction()) {
if (this.loadingUri.length > 0) {
Row() {
LoadingProgress()
.width(20)
.height(20)
.color(Color.White)
}
.width(44)
.height(44)
.justifyContent(FlexAlign.Center)
.backgroundColor('#804F46E5')
.borderRadius(22)
.accessibilityText('正在增强图片清晰度')
} else {
Button({ type: ButtonType.Circle, stateEffect: true }) {
SymbolGlyph(
this.isEnhanced()
? $r('sys.symbol.arrow_counterclockwise')
: $r('sys.symbol.picture')
)
.fontSize(19)
.fontColor([Color.White])
}
.width(44)
.height(44)
.backgroundColor(
this.isEnhanced() ? '#66323E50' : '#804F46E5'
)
.accessibilityText(
this.isEnhanced() ? '恢复原图预览' : '图像超分'
)
.onClick(() => {
if (this.isEnhanced()) {
this.clearEnhancedPreview();
return;
}
void this.runSuperResolution();
})
}
}
Button({ type: ButtonType.Circle, stateEffect: true }) {
SymbolGlyph($r('sys.symbol.xmark'))
.fontSize(19)
.fontColor([Color.White])
}
.width(44)
.height(44)
.backgroundColor('#66323E50')
.accessibilityText('关闭图片预览')
.onClick(() => {
this.requestClose();
})
}
.position({ right: 20, top: 48 })
}
.width('100%')
.height('100%')
.gesture(
GestureGroup(
GestureMode.Parallel,
PinchGesture({ fingers: 2 })
.onActionStart(() => {
this.pinchStartScale = this.previewScale;
})
.onActionUpdate((event: GestureEvent) => {
const nextScale: number =
this.pinchStartScale * event.scale;
this.previewScale = this.clampPreviewScale(nextScale);
})
.onActionEnd(() => {
this.settlePreviewScale();
}),
PanGesture({ fingers: 1 })
.onActionStart(() => {
this.panStartOffsetX = this.previewOffsetX;
this.panStartOffsetY = this.previewOffsetY;
})
.onActionUpdate((event: GestureEvent) => {
if (!this.isPreviewZoomed()) {
return;
}
this.previewOffsetX =
this.panStartOffsetX + event.offsetX;
this.previewOffsetY =
this.panStartOffsetY + event.offsetY;
})
)
)
}
private shouldShowEnhanceAction(): boolean {
return this.enabled &&
this.imageUri.length > 0 &&
isImageSuperResolutionAvailable();
}
private isEnhanced(): boolean {
return this.enhancedPixelMap !== undefined &&
this.enhancedSourceUri === this.imageUri;
}
private getEnhancedPixelMap(): PixelMap {
if (this.enhancedPixelMap === undefined) {
throw new Error('图像超分预览尚未准备完成');
}
return this.enhancedPixelMap;
}
private async runSuperResolution(): Promise<void> {
if (!this.shouldShowEnhanceAction() || this.loadingUri.length > 0) {
return;
}
const sourceUri: string = this.imageUri;
this.requestVersion = this.requestVersion + 1;
const currentVersion: number = this.requestVersion;
this.loadingUri = sourceUri;
try {
const result: PixelMap =
await jackImageSuperResolutionService.enhanceImage(sourceUri);
if (this.isClosing ||
this.imageUri !== sourceUri ||
currentVersion !== this.requestVersion) {
void result.release();
return;
}
const resultInfo = await result.getImageInfo();
this.clearEnhancedPreview(false);
this.enhancedPixelMap = result;
this.enhancedSourceUri = sourceUri;
this.imageLoaded = true;
promptAction.showToast({
message:
`已切换到增强预览 ` +
`${resultInfo.size.width.toString()}×` +
`${resultInfo.size.height.toString()},再次点击可对比原图`,
duration: 2500
});
} catch (error) {
const businessError: BusinessError = error as BusinessError;
const detail: string = typeof businessError.message === 'string'
? businessError.message.trim()
: '';
const message: string = detail.length > 0 &&
detail.indexOf('Service') < 0
? detail
: '当前照片暂时无法进行图像超分';
promptAction.showToast({
message: message,
duration: 1800
});
} finally {
if (currentVersion === this.requestVersion &&
this.loadingUri === sourceUri) {
this.loadingUri = '';
}
}
}
private clearEnhancedPreview(
invalidateRequest: boolean = true
): void {
if (invalidateRequest) {
this.requestVersion = this.requestVersion + 1;
}
const pixelMap: PixelMap | undefined = this.enhancedPixelMap;
this.enhancedPixelMap = undefined;
this.enhancedSourceUri = '';
this.loadingUri = '';
if (pixelMap !== undefined) {
void pixelMap.release();
}
}
private requestClose(): void {
if (this.isClosing) {
return;
}
this.isClosing = true;
this.clearEnhancedPreview();
if (this.onClose !== undefined) {
this.onClose();
}
}
private clampPreviewScale(value: number): number {
return Math.min(
this.maxPreviewScale,
Math.max(this.minPreviewScale, value)
);
}
private isPreviewZoomed(): boolean {
return this.previewScale > 1.05;
}
private settlePreviewScale(): void {
if (this.isPreviewZoomed()) {
return;
}
this.previewScale = 1;
this.pinchStartScale = 1;
this.previewOffsetX = 0;
this.previewOffsetY = 0;
this.panStartOffsetX = 0;
this.panStartOffsetY = 0;
}
}
这个独立组件故意没有把选图也塞进来。一个组件同时负责拉起图库、管理照片集合、处理动态照片、执行超分和保存结果,很快会变成难以复用的“大页面”。在《时光旅记》中,图片 URI 来自既有的瞬间数据,预览组件只关心“当前 URI 和交互状态”,服务只关心“URI 到增强 PixelMap”。职责拆开后,未来从旅行封面、回收站预览或图片工厂调用同一个服务都不需要复制算法链。
接回《时光旅记》的现有预览
独立组件适合新页面,但《时光旅记》已经有成熟的 ImagePreviewDialog。它负责图片 Swiper、动态照片、双指缩放、AI 识图、主体抠图、贴纸提取和微表情辅助控制。如果直接用新组件替换,其他能力会丢失,所以项目实际采用“给既有预览增加一个可选能力”的方式。
入口由 MainPage 创建:
if (this.previewImageUri.length > 0) {
ImagePreviewDialog({
imageUri: $previewImageUri,
imageIndex: $previewImageIndex,
imageUris: this.previewImageUris,
movingPhotoVideoUris: this.previewMovingPhotoVideoUris,
expressionAssistEnabled:
this.store.microExpressionPhotoAssistEnabled,
showMoveButton: this.canMoveCurrentPreviewImage(),
showExtractStickerButton:
this.canExtractCurrentPreviewSticker(),
enableSuperResolution: this.showMomentDetail,
onClose: () => {
this.closeImagePreview();
},
onImageChange: (index: number, uri: string) => {
this.handleImagePreviewIndexChange(index, uri);
},
onMoveImage: () => {
this.requestMoveCurrentPreviewImage();
},
onExtractSticker: () => {
this.requestExtractCurrentPreviewSticker();
}
})
.key(
'image-preview-dialog-' +
this.previewImageSessionId.toString()
)
.zIndex(100)
}
enableSuperResolution: this.showMomentDetail 说明当前只在瞬间详情场景打开超分,不是所有使用图片预览弹层的地方都默认出现。这个布尔参数是业务开关,API 版本和 SysCap 是设备开关,两者要同时满足。
在 ImagePreviewDialog 顶部导入服务,并添加参数和状态:
import {
coreVisionApi26Service,
isCoreVisionApi26Available
} from '../utils/CoreVisionApi26Service';
@Component
export struct ImagePreviewDialog {
@Link imageUri: string;
@Link imageIndex: number;
imageUris: Array<string> = [];
movingPhotoVideoUris: Array<string> = [];
enableSuperResolution: boolean = false;
@State private superResolutionPixelMap:
PixelMap | undefined = undefined;
@State private superResolutionSourceUri: string = '';
@State private superResolutionLoadingUri: string = '';
private superResolutionRequestVersion: number = 0;
}
预览组件不会在 aboutToAppear() 自动跑超分。自动处理每一张图既增加等待,也会让用户无法判断当前看到的是原图还是增强图,而且连续滑动时成本很高。我把决定权留给用户:只有点击按钮才执行,成功后明确提示当前是增强预览。
入口展示与按钮位置
现有预览右上角已经有关闭、移动、提取贴纸等按钮。图像超分按钮不能写死在同一个 right 值,否则几个控件会重叠。项目根据已有按钮动态计算位置:
private shouldShowSuperResolutionButton(): boolean {
return this.enableSuperResolution &&
isCoreVisionApi26Available() &&
this.getCurrentMovingPhotoVideoUri().length === 0;
}
private getSuperResolutionButtonRight(): number {
let right: number = 70;
if (this.showMoveButton) {
right = right + 50;
}
if (this.showExtractStickerButton) {
right = right + 50;
}
return right;
}
按钮本体根据状态显示三种反馈。空闲且未增强时显示图片符号;正在处理时用同尺寸 LoadingProgress 替换,避免布局跳动;增强完成后显示恢复符号,点击会释放结果并回到原图。
if (this.shouldShowSuperResolutionButton()) {
if (this.superResolutionLoadingUri.length > 0) {
Row() {
LoadingProgress()
.width(20)
.height(20)
.color(Color.White)
}
.width(42)
.height(42)
.justifyContent(FlexAlign.Center)
.backgroundColor('#804F46E5')
.borderRadius(21)
.accessibilityText('正在增强图片清晰度')
.position({
right: this.getSuperResolutionButtonRight(),
top: 48
})
} else {
SymbolCircleButton({
symbol: this.isCurrentImageSuperResolved()
? $r('sys.symbol.arrow_counterclockwise')
: $r('sys.symbol.picture'),
buttonSize: 42,
iconSize: 18,
buttonBackgroundColor:
this.isCurrentImageSuperResolved()
? '#66323E50'
: '#804F46E5',
iconColor: Color.White,
accessibilityLabel:
this.isCurrentImageSuperResolved()
? '恢复原图预览'
: '图像超分',
accessibilityHint:
this.isCurrentImageSuperResolved()
? '双击恢复显示原始照片'
: '双击增强当前照片的清晰度并放大细节',
action: () => {
if (this.isCurrentImageSuperResolved()) {
this.clearSuperResolutionPreview();
return;
}
void this.runSuperResolution();
}
})
.position({
right: this.getSuperResolutionButtonRight(),
top: 48
})
}
}
这里没有让用户在一个弹窗里选择倍率、模型或参数,因为 ImageSRAnalyzer.process() 的公开调用本身不需要业务层传这些选项。《时光旅记》的动作很明确:对当前低清照片做一次增强预览。为了一个没有对应 API 参数的概念增加控件,只会制造无效选择。
原图和增强图怎么共用缩放手势
渲染时先判断增强结果是否同时属于当前 URI 和当前 Swiper 下标:
private isSuperResolutionActive(
uri: string,
index: number
): boolean {
return this.superResolutionPixelMap !== undefined &&
this.superResolutionSourceUri === uri &&
this.imageUri === uri &&
this.getSafePreviewIndex() === index;
}
只有全部匹配,当前页才显示增强 PixelMap:
if (this.isSuperResolutionActive(uri, index)) {
Image(this.getSuperResolutionPixelMap())
.width('100%')
.height('100%')
.objectFit(ImageFit.Contain)
.draggable(false)
.scale({
x: this.previewScale,
y: this.previewScale
})
.translate({
x: this.previewOffsetX,
y: this.previewOffsetY,
z: 0
})
.onComplete(() => {
console.info(
`[CoreVisionApi26][SRPreview] ` +
`stage=render-complete uri=${uri}`
);
})
.onError(() => {
console.error(
`[CoreVisionApi26][SRPreview] ` +
`stage=render-failed uri=${uri}`
);
})
} else {
Image(uri)
.width('100%')
.height('100%')
.objectFit(ImageFit.Contain)
.orientation(ImageRotateOrientation.AUTO)
.draggable(false)
.scale({
x: this.previewScale,
y: this.previewScale
})
.translate({
x: this.previewOffsetX,
y: this.previewOffsetY,
z: 0
})
}
原图和增强图复用 previewScale、previewOffsetX、previewOffsetY,用户切换前后仍用同一套缩放和平移手势。这样才能真正对比细节。如果增强完成后强制把视图缩回 1 倍,用户刚刚观察的区域会丢失,对比体验反而变差。
Image(uri) 使用 .orientation(ImageRotateOrientation.AUTO) 读取并应用图片方向;增强结果是解码、处理后得到的 PixelMap,直接交给 ArkUI 显示。测试时要专门覆盖带 EXIF 旋转信息的照片,确认输入解码后的方向和增强结果没有出现横竖颠倒。方向问题不能只拿系统截图来验证,因为截图通常没有复杂的 EXIF Orientation。
为什么增强时暂时不叠加 AI 识图
原预览还会在支持时创建带 aiController 的 Image:
Image(this.imageUri, {
types: this.enabledAnalyzerTypes,
aiController: this.analyzerController
})
.enableAnalyzer(true)
当前实现只有在没有启用超分结果时才进入这个分支:
if (!this.isSuperResolutionActive(uri, index) &&
this.isSupportImageAnalyzer &&
this.imageUri === uri &&
this.getSafePreviewIndex() === index) {
// 构建 Vision Kit AI 识图图层
}
这是两种视觉交互的边界处理。超分结果在 UI 中是一个新 PixelMap,而原有 AI 识图控制器绑定的是原始图片控件及其分析状态。如果原图识图层继续盖在增强图上,显示像素和交互命中区域可能来自不同图层;如果对增强图再启动一次识图,还要重新管理分析结果、按钮状态和资源。当前产品目标只是清晰度对比,所以增强态优先显示干净的图片,不叠加识图交互。恢复原图后,原有 Vision Kit 能力继续工作。
这也再次说明 Core Vision Kit 图像超分和 Vision Kit AI 识图不是同一能力。它们可以出现在同一个预览页面,但需要明确谁在当前状态下负责画面和交互,不能因为都叫 Vision 就把 controller 和处理结果混在一起。
切换照片时如何清理
Swiper 的 onChange 最终调用 handlePreviewIndexChange()。项目先清理超分结果,再更新当前索引和 URI:
private handlePreviewIndexChange(index: number): void {
const previewUris: Array<string> = this.getPreviewUris();
if (this.isClosing || index < 0 || index >= previewUris.length) {
return;
}
if (this.initialPreviewIndexGuardActive &&
index !== this.expectedInitialPreviewIndex) {
return;
}
this.clearInitialPreviewIndexGuardTimer();
this.clearSuperResolutionPreview();
this.imageIndex = index;
this.imageUri = previewUris[index];
this.resetPreviewScale();
this.prepareVisionAnalyzer();
this.prepareMovingPhoto();
if (this.onImageChange !== undefined) {
this.onImageChange(index, previewUris[index]);
}
}
clearSuperResolutionPreview() 默认会增加请求版本号,所以正在执行的旧任务被逻辑作废;已有增强结果则立即释放。随后再切换 URI,界面不会短暂把上一张的结果当作下一张的状态。
组件消失时同样清理:
aboutToDisappear(): void {
this.clearSuperResolutionPreview();
// 下面继续释放原组件中的 AI 识图、动态照片、AR 等资源
}
组件关闭不代表底层 process() 必然立刻停止,但结果回调会看到 requestVersion 已变化或 isClosing 为 true,于是释放结果而不写 UI。对于没有公开取消接口的异步任务,这种“界面状态作废 + 返回后释放”是可控的处理方式。
一次完整点击的代码阅读顺序
第一次读这套实现时,可以沿着一条固定路径看,不必从 1200 多行的预览组件顶部一直读到底。
先看 MainPage 的 enableSuperResolution: this.showMomentDetail,确认功能在哪个业务场景打开。再看 shouldShowSuperResolutionButton(),确认设备和媒体类型门槛。接着看按钮的 action,未增强时进入 runSuperResolution(),已增强时进入 clearSuperResolutionPreview()。
runSuperResolution() 保存 URI 与请求版本,然后调用 coreVisionApi26Service.enhanceImage(sourceUri)。进入服务后看 fileIo.open -> createImageSource -> createPixelMap -> ImageSRAnalyzer.create -> process -> createScaledPixelMap。服务返回后回到组件,先走过期检查,再写入 superResolutionPixelMap 和 superResolutionSourceUri。最后 buildPreviewPage() 因 isSuperResolutionActive() 变为 true,改为渲染 Image(PixelMap)。
恢复原图、横滑和退出最终都汇合到 clearSuperResolutionPreview(),所以资源出口只有一个。把这条主线掌握以后,再看日志、Toast、按钮位置和 AI 识图互斥会轻松很多。
用户看到的交互应该是什么
技术能力接通后,用户体验还需要把状态说清楚。我的设计里,入口文案和反馈遵循三个原则。
第一,按钮叫“图像超分”,无障碍提示补充“增强当前照片的清晰度并放大细节”。对普通用户可见的 Toast 用“增强预览”,因为这是当前操作的真实结果:图片只在预览组件中替换,并没有保存为一张新照片。
第二,处理期间不允许重复发起。按钮位置保持不变,只把图标替换为加载进度,用户知道任务还在继续,快速连点也不会创建多个分析器。
第三,结果可逆。成功 Toast 明确写“再次点击可对比原图”,增强按钮也切成恢复符号。图像超分不是永远比原图更符合用户偏好,尤其是老照片的人脸、文字和细纹理,用户应该能随时对照原图判断。
效果图占位:原图状态的按钮、处理中状态、增强完成状态三连图,三个画面使用同一尺寸裁切,便于看出按钮位置没有跳动。
效果图占位:双指放大同一区域后的原图与增强图对比,建议选择建筑窗格、衣服纹理或远处路牌,不要只放整张缩略图。
效果图占位:API 23 或不具备 VisionBase SysCap 的设备上,预览页正常打开但不显示图像超分入口。
日志怎么帮助定位问题
图像处理问题只看一句“失败了”通常不够。项目把服务阶段和 UI 阶段分开记录。服务日志标签是 CoreVisionApi26,关键阶段包括:
sr start
sr input-ready
sr analyzer-created
sr process-success
sr preview-created
sr failed
UI 日志使用 [CoreVisionApi26][SRPreview] 前缀,关键阶段包括:
stage=request
stage=discard-stale-result
stage=applied
stage=render-complete
stage=render-failed
stage=clear
stage=failed
如果日志停在 sr start 之后、没有 input-ready,优先检查 URI 是否仍可读、文件是否存在、图库授权是否还有效以及格式能否由 Image Kit 解码。如果有 input-ready、没有 analyzer-created,优先检查设备能力和系统服务状态。如果已经有 process-success,却没有 preview-created,问题多半发生在输出图信息读取或预览 PixelMap 创建阶段,内存压力也是检查方向。
如果服务出现 preview-created,UI 却没有 stage=applied,先找是否打印了 stage=discard-stale-result。有这条日志通常不是故障,而是用户在处理期间切图或关闭了页面,组件正确丢弃了过期结果。有 stage=applied 但没有 stage=render-complete,才需要继续看 ArkUI 渲染和 PixelMap 有效性。
耗时从服务开始记录到 process-success,主要反映 URI 打开、输入解码、分析器创建和超分处理的累计时间。preview-created 发生在之后,因此如果要做精确性能分析,我会增加解码耗时、分析器创建耗时、process() 耗时和缩放耗时四个独立区间,而不是只用一个总数下结论。
生产环境还要注意日志隐私。尺寸、阶段、耗时、错误码适合公开记录,完整 URI 和系统错误消息应根据数据分级做脱敏。文章为了对应源码展示了完整调试字符串,实际发布版本不应把用户的文件路径当成普通业务日志长期保存。
怎样验证接入不是“看起来能用”
我不会只拿一张正常 JPG 点成功就结束测试。图像超分同时涉及系统能力、文件格式、异步状态和大内存对象,测试矩阵至少应覆盖下面这些情况。
| 测试场景 | 操作 | 预期结果 |
|---|---|---|
| API 26 支持设备、普通低清 JPG | 打开瞬间静态图并点击超分 | 显示加载态,成功后切换增强预览并提示输出尺寸 |
| 模拟器 | 打开瞬间照片预览 | 不把能力不可用视为代码故障,改用符合地区条件的 API 26 真机验收 |
| 不在官方支持地区的设备 | 打开相同预览 | 入口自然降级;若系统仍报告 SysCap 可用,则以实际服务返回为准并做好失败提示 |
| API 低于 26 | 打开相同预览 | 不显示超分按钮,原图浏览、缩放和退出正常 |
| API 26 但 SysCap 不可用 | 打开相同预览 | 与不支持设备一致,服务若被直接调用则返回明确错误 |
| 高分辨率输入 | 点击超分并观察内存 | 输出预览最长边不超过 4096,页面不因长期持有超大图持续涨内存 |
| 竖拍且带方向信息的照片 | 对比原图和增强图 | 方向一致,不出现横置或镜像 |
| 透明 PNG | 点击超分 | 能处理则正确显示;能力不支持该内容时给出可读失败提示,不崩溃 |
| 损坏文件或失效 URI | 触发处理 | 解码失败进入 catch,加载态结束,原图或错误占位保持可操作 |
| 处理时快速横滑 | A 图点击后立刻滑到 B 图 | A 的晚到结果被释放,不覆盖 B,不在 B 上显示恢复按钮 |
| 处理时关闭页面 | 点击后立即关闭 | 页面正常退出,结果返回后被释放,不更新已消失组件 |
| 连续快速点击 | 在按钮可用时连点 | 只发起一次任务,处理期间显示固定尺寸加载控件 |
| 成功后再次点击 | 点击恢复按钮 | 增强 PixelMap 被释放,立刻显示原图 |
| 成功后滑到下一张 | 横向切换 | 上一张增强结果释放,下一张从原图状态开始 |
| 动态照片 | 打开带视频资源的照片 | 不展示超分入口,动态照片播放不受影响 |
| AI 识图支持设备 | 原图使用识图,再切增强 | 原图识图正常;增强态不叠加错位的识图交互;恢复后能力可继续使用 |
除了功能现象,还要检查日志闭环。一次成功任务应该能看到输入尺寸、处理输出尺寸、预览尺寸、耗时、UI 应用和渲染完成。一次主动切图应该出现请求、服务完成、丢弃过期结果,随后有资源清理。失败任务必须最终清掉 superResolutionLoadingUri,否则界面会永久停在 Loading 状态。
内存验证不能只观察任务执行瞬间的峰值,还要重复“增强、恢复、切图”多次,看内存能否回落到稳定区间。PixelMap.release() 是异步接口,这里用 void 发起释放,运行时实际回收可能不是瞬间完成,但不应该随着操作次数持续线性增长。
常见问题和排查方式
编译时找不到 imageSuperResolution
先检查工程的 compileSdkVersion 是否已经是 26.0.0,再确认本机 DevEco Studio 使用的 SDK 确实包含 API 26。只把 targetSdkVersion 改成 26,不代表编译器一定能找到新声明;真正提供编译符号的是编译 SDK。
导入必须来自 Core Vision Kit:
import {
imageSuperResolution,
visionBase
} from '@kit.CoreVisionKit';
不要从 @kit.VisionKit 导入,也不要自己在 oh-package.json5 里添加同名第三方依赖。SDK Kit 的使用方式和 ohpm 包不是一回事。
API 26 真机上按钮仍然不显示
项目的显示条件不是只看版本,还包括业务开关、SysCap 和媒体类型:
enableSuperResolution
&& sdkApiVersion >= 26
&& canIUse('SystemCapability.AI.Vision.VisionBase')
&& 当前不是动态照片
逐个打印这些条件即可定位。若从非瞬间详情入口打开,enableSuperResolution 可能本来就是 false;若当前媒体有动态照片视频 URI,隐藏按钮是产品设计;如果前两项满足而 canIUse 返回 false,应按设备不支持降级,而不是强行调用。
点击后一直转圈
先确认 runSuperResolution() 的 finally 是否无条件清理当前请求的 loadingUri。只有请求版本和 URI 仍匹配时才清理,是为了防止旧任务把新任务的加载状态关掉:
if (currentVersion === this.requestVersion &&
this.loadingUri === sourceUri) {
this.loadingUri = '';
}
如果服务日志停在某个阶段,按前文日志链排查。如果服务已经返回、UI 仍转圈,检查是否在接收结果前调用了会增加版本号的清理函数。项目成功接收时用 clearSuperResolutionPreview(false),参数 false 很关键:它只释放旧的已显示结果,不作废刚完成的当前请求。
增强结果一闪就消失
通常是 imageUri、Swiper 下标或组件 key 在结果回来时变化了。先看有没有 stage=discard-stale-result,再检查父组件是否因为无关状态刷新而重建了整个预览组件。《时光旅记》用 previewImageSessionId 生成 key,目的是区分一次次预览会话;同一会话中不应在超分完成时随意改变 key。
也要检查是否在图片 onComplete() 或其他监听里调用了 clearSuperResolutionPreview()。清理应该只发生在恢复原图、切换照片、关闭组件或明确开始替换旧结果的时机。
我在这个场景里做出的取舍
回到《时光旅记》,这次接入有几个明确边界。图像超分只在瞬间详情的静态照片全屏预览中开放;用户主动点击才执行;结果用于当前会话预览,不自动保存、不覆盖原图;输出预览最长边控制在 4096;动态照片不展示入口;增强态暂不叠加原图的 AI 识图交互;切图、恢复和退出都释放结果;不支持 API 26 或 SysCap 时直接降级。
这些边界不是为了少做功能,而是让能力和用户意图一致。用户在缩略图列表里不需要每张图自动超分,在动态照片播放中也不需要静态帧突然变样。真正需要增强时,他已经打开了某张照片并愿意等待一次处理,此时提供可逆的原图对比最合适。
从代码角度看,核心 API 调用只占很小一段。让我花更多时间的是资源所有权和异步状态:谁创建、谁释放;用户离开后结果归谁;上一张的任务能不能写到下一张;服务原始输出和 UI 预览输出是不是同一个对象;不支持设备是否会看到一个无效入口。把这些问题回答清楚,能力才算真正接进 APP,而不是只在 Demo 里跑通。
写在最后
Core Vision Kit 的图像超分调用并不复杂:准备 PixelMap,创建 ImageSRAnalyzer,构造 visionBase.Request,执行 process(),从 ISPResponse.pixelMap 取得结果。真正落到照片类 APP 时,需要把 API 26 兼容判断、图库 URI 解码、位图内存、异步竞态、组件生命周期和用户对比交互一起设计。
在《时光旅记》里,我没有把它做成一个孤立的“AI 功能页”,而是放到用户本来就在使用的瞬间照片预览里。低清老照片需要时点一下,处理完成直接在原位置看,想判断效果就再点一下恢复原图;设备不支持时,普通预览完全不受影响。这样的接入对用户来说足够自然,对工程来说也有明确边界。















































苏公安网备 32011402010933号