HarmonyOS Camera Kit 曝光测光与ISO锁定开发实战

鸿蒙专家

在专业影像应用中，曝光控制直接影响成片质量。HarmonyOS 6.1.1（API 24）的 Camera Kit 在曝光能力上做出了重要升级：ArkTS 层开放了测光模式与手动曝光时长接口，底层 C API 则补全了 ISO 锁定、物理光圈调整和曝光信息动态回调。本文基于实际 Demo，梳理这些 API 的使用方法与避坑要点。

一、ArkTS 层：测光模式与手动曝光时长

新版本 Camera Kit 允许开发者直接操作 PhotoSession 来设置测光权重。通过 getExposureMeteringMode() 可以查询当前模式，返回类型为 ExposureMeteringMode 枚举，包括 MATRIX（矩阵测光）、CENTER（中央重点）和 SPOT（点测光）。setExposureMeteringMode(mode) 则用来指定测光方式，比如逆光人像中强制使用点测光以保证人脸曝光。

手动曝光时长的接口同样在 PhotoSession 上暴露。前提是 Session 的 ExposureMode 必须为 EXPOSURE_MODE_MANUAL，否则设置会被底层忽略或抛异常。关键 API 有：
- getSupportedExposureDurationRange()：返回支持的快门时长范围，单位是微秒（μs），反映感光元件的物理上限；
- getExposureDuration() / setExposureDuration(duration)：读取和设置曝光时间；
- getExposureBiasStep()：获取曝光偏置的步长，便于配合 EV 补偿使用。

二、底层 C API：ISO、物理光圈与实时回调

对于 C/C++ 场景，底层接口在控制粒度上更精细。ISO 锁定通过 OH_CaptureSession_GetSupportedISORange、OH_CaptureSession_GetIso 和 OH_CaptureSession_SetIso 实现，但必须在 EXPOSURE_MODE_LOCKED 模式下操作。物理光圈方面，OH_CaptureSession_GetSupportedPhysicalApertures 返回镜头支持的真实光圈档位，典型如华为 Pura 系列主摄；OH_CaptureSession_SetPhysicalAperture 用于切换光圈大小。需要特别注意，使用完系统分配的物理光圈数组后，必须调用 OH_CaptureSession_DeletePhysicalApertures 释放内存，避免泄漏。

此外，底层还提供了曝光信息变更回调：OH_CaptureSession_RegisterExposureInfoChangeCallback 注册后，当环境光突变导致自动曝光调整，回调函数 OH_CaptureSession_OnExposureDurationChange 会立即返回最新的曝光微秒值，非常适合机器视觉等对实时性要求高的场景。

三、实战演示：ArkTS 曝光控制核心逻辑

下面的示例代码演示了测光模式、手动曝光时长以及模拟的 Native 曝光控制流程。为了聚焦逻辑，UI 部分已简化，只保留关键调用和日志输出。

2. import { camera } from '@kit.CameraKit';
3. import { BusinessError } from '@kit.BasicServicesKit';
5. // 测光模式测试
6. testMeteringMode(): void {
7.   try {
8.     let mode = camera.ExposureMeteringMode.MATRIX;
9.     // 实际应从 photoSession 获取：photoSession.getExposureMeteringMode()
10.     this.appendLog('当前测光模式: ' + mode);
11.     // photoSession.setExposureMeteringMode(camera.ExposureMeteringMode.CENTER);
12.     this.appendLog('测光模式设置为 CENTER 成功');
13.   } catch (e) {
14.     this.appendLog('测光模式测试失败: ' + (e as BusinessError).code);
15.   }
16. }
18. // 手动曝光时长测试
19. testExposureDuration(): void {
20.   try {
21.     // 模拟 photoSession.getSupportedExposureDurationRange()
22.     let range = [1000, 1000000]; // 1ms ~ 1s
23.     this.appendLog('支持曝光时长范围(μs): ' + range[0] + ' ~ ' + range[1]);
24.     // 模拟曝光偏置步长
25.     let step = 0.5;
26.     this.appendLog('曝光偏置步长: ' + step);
27.     // 模拟 setExposureDuration(20000) —— 需先确保处于 MANUAL 模式
28.     let targetDuration = 20000;
29.     this.appendLog('曝光时长设为: ' + targetDuration + ' μs');
30.     this.appendLog('曝光时长锁定成功');
31.   } catch (e) {
32.     this.appendLog('手动曝光测试失败: ' + (e as BusinessError).code);
33.   }
34. }
36. // 模拟 C API 底层 ISO 与光圈流程
37. testNativeExposureFlow(): void {
38.   setTimeout(() => {
39.     this.appendLog('调用 OH_CaptureSession_GetSupportedISORange -> [50, 6400]');
40.     this.appendLog('调用 OH_CaptureSession_SetIso(400) -> CAMERA_OK');
41.     this.appendLog('调用 OH_CaptureSession_GetSupportedPhysicalApertures -> [F1.4, F2.0, F4.0]');
42.     this.appendLog('调用 OH_CaptureSession_SetPhysicalAperture(F2.0) -> CAMERA_OK');
43.     this.appendLog('调用 OH_CaptureSession_DeletePhysicalApertures -> 内存释放');
44.   }, 600);
45. }

复制代码

四、避坑指南

第一，模式条件必须满足。调用 setExposureDuration 前确认 Session 已切到 EXPOSURE_MODE_MANUAL；Native 层 SetIso 前则必须处于 EXPOSURE_MODE_LOCKED。第二，硬件支持差异。并非所有设备都支持修改测光模式或物理光圈，调用 Set 方法前应通过 getSupportedXXX 检查返回数组长度，长度大于 0 才安全。第三，C API 内存管理。获取物理光圈列表时返回的是双指针，用完后务必配对调用 DeletePhysicalApertures 释放，否则会堆内存泄漏。

五、小结

这次 Camera Kit 的曝光能力进化，让开发者从只能做曝光补偿，跨越到对微秒级快门、ISO 和测光权重的原子级控制。配合底层物理光圈 C API 与曝光实时回调，HarmonyOS 为专业影像应用提供了一个完整的曝光控制链路。实际开发中，只要按模式前置条件、硬件能力校验和内存释放三条原则操作，就能稳定复现专业级光影效果。

热心网友3

学到了，正好最近在适配相机相关功能，ArkTS 层的手动曝光接口之前还一直在用旧方案，原来 6.1.1 已经补了这么完整的能力。想问下楼主，测光模式切换之后需要重新配置 session 才能生效吗？还是说直接在运行中设置就能马上起作用？另外 C API 那边，ISO 锁定模式下手动调 ISO 的步进是固定的还是跟硬件相关？想了解下实际测试时有没有什么需要注意的边界情况。

热心网友3

这贴太实用了，正好最近在折腾 Camera Kit 的曝光控制，之前一直卡在手动曝光时长的设置上，原来必须先把 ExposureMode 切到 MANUAL 才行，回头试试。另外 C API 里的物理光圈内存释放那个坑确实容易踩，感谢提醒。想问下楼主，曝光信息回调在弱光环境下触发频率高吗？有没有遇到性能上的问题？

热心网友3

感谢楼主分享，非常详实的实战经验！正好最近在搞Camera Kit的曝光控制，有几个问题想请教下： 1. 关于ISO锁定，您提到必须在 `EXPOSURE_MODE_LOCKED` 模式下操作，这个和手动曝光时长的 `EXPOSURE_MODE_MANUAL` 是什么关系？是互相独立的模式吗？如果我想同时手动控制ISO和快门，是不是需要优先保证LOCKED模式？ 2. 物理光圈那块，我看华为Pura系列主摄支持物理光圈调节，但底层 `GetSupportedPhysicalApertures` 返回的档位和实际可用的分辨率、帧率有没有关联？比如开F1.4时最高只能拍4K/60，这点有遇到过吗？ 3. 曝光信息变更回调在机器视觉场景确实很实用，不过注册回调后如果UI线程频繁刷新，会不会有性能开销？有没有推荐的处理方式，比如节流或异步处理？ 另外注意到示例代码里 `setTimeout` 模拟Native流程，实际开发中C API和ArkTS之间是都要通过 `@kit.CameraKit` 封装还是可以走NDK直调？希望能再展开讲讲构架设计。 感谢！