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 实现上述逻辑。

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


   {
   : camera. |  = ;
   :  = ;

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

        
        promptAction.({ message, :  });

        
        .(macroStatus);
      };

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

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

  
   () {
    .();
    
  }
}