HarmonyOS：相机管理

一、概述

通过调用相机服务接口，开发者可以开发相机应用，访问和操作相机硬件，实现基础功能如预览、拍照和录像。此外，还可以通过接口组合完成更多操作，如控制闪光灯、曝光时间和对焦等。

说明

本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

二、示例

获取相机设备信息效果图

打开或关闭手电筒

示例代码

复制代码

import { camera } from '@kit.CameraKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let cameraManager: camera.CameraManager | undefined = undefined;
let context = getContext(this) as common.BaseContext;
let cameras: Array<camera.CameraDevice> = [];

/**
 * 获取相机管理器实例
 * @param context
 * @returns
 */
function getCameraManager(): camera.CameraManager | undefined {
  try {
    // 获取相机管理器实例，同步返回结果。
    cameraManager = camera.getCameraManager(context);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`The getCameraManager call failed. error code: ${err.code}`);
  }
  return cameraManager;
}

/**
 * 获取相机设备信息
 */
function getCameraDevice() {
  getCameraManager()
  if (cameraManager == undefined) {
    console.log("请先获取相机管理器实例")
    return
  }
  try {
    cameras = cameraManager.getSupportedCameras()
  } catch (error) {
    let err = error as BusinessError;
    console.error(`调用  getSupportedCameras 方法报错 error code: ${err.code}`);
  }
  if (cameras.length == 0) {
    console.log("未获取到相机设备")
  } else {
    cameras.forEach((cameraDevice, index, cameraDevices) => {
      console.log(`${index} 相机信息 相机ID: ${cameraDevice.cameraId} , 远端设备名称：${cameraDevice.hostDeviceName} , 相机位置: ${cameraDevice.cameraPosition} , 相机类型：${cameraDevice.cameraType}, 相机连接类型：${cameraDevice.connectionType}, 远端设备类型：${cameraDevice.hostDeviceType}, 相机安装角度：${cameraDevice.cameraOrientation}`)
    })
  }
  // 查询当前相机是否禁用
  let isMuted: boolean = cameraManager.isCameraMuted();
  console.log('查询当前相机是否禁用: ', isMuted)
  //  检测设备是否支持手电筒。
  let isSupported = cameraManager.isTorchSupported();
  console.log('检测设备是否支持手电筒: ', isSupported)
  // 检测是否支持设置的手电筒模式 TorchMode, 0	常关模式；1	常开模式；2	自动模式，系统根据环境自动调节手电筒亮度。
  let isTorchModeSupported = cameraManager.isTorchModeSupported(camera.TorchMode.AUTO);
  console.log('检测是否支持设置的手电筒模式: ', isTorchModeSupported)
  let torchMode: camera.TorchMode | undefined = undefined;
  // 获取当前设备手电筒模式
  torchMode = cameraManager.getTorchMode();
  console.log('获取当前设备手电筒模式: ', torchMode)
}

/**
 *  设置设备手电筒模式
 */
function setTorchMode(mode: camera.TorchMode) {
  getCameraManager()
  if (cameraManager == undefined) {
    console.log("请先获取相机管理器实例")
    return
  }
  if (mode == camera.TorchMode.ON) {
    registerTorchStatusChange(cameraManager)
  } else {
    unregisterTorchStatusChange(cameraManager)
  }
  // 设置设备手电筒模式
  try {
    //  TorchMode, 0	常关模式；1	常开模式；2	自动模式，系统根据环境自动调节手电筒亮度。
    cameraManager.setTorchMode(mode);
  } catch (error) {
    // 失败返回错误码error.code并处理。
    let err = error as BusinessError;
    console.error(`设置设备手电筒模式 setTorchMode 失败. error code: ${err.code}`);
  }
}

/**
 * @param err
 * @param torchStatusInfo
 */
function torchCallback(err: BusinessError, torchStatusInfo: camera.TorchStatusInfo): void {
  if (err !== undefined && err.code !== 0) {
    console.error(`手电筒状态变化回调 torchCallback Error, errorCode: ${err.code}`);
    return;
  }
  console.info(`手电筒状态变化回调 onTorchStatusChange, isTorchAvailable: ${torchStatusInfo.isTorchAvailable}, isTorchActive: ${torchStatusInfo.isTorchActive}, level: ${torchStatusInfo.torchLevel}`);
}

/**
 *
 * @param cameraManager
 */
function registerTorchStatusChange(cameraManager: camera.CameraManager): void {
  // 手电筒状态变化回调，通过注册回调函数获取手电筒状态变化。使用callback异步回调
  // 当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。
  cameraManager.on('torchStatusChange', torchCallback);
}

/**
 *
 * @param cameraManager
 */
function unregisterTorchStatusChange(cameraManager: camera.CameraManager): void {
  // 手电筒状态变化注销回调，通过注销回调函数取消获取手电筒状态变化。
  cameraManager.off('torchStatusChange');
}

@Entry
@Component
struct TestCamera {
  @State message: string = '相机管理';

  build() {
    Column({ space: 10 }) {
      Text(this.message)
        .id('TestCameraHelloWorld')
        .fontSize($r('app.float.page_text_font_20fp'))
        .fontWeight(FontWeight.Medium)
        .margin({ top: 10 })
      Button('获取相机设备信息')
        .fontSize(20)
        .fontWeight(FontWeight.Medium)
        .onClick(() => {
          getCameraDevice()
        })
      Row({ space: 10 }) {
        Button("打开手电筒")
          .fontSize(20)
          .fontWeight(FontWeight.Medium)
          .onClick(() => {
            setTorchMode(camera.TorchMode.ON)
          })
        Button("关闭手电筒")
          .fontSize(20)
          .fontWeight(FontWeight.Medium)
          .onClick(() => {
            setTorchMode(camera.TorchMode.OFF)
          })
      }.margin({ top: 10 })

    }
    .height('100%')
    .width('100%')
  }
}

三、相关API

3.1 相机设备信息

CameraDevice

相机设备信息。
系统能力： SystemCapability.Multimedia.Camera.Core

名称	类型	只读	可选	说明
cameraId	string	是	否	相机ID。
cameraPosition	CameraPosition	是	否	相机位置。
cameraType	CameraType	是	否	相机类型。
connectionType	ConnectionType	是	否	相机连接类型。
cameraOrientation	number	是	否	相机安装角度，不会随着屏幕旋转而改变，取值范围为0°-360°，单位：度。
hostDeviceName	string	是	否	远端设备名称。
hostDeviceType	HostDeviceType	是	否	远端设备类型。

3.2 相机位置

CameraPosition

枚举，相机位置。

元服务API：从API version 12开始，该接口支持在元服务中使用。
系统能力： SystemCapability.Multimedia.Camera.Core

名称	值	说明
CAMERA_POSITION_UNSPECIFIED	0	相对于设备屏幕没有固定的朝向的相机。
CAMERA_POSITION_BACK	1	后置相机。
CAMERA_POSITION_FRONT	2 前置相机。
CAMERA_POSITION_FOLD_INNER	3	折叠态相机。从API version 11开始支持，从API version 12开始废弃。

3.3 相机类型

CameraType

枚举，相机类型。
系统能力： SystemCapability.Multimedia.Camera.Core

名称	值	说明
CAMERA_TYPE_DEFAULT	0	相机类型未指定。
CAMERA_TYPE_WIDE_ANGLE	1	广角相机。
CAMERA_TYPE_ULTRA_WIDE	2	超广角相机。
CAMERA_TYPE_TELEPHOTO	3	长焦相机。
CAMERA_TYPE_TRUE_DEPTH	4	带景深信息的相机。

3.4 相机模式

SceneMode

枚举，相机模式。
系统能力： SystemCapability.Multimedia.Camera.Core

名称	值	说明
NORMAL_PHOTO	1	普通拍照模式。
NORMAL_VIDEO	2	普通录像模式。
SECURE_PHOTO	12	安全相机模式。

3.5 相机管理器类

相机管理器类，使用前需要通过getCameraManager接口获取相机管理实例
getSupportedCameras

getSupportedCameras(): Array<CameraDevice>

获取支持的相机设备对象，同步返回结果。
系统能力 ： SystemCapability.Multimedia.Camera.Core
返回值： Array<CameraDevice> 相机设备列表。

3.6 查询当前相机是否禁用

isCameraMuted(): boolean

查询当前相机是否禁用。
系统能力 ： SystemCapability.Multimedia.Camera.Core
返回值： boolean 返回true表示相机被禁用，返回false表示相机未被禁用。

3.7 检测是否支持设置的手电筒模式

isTorchModeSupported(mode: TorchMode): boolean

检测是否支持设置的手电筒模式。
系统能力 ： SystemCapability.Multimedia.Camera.Core
参数：

参数名	类型	必填	说明
mode	TorchMode	是	手电筒模式。传参为null或者undefined，作为0处理，手电筒关闭。

返回值：

类型	说明
boolean	返回true表示设备支持设置的手电筒模式，返回false表示设备不支持的手电筒模式。

3.8 获取当前设备手电筒模式

getTorchMode(): TorchMode

获取当前设备手电筒模式。
系统能力： SystemCapability.Multimedia.Camera.Core

返回值：

类型	说明
TorchMode	返回设备当前手电筒模式。

TorchMode 枚举，手电筒模式。

系统能力： SystemCapability.Multimedia.Camera.Core

名称	值	说明
OFF	0	常关模式。
ON	1	常开模式。
AUTO	2	自动模式，系统根据环境自动调节手电筒亮度。

3.9 设置设备手电筒模式

setTorchMode(mode: TorchMode): void

设置设备手电筒模式。
系统能力： SystemCapability.Multimedia.Camera.Core

返回值：

参数名	类型	说明	必填说明
mode	TorchMode	是	手电筒模式。传参为null或者undefined，作为0处理，手电筒关闭。

3.10 手电筒状态变化回调

on(type: 'torchStatusChange', callback: AsyncCallback<TorchStatusInfo>): void

手电筒状态变化回调，通过注册回调函数获取手电筒状态变化。使用callback异步回调。
说明

当前注册监听接口，不支持在on监听的回调方法里，调用off注销回调。

系统能力： SystemCapability.Multimedia.Camera.Core

参数：

参数名	类型	必填	说明
type	string	是	监听事件，固定为'torchStatusChange'。cameraManager对象获取成功后可监听。目前只支持手电筒打开，手电筒关闭，手电筒不可用，手电筒恢复可用会触发该事件并返回对应信息。
callback	AsyncCallback<TorchStatusInfo>	是	回调函数，用于获取手电筒状态变化信息。

示例

c 复制代码

import { BusinessError } from '@kit.BasicServicesKit';


function callback(err: BusinessError, torchStatusInfo: camera.TorchStatusInfo): void {
  if (err !== undefined && err.code !== 0) {
    console.error(`Callback Error, errorCode: ${err.code}`);
    return;
  }
  console.info(`onTorchStatusChange, isTorchAvailable: ${torchStatusInfo.isTorchAvailable}, isTorchActive: ${torchStatusInfo.isTorchActive}, level: ${torchStatusInfo.torchLevel}`);
}


function registerTorchStatusChange(cameraManager: camera.CameraManager): void {
  cameraManager.on('torchStatusChange', callback);
}

3.11 手电筒状态变化注销回调

off(type: 'torchStatusChange', callback?: AsyncCallback<TorchStatusInfo>): void

手电筒状态变化注销回调，通过注销回调函数取消获取手电筒状态变化。

系统能力： SystemCapability.Multimedia.Camera.Core

参数：

参数名	类型	必填	说明
type	string	是	监听事件，固定为'torchStatusChange'。cameraManager对象获取成功后可监听。
callback	AsyncCallback<TorchStatusInfo>	否	回调函数，如果指定参数则取消对应callback（callback对象不可是匿名函数），否则取消所有callback。

示例

c 复制代码

function unregisterTorchStatusChange(cameraManager: camera.CameraManager): void {
  cameraManager.off('torchStatusChange');
}