HarmonyOS 6.0 Camera Kit 微距状态监听详解

概述

移动摄影技术日新月异，微距拍摄已成为智能手机相机不可或缺的核心功能。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 取消订阅。状态一变，系统主动告诉你当前是进入了微距世界还是回到了普通模式。

实战演练：构建一个智能微距相机场景

为了直观展示用法，我们构思一个简单的场景：当手机自动进入微距模式时，界面显示'放大镜'图标并提示用户；退出微距模式时，图标和提示消失。

完整的代码示例

下面展示了如何在 HarmonyOS 应用中使用 PhotoSession 实现上述逻辑。关键步骤和核心逻辑都已包含在内。

 { camera }  ;
 {  }  ;
 { promptAction }  ;


   {
     : camera. |  = ;
     :  = ;

    
     () {
        . = session;
         {
            
             macroStatusCallback = (: , : ):  {
                
                 (err !==  && err. !== ) {
                    .();
                    ;
                }
                
                . = macroStatus;
                 message = macroStatus ?  : ;
                .();
                
                
                promptAction.({
                    : message,
                    : 
                });
                
                
                
                .(macroStatus);
            };

            
            ..(, macroStatusCallback);
            .();
        }  (error) {
             err = error  ;
            .();
        }
    }

    
     () {
         (.) {
             {
                
                ..();
                
                
                .();
                . = ;
            }  (error) {
                 err = error  ;
                .();
            }
        }
    }

    
     () {
        
        .();
        
    }
}