文档开发者中心
我的

【Jack实战】如何给《时光旅记》接入API26的图像超分让老照片变得清晰

浏览138发布于2026-08-25 14:48中国香港
本文章最后由 Jack 于 2026-09-02 01:41 编辑

大家好,我是鸿蒙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 功能页”,而是放到用户本来就在使用的瞬间照片预览里。低清老照片需要时点一下,处理完成直接在原位置看,想判断效果就再点一下恢复原图;设备不支持时,普通预览完全不受影响。这样的接入对用户来说足够自然,对工程来说也有明确边界。

收藏
6
回复
9
分享
全部评论
authorIcon
大雷神
太秀了 我的Jack
回复于2026-09-11 07:42湖北
authorIcon
北墨NoLimit
厉害
回复于2026-09-03 12:16湖南
authorIcon
兔樂ovo
好厉害,赶紧体验
回复于2026-09-02 02:00广东
authorIcon
鱼鱼
学习
回复于2026-08-29 05:39广东
authorIcon
小呼噜
学习
回复于2026-08-26 02:15中国香港
authorIcon
智领未来
哇塞,对比明显哇
1
回复于2026-08-26 02:13中国香港
authorIcon
柳如是20
是的
回复于2026-09-02 23:10北京
authorIcon
飞行员舒克
这个图像超分的效果真厉害啊,照片好清晰!
1
回复于2026-08-26 00:54广东
authorIcon
Jack
嘿嘿,快来体验一下吧~
回复于2026-08-26 03:09中国香港
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
先看最终调用链
这次到底用了哪些技术
工程版本应该怎么配
是否需要权限和额外依赖
最小调用到底有几步
从图库 URI 准备输入 PixelMap
为什么输出还要再生成一张预览 PixelMap
完整服务层代码
为什么分析器在每次请求里创建
为什么所有清理都放在 finally
错误为什么重新包装
UI 不是拿到 PixelMap 就结束了
完整的独立预览组件
接回《时光旅记》的现有预览
入口展示与按钮位置
原图和增强图怎么共用缩放手势
为什么增强时暂时不叠加 AI 识图
切换照片时如何清理
一次完整点击的代码阅读顺序
用户看到的交互应该是什么
日志怎么帮助定位问题
怎样验证接入不是“看起来能用”
常见问题和排查方式
编译时找不到 imageSuperResolution
API 26 真机上按钮仍然不显示
点击后一直转圈
增强结果一闪就消失
我在这个场景里做出的取舍
写在最后
了解社区公约,与您携手共创和谐专业的开发者社区。