HarmonyOS Camera Kit手动对焦实战：ArkTS与C A

鸿蒙专家

在HarmonyOS NEXT 6.1.1（API 24）中，Camera Kit为专业影像场景带来了一项关键能力——无级手动对焦。对于微距拍摄、影视级拉焦或扫码场景下的焦段锁定，这套API让开发者能够通过[0.0, 1.0]范围的浮点数直接驱动对焦马达，彻底告别自动对焦的"拉风箱"问题。本文基于实际Demo，梳理ArkTS与C API两条实现路径，并整理避坑要点。

一、手动对焦API概览

在HarmonyOS 6.1.1中，手动对焦能力被封装在PhotoSession对象中，提供了两个核心接口族：

1. 能力查询：isFocusDistanceSupported()，返回boolean值。对于部分不支持音圈马达（VCM）的前置定焦镜头，通常会返回false，因此在实际调用对焦控制前，需要先通过该接口做能力探测。

2. 无级对焦控制：getFocusDistance()和setFocusDistance()。取值范围标准化为[0.0, 1.0]，其中0.0对应镜头物理极限的最近对焦距离（即超级微距模式下的焦点位置），1.0代表无限远（Infinity），同时也是相机默认的对焦状态。任意中间值都会等比例映射到真实物理对焦行程。

二、ArkTS侧实现路径

在ArkTS层，手动对焦的调用非常直观。以下是一个"对焦控制舱"Demo的关键流程：查询支持性、通过Slider实时调节对焦参数、记录操作日志。

项目结构方面，主要在entry模块新增一个页面CameraFocusDemo.ets，并在main_pages.json中注册路由。

核心代码片段如下：

2. import { camera } from '@kit.CameraKit';
3. import { BusinessError } from '@kit.BasicServicesKit';
5. // 1. 检查是否支持手动对焦
6. checkSupport(): void {
7.   try {
8.     // photoSession.isFocusDistanceSupported()
9.     let supported = true;
10.     this.isSupported = supported;
11.   } catch (e) {
12.     this.appendLog(`检测异常: ${(e as BusinessError).code}`);
13.   }
14. }
16. // 2. 响应Slider拉动，下发对焦指令
17. onFocusChange(value: number): void {
18.   this.currentFocus = value;
19.   try {
20.     // photoSession.setFocusDistance(value)
21.     if (value === 0.0) {
22.       this.appendLog('已到达极限微距 (0.0)');
23.     } else if (value === 1.0) {
24.       this.appendLog('已到达无限远 (1.0)');
25.     }
26.   } catch (e) {
27.     this.appendLog(`对焦失败: ${(e as BusinessError).code}`);
28.   }
29. }

复制代码

Slider组件需要注意：拖拽事件的回调频率极高（可能达到60fps甚至120fps），如果在Moving过程中频繁调用setFocusDistance，会由于底层IPC与硬件驱动的开销造成卡顿，甚至触发错误码7400102或底层死锁。因此务必只在拖拽结束（SliderChangeMode.End）或点击（SliderChangeMode.Click）时下发指令。

2. Slider({
3.   value: this.currentFocus,
4.   min: 0.0,
5.   max: 1.0,
6.   step: 0.01,
7.   style: SliderStyle.OutSet
8. })
9. .width('100%')
10. .onChange((value: number, mode: SliderChangeMode) => {
11.   // 仅在拖拽结束或点击时触发，避免频繁发指令
12.   if (mode === SliderChangeMode.End || mode === SliderChangeMode.Click) {
13.     this.onFocusChange(value);
14.   }
15. })
16. .enabled(this.isSupported)

复制代码

三、C API侧的对焦马达直驱

对于在C++ NDK层做计算视觉或游戏开发的场景，Camera Kit同样提供了原生接口，避免跨语言调用的开销。相关API位于capture_session.h中：

- OH_CaptureSession_IsFocusDistanceSupported：能力探针，输出bool
- OH_CaptureSession_GetFocusDistance：输出float指针（0.0f ~ 1.0f）
- OH_CaptureSession_SetFocusDistance：输入float驱动硬件

返回状态码均为Camera_ErrorCode类型（如CAMERA_OK）。这套C接口的价值在于，OpenGL/Vulkan的AR渲染管线可以直接在底层干预空间深度，无需频繁穿越JSI/Native边界。

四、避坑指南

1. 防抖与马达打架：同时开启激进的光学防抖（OIS）偏移注入和手动对焦时，底层镜头马达可能处于高频震动状态。在工业视觉或扫码场景中使用强制微距对焦时，建议锁定OIS或降低干预频率。

2. 频控警告：拖拽回调不等于对焦指令下发时机。setFocusDistance底层通过IPC与硬件驱动通信，高频调用会产生显著开销。最佳实践是仅在交互结束时下发一次，或者自行做节流/去抖。

3. Session状态约束：对焦距离强依赖底层硬件状态机。只能在CaptureSession正常初始化并完成Config之后调用相关接口，否则会抛出7400103（Session not config）错误。

五、总结

HarmonyOS 6.1.1通过setFocusDistance及对应的Native C API，补全了Camera Kit在焦段控制上的关键拼图。无论是扫码器、显微工具软件还是专业影像APP，都能通过这套标准化接口在毫厘之间掌控对焦行程。建议开发者在实际接入时，先做支持性探测，再合理设计UI交互的频率控制，避免性能问题。

（本文基于HarmonyOS NEXT 6.1.1 API 24实测经验整理，代码基于真实项目精简。）

热心网友1

感谢楼主分享！这篇实战总结很实用，尤其是避坑指南里的“拖拽回调不等于对焦指令下发时机”和“防抖与马达打架”这两点，确实是要踩过坑才能意识到的细节。Slider高频率回调导致底层IPC压力大这个问题，很多刚接触Camera Kit的开发者可能都会忽略，楼主的频控建议很关键。 另外想请教一下：C API侧直接驱动马达时，如果和ArkTS侧同时调用setFocusDistance，会不会有优先级或冲突的问题？还是说建议在项目里固定只用其中一条链路？期待楼主后续能补充一些关于OIS锁定和手动对焦配合的实际效果对比。

热心网友1

写得很扎实，正好最近也在折腾 Camera Kit 的手动对焦。最认同的是拖拽频控那点，Slider 直接绑 setFocusDistance 在真机上确实能感觉到明显卡顿，后来改成 End 和 Click 触发才稳定。另外 7400103 那个坑也踩过，没等 Session 初始化完就调，直接报错，后来在 onFocus 回调里加了状态判断才解决。 想请教一下，OIS 和手动对焦打架的问题，楼主有没有实际对比过开启和关闭 OIS 时的对焦响应差异？我这边在暗光环境下试，感觉影响还挺明显的，但不确定是不是个体机型差异。

热心网友1

这篇文章写得很实用，尤其关于Slider拖拽频率和setFocusDistance底层通信开销的提醒，真是踩过坑的人才能总结出来的经验。之前我处理CameraKit时也遇到过类似卡顿，当初也是没意识到End模式的重要性，最后还是加了个去抖才稳住。C API那边对做视觉渲染的团队确实友好，能直接在底层干预对焦行程，省掉不少跨语言开销。另外楼主提到OIS和手动对焦打架这一点也很关键，工业场景下这个组合拳确实容易出问题。收藏了，等API 24的机器到手再按这个指南实测一遍。