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

概述

随着移动摄影能力不断增强，微距拍摄已经成了智能手机相机里很重要的一环。HarmonyOS 6.0（API version 20）在 Camera Kit 中补上了一个很实用的能力：监听微距状态变化。对开发者来说，这意味着应用终于可以实时知道当前相机是否进入了微距模式，从而更自然地联动 UI、提示文案和拍照逻辑。

这类能力看上去不算'炫'，但落到实际产品里非常有价值。以前系统自动切换到微距镜头或开启微距算法时，应用层往往只能'猜'。现在有了事件监听，状态变化就从黑盒变成了可感知、可响应的信号。

微距状态监听：基础概念与 API

在相机开发里，最麻烦的事情之一就是底层状态和应用层不同步。用户把手机靠近物体后，系统可能自动进入微距模式；可如果应用拿不到这个信息，就没法及时显示提示、切换图标，甚至调整一些拍摄策略。

HarmonyOS 6.0 的 Camera Kit 在 VideoSession 和 PhotoSession 中都提供了 on('macroStatusChanged') 与 off('macroStatusChanged')，专门用来处理这类场景。

on('macroStatusChanged')

这个接口用于监听相机微距状态的变化。当系统因为拍摄距离、场景识别等原因切换到微距模式，或者从微距模式退出时，注册的回调会收到通知。

• 所属对象：
  • camera.VideoSession
  • camera.PhotoSession
• 起始版本：API version 20
• 元服务支持：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 负责取消订阅。状态一旦变化，系统会主动通知应用，而不是让应用自己去轮询或猜测当前是不是微距模式。

实战：做一个智能微距相机场景

为了让这个能力更直观，我们来做一个简单但很贴近真实产品的场景：当用户靠近拍摄对象，手机进入微距模式时，界面自动显示一个提示，比如'微距模式已开启'，同时亮起一个放大镜图标；当退出微距模式时，这些提示自动收起。

这里用 PhotoSession 来演示，VideoSession 的思路是一样的。

代码示例