概述
在移动摄影领域，微距拍摄已成为智能手机相机不可或缺的核心功能之一，它让用户能够探索和记录肉眼难以察觉的细节之美。HarmonyOS 6.0（对应 API version 20）在 Camera Kit 中带来了一项重要的能力更新：对微距状态变化事件的监听支持。这一更新标志着应用开发者现在可以精确、实时地感知相机硬件或算法微距模式的开启与关闭，从而为用户带来更智能、更流畅的微距拍摄体验。
咱们来拆解一下这个新特性，从基础概念入手，详细介绍其 API 定义、使用场景，并通过完整的代码示例和细致的分析，帮助开发者快速掌握并应用这一强大功能。
微距状态监听：基础概念与 API 解析
在传统的相机应用开发中，开发者通常难以直接得知相机当前是否处于微距模式。用户靠近被摄物体时，系统可能会自动切换到微距镜头或激活微距算法，但应用层无法感知这一状态变化，导致无法及时调整 UI 提示、优化拍照参数或提供针对性的功能引导。
HarmonyOS 6.0 Camera Kit 通过在 VideoSession（录像会话）和 PhotoSession（拍照会话）中同时引入 on('macroStatusChanged') 和 off('macroStatusChanged') 方法，完美解决了这一痛点。
核心接口：on('macroStatusChanged')
这个方法用于监听相机微距状态的变化。当系统因场景变化（如镜头与被摄物体的距离）自动进入或退出微距模式时，通过注册的回调函数通知应用。
- 所属对象：camera.VideoSession (录像模式会话)、camera.PhotoSession (拍照模式会话)
- 起始版本：API version 20 (HarmonyOS 6.0)
- 元服务支持：从 API version 20 开始，该接口支持在元服务中使用，拓展了其应用范围。
- 系统能力：SystemCapability.Multimedia.Camera.Core
- 参数详解：
type: string：监听事件类型，固定为'macroStatusChanged'。callback: AsyncCallback<boolean>：异步回调函数，用于接收微距状态。回调参数macroStatus是一个布尔值：true：表示微距模式已开启。false：表示微距模式已禁用。
核心接口：off('macroStatusChanged')
该方法用于注销微距状态变化的监听，释放相关资源。
- 起始版本：API version 20
- 参数详解：
type: string：注销的事件类型，固定为'macroStatusChanged'。callback?: AsyncCallback<boolean>：可选参数。若指定了具体的回调函数（不能是匿名函数），则仅注销该回调；若不指定，则注销所有与该事件关联的回调。
简单来说，这两个 API 为开发者提供了一个观察者模式的接口。on 方法让你订阅'微距状态变化'这一通知，off 方法让你取消订阅。当状态发生变化时，系统会主动回调你注册的函数，并告诉你当前是进入了微距世界（true），还是回到了普通拍摄模式（false）。
实战演练：构建一个智能微距相机场景
为了更直观地展示如何使用这一新特性，我们构思一个简单的相机应用场景：当用户靠近被摄物体，手机自动进入微距模式时，应用界面会动态显示一个'放大镜'图标，并提示用户'微距模式已开启'。当远离物体退出微距模式时，图标和提示消失。
完整的代码示例
以下代码展示了如何在 HarmonyOS 应用中使用 PhotoSession 实现上述场景。关键步骤和核心逻辑都包含在内。
import { camera } from ;
{ } ;
{ promptAction } ;
{
: camera. | = ;
: = ;
() {
. = session;
{
macroStatusCallback = (: , : ): {
(err !== && err. !== ) {
.();
;
}
. = macroStatus;
message = macroStatus ? : ;
.();
promptAction.({
: message,
:
});
.(macroStatus);
};
..(, macroStatusCallback);
.();
} (error) {
err = error ;
.();
}
}
() {
(.) {
{
..();
.();
. = ;
} (error) {
err = error ;
.();
}
}
}
() {
.();
}
}
