API 23 Camera Kit全质量未压缩图与HDR动态照片

鸿蒙专家

HarmonyOS NEXT 6.1（API 23）为 Camera Kit 带来了三项重要更新：全质量图与未压缩图统一回调、全链路 HDR 动态照片、以及元数据检测类型的运行时增删。这些能力直接解决了高像素 YUV 原图获取、动态照片 HDR 撕裂、以及元数据切换需重建会话的痛点。本文通过一个“视觉新纪元中控舱”示例项目，展示这三项特性的实战配置与验证方法。

## 一、全质量图与未压缩图调度

在 API 23 之前，获取物理拍摄的未压缩 YUV 图需要依赖 imageReceiver 等中间件，容易导致主线程卡顿或时序紊乱。新版 PhotoOutput 提供了 `onCapturePhotoAvailable(callback: Callback<CapturePhoto>)` 回调，注册后即可直接接收 `CapturePhoto` 实例。该实例的 `main` 属性携带未压缩的 `image.Picture` 或 `image.Image`，无需额外转换。

开发约束：此回调内部禁止调用 `offCapturePhotoAvailable` 注销自身（避免套娃注销）；当拍摄未压缩 YUV 格式时，该回调是唯一合法的物理接收通路。

在实战代码中，注册监听后即可通过模拟拍摄触发回调，查看接收到的物理图片信息：

2. private onPhotoAvailableCallback = (capturePhoto: camera.CapturePhoto): void => {
3.     this.photoCapturedCount++;
4.     let picture: image.Image | image.Picture = capturePhoto.main;
5.     // 处理 picture ...
6. };
7. private registerPhotoAvailableListener(): void {
8.     // photoOutput.onCapturePhotoAvailable(this.onPhotoAvailableCallback);
9. }

复制代码

## 二、全链路 HDR 动态照片配置

动态照片（Live Photo）要求静态图和附带短视频均为高动态范围内容，才能避免色差与画质撕裂。配置 HDR 动态照片需两步先行：

1. 格式核验：通过 `getSupportedFullOutputCapability` 查询预览输出能力，选择 P010 深度色彩输出流（如 `CAMERA_FORMAT_YCRCB_P010` 或 `CAMERA_FORMAT_YCBCR_P010`）。
2. 色彩空间自检：通过 `getSupportedColorSpaces` 查询设备支持列表，并调用 `setColorSpace` 强制设为 `BT2020_HLG`。

只有流格式和色彩空间双项 HDR 标志均正确匹配，生成的动态照片才能具备通透高光、深邃暗部和完美色彩渐变。

示例中通过开关切换 HDR 模式，同时更新显示流格式和色彩空间状态：

2. private toggleHDRPhoto(enabled: boolean): void {
3.     if (enabled) {
4.         this.selectedFormat = 'CAMERA_FORMAT_YCRCB_P010';
5.         this.selectedColorSpace = 'BT2020_HLG';
6.     } else {
7.         this.selectedFormat = 'CAMERA_FORMAT_YUV_420_SP';
8.         this.selectedColorSpace = 'SRGB';
9.     }
10. }

复制代码

## 三、元数据检测流实时控制

传统方式下，切换检测类型（如从条码识别切到人脸检测）需要销毁 CameraSession 并重建，导致视觉闪烁与耗电。API 23 新增 `addMetadataObjectTypes` 和 `removeMetadataObjectTypes` 方法，允许在运行期动态增减检测对象类型，无需暂停或重建会话。

实战中通过 Checkbox 控制检测类型的激活状态：

2. private toggleMetadataType(type: string): void {
3.     const index = this.activeMetadataTypes.indexOf(type);
4.     if (index > -1) {
5.         // 注销该类型
6.         // metadataOutput.removeMetadataObjectTypes([camera.MetadataObjectType[type]]);
7.     } else {
8.         // 注册该类型
9.         // metadataOutput.addMetadataObjectTypes([camera.MetadataObjectType[type]]);
10.     }
11. }

复制代码

## 四、项目结构与验证演示

示例工程 CameraKitDemo 包含两个页面：Index.ets 作为入口，展示三项新特性概述并跳转到 CameraDemo.ets；CameraDemo.ets 为“中控舱”，集成三大模块：全质量图调度舱（注册/注销监听、模拟拍摄）、HDR 动态照片配置控制台（开关切换、状态显示）、元数据检测流实时控制台（ Checkbox 增删类型）。运行后即可直观验证各功能的注册、切换与回调触发。

通过以上实战，开发者可以快速掌握 API 23 Camera Kit 的核心更新，并在真实相机场景中无缝集成全质量未压缩图、HDR 动态照片与运行时元数据控制，大幅提升影像开发效率与用户体验。

热心网友5

感谢楼主的详细分享！API 23 这三个更新确实很实用，尤其是全质量未压缩图直接回调解决了之前需要额外中转的痛点，HDR 动态照片的全链路配置也能避免色差问题。想问下在元数据检测流实时控制中，如果同时添加多种检测类型（比如条码+人脸），性能开销大概会增加多少？另外 p010 格式的兼容性在目前主流设备上表现如何？

热心网友5

感谢楼主分享这么详细的实战经验！API 23 在 Camera Kit 上这几个更新确实切中痛点，尤其是全质量未压缩图直接回调，省去了 imageReceiver 的中间环节，性能上应该能改善不少。HDR 动态照片的全链路配置说明也很清楚，流格式和色彩空间双重校验的做法很实在。元数据检测类型的运行时增删更是实用，避免频繁重建会话带来的卡顿和功耗问题。示例项目的模块设计思路清晰，方便开发者快速上手验证。请问在实际测试中，P010 格式配合 BT2020_HLG 的色彩空间，在全平台机型上的兼容性表现如何？有没有遇到某些设备不支持的情况？

热心网友5

感谢分享，内容非常扎实！API 23 这三个更新确实切中了不少开发痛点——特别是全质量图回调省去了中间件折腾，运行时增删元数据类型也终于不用重建会话了。想请教一下，HDR 动态照片在 P010 格式下，不同机型的色彩空间支持情况是否一致？比如有些中端机型可能只支持 BT2020_HLG 的部分子集，你测试时有没有遇到 fallback 策略？