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>：异步回调函数。
    • true：表示微距模式已开启
    • false：表示微距模式已禁用

核心接口：off('macroStatusChanged')

用于注销微距状态变化的监听，释放相关资源。

• 起始版本：API version 20
• 参数详解：
  • type: string：固定为 'macroStatusChanged'
  • callback?: AsyncCallback<boolean>：可选。若指定具体回调函数，仅注销该回调；若不指定，则注销所有关联回调。

简而言之，这两个 API 提供了观察者模式接口。on 订阅'微距状态变化'通知，off 取消订阅。状态变化时，系统主动回调你注册的函数，告知当前是进入了微距世界还是普通拍摄模式。

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

为了直观展示如何使用这一特性，我们构建一个简单场景：当手机自动进入微距模式时，界面显示'放大镜'图标及提示；退出时，图标和提示消失。

完整代码示例

以下代码展示了如何在 HarmonyOS 应用中使用 PhotoSession 实现上述逻辑。

import { camera } from '@kit.CameraKit';
 {  }  ;
 { promptAction }  ;


   {
     : camera. |  = ;
     :  = ;

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

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

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

    
     () {
        
        .();
        
    }
}