HarmonyOS 相机开发实战指南

开发准备：权限申请

在编写代码前，必须确保已申请必要权限。

3.1 声明权限

在 module.json5 中添加以下配置：

"requestPermissions": [
  {
    "name": "ohos.permission.CAMERA",
    "reason": "$string:camera_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:mic_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

说明：

• CAMERA：相机权限，必需。
• MICROPHONE：麦克风权限，录制视频时需要。
• MEDIA_LOCATION：如需在照片元数据中记录地理位置，需额外添加。

3.2 运行时授权

配置文件声明后，需在运行时向用户申请授权。

import { abilityAccessCtrl, bundleManager } from '@kit.AbilityKit';

async function requestCameraPermission(): Promise<boolean> {
  let atManager = abilityAccessCtrl.createAtManager();
  let token = await bundleManager.getAccessToken();

  // 先检查是否有权限
  let grantStatus = await atManager.checkAccessToken(token, 'ohos.permission.CAMERA');
  if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
    console.info('已有相机权限');
    return true;
  }

  // 无权限则申请
  let result = await atManager.requestPermissionsFromUser([
    'ohos.permission.CAMERA',
    'ohos.permission.MICROPHONE'
  ]);

  // 检查结果
  for (let permResult of result.authResults) {
    if (permResult !== 0) {
      console.error('用户拒绝了权限');
      return false;
    }
  }
  console.info('权限申请成功');
  return true;
}

建议：在应用启动阶段申请权限，避免用户点击拍照时才弹窗影响体验。

核心功能实现

4.1 获取相机管理器

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

function getCameraManager(context: common.BaseContext): camera.CameraManager | undefined {
  let cameraManager: camera.CameraManager;
  try {
    cameraManager = camera.getCameraManager(context);
  } catch (error) {
    console.error(`获取相机管理器失败：${error}`);
    return undefined;
  }
  return cameraManager;
}

注意：若获取失败，可能因相机被占用或设备无相机硬件，应终止后续操作。

4.2 获取支持的相机列表

function getSupportedCameras(
  cameraManager: camera.CameraManager
): Array<camera.CameraDevice> {
  let cameraArray: Array<camera.CameraDevice> = cameraManager.getSupportedCameras();
  if (cameraArray != undefined && cameraArray.length > 0) {
    for (let index = 0; index < cameraArray.length; index++) {
      console.info(`相机 ID: ${cameraArray[index].cameraId}`);
      console.info(`相机位置：${cameraArray[index].cameraPosition}`); // 前置/后置
      console.info(`相机类型：${cameraArray[index].cameraType}`); // 广角/长焦等
      console.info(`连接类型：${cameraArray[index].connectionType}`);
    }
    return cameraArray;
  } else {
    console.error('设备没有可用相机');
    return [];
  }
}

建议：将相机列表缓存，便于后续切换摄像头时使用。

4.3 监听相机状态

function onCameraStatusChange(cameraManager: camera.CameraManager): void {
  cameraManager.on('cameraStatus', (err, cameraStatusInfo) => {
    if (err != undefined && err.code !== 0) {
      console.error(`相机状态监听错误：${err.code}`);
      return;
    }
    // 新相机出现（如 USB 外接）
    if (cameraStatusInfo.status == camera.CameraStatus.CAMERA_STATUS_APPEAR) {
      console.info('新相机设备出现');
    }
    // 相机被移除
    if (cameraStatusInfo.status == camera.CameraStatus.CAMERA_STATUS_DISAPPEAR) {
      console.info('相机设备被移除');
    }
    // 相机可用（之前被占用，现释放）
    if (cameraStatusInfo.status == camera.CameraStatus.CAMERA_STATUS_AVAILABLE) {
      console.info('相机当前可用');
    }
    // 相机被占用
    if (cameraStatusInfo.status == camera.CameraStatus.CAMERA_STATUS_UNAVAILABLE) {
      console.info('相机被占用');
    }
    console.info(`相机 ID: ${cameraStatusInfo.camera.cameraId}`);
    console.info(`状态：${cameraStatusInfo.status}`);
  });
}

建议：应用启动时注册监听，及时处理状态变化。

4.4 创建相机输入流

async function createInput(
  cameraDevice: camera.CameraDevice,
  cameraManager: camera.CameraManager
): Promise<camera.CameraInput | undefined> {
  let cameraInput: camera.CameraInput | undefined = undefined;
  try {
    cameraInput = cameraManager.createCameraInput(cameraDevice);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`创建相机输入失败：${err.code}`);
  }
  if (cameraInput === undefined) {
    return undefined;
  }
  // 监听输入流错误
  cameraInput.on('error', cameraDevice, (error: BusinessError) => {
    console.error(`相机输入错误：${error.code}`);
  });
  // 打开相机
  await cameraInput.open();
  return cameraInput;
}

注意：创建前确保相机未被占用。

4.5 获取支持的模式

function getSupportedSceneModes(
  cameraDevice: camera.CameraDevice,
  cameraManager: camera.CameraManager
): Array<camera.SceneMode> {
  let sceneModeArray: Array<camera.SceneMode> = cameraManager.getSupportedSceneModes(cameraDevice);
  if (sceneModeArray != undefined && sceneModeArray.length > 0) {
    for (let index = 0; index < sceneModeArray.length; index++) {
      console.info(`支持的模式：${sceneModeArray[index]}`);
    }
    return sceneModeArray;
  } else {
    console.error('获取支持的模式失败');
    return [];
  }
}

常见模式：

• NORMAL_PHOTO：普通拍照
• NORMAL_VIDEO：普通录像
• HIGH_QUALITY_PHOTO：高质量拍照

4.6 获取输出能力

async function getSupportedOutputCapability(
  cameraDevice: camera.CameraDevice,
  cameraManager: camera.CameraManager,
  sceneMode: camera.SceneMode
): Promise<camera.CameraOutputCapability | undefined> {
  let cameraOutputCapability: camera.CameraOutputCapability = cameraManager.getSupportedOutputCapability(
    cameraDevice,
    sceneMode
  );
  if (!cameraOutputCapability) {
    console.error('获取输出能力失败');
    return undefined;
  }
  console.info(`输出能力：${JSON.stringify(cameraOutputCapability)}`);

  // 以 NORMAL_PHOTO 为例，需要预览流和拍照流
  let previewProfilesArray: Array<camera.Profile> = cameraOutputCapability.previewProfiles;
  let photoProfilesArray: Array<camera.Profile> = cameraOutputCapability.photoProfiles;

  if (!previewProfilesArray) {
    console.error('不支持预览流');
  }
  if (!photoProfilesArray) {
    console.error('不支持拍照流');
  }
  return cameraOutputCapability;
}

注意：创建输出流前务必检查设备是否支持。

会话管理

会话是相机开发的核心，所有配置均在会话中完成。

5.1 创建会话

function getSession(cameraManager: camera.CameraManager): camera.VideoSession | undefined {
  let videoSession: camera.VideoSession | undefined = undefined;
  try {
    // 以录像会话为例
    videoSession = cameraManager.createSession(camera.SceneMode.NORMAL_VIDEO) as camera.VideoSession;
  } catch (error) {
    let err = error as BusinessError;
    console.error(`创建会话失败：${err.code}`);
  }
  return videoSession;
}

注意：会话类型需与场景模式匹配（录像用 VideoSession，拍照用 PhotoSession）。

5.2 配置会话

function beginConfig(videoSession: camera.VideoSession): void {
  try {
    videoSession.beginConfig();
  } catch (error) {
    let err = error as BusinessError;
    console.error(`开始配置失败：${err.code}`);
  }
}

此步骤通知会话即将开始配置。

5.3 添加输入输出流

async function startSession(
  videoSession: camera.VideoSession,
  cameraInput: camera.CameraInput,
  previewOutput: camera.PreviewOutput,
  photoOutput: camera.PhotoOutput
): Promise<void> {
  // 1. 添加输入流
  try {
    videoSession.addInput(cameraInput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`添加输入流失败：${err.code}`);
  }

  // 2. 添加预览输出流
  let canAddPreviewOutput: boolean = false;
  try {
    canAddPreviewOutput = videoSession.canAddOutput(previewOutput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`检查预览流失败：${err.code}`);
  }
  if (!canAddPreviewOutput) {
    console.error('无法添加预览输出流');
    return;
  }
  try {
    videoSession.addOutput(previewOutput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`添加预览流失败：${err.code}`);
  }

  // 3. 添加拍照输出流
  let canAddPhotoOutput: boolean = false;
  try {
    canAddPhotoOutput = videoSession.canAddOutput(photoOutput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`检查拍照流失败：${err.code}`);
  }
  if (!canAddPhotoOutput) {
    console.error('无法添加拍照输出流');
    return;
  }
  try {
    videoSession.addOutput(photoOutput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`添加拍照流失败：${err.code}`);
  }

  // 4. 提交配置
  try {
    await videoSession.commitConfig();
  } catch (error) {
    let err = error as BusinessError;
    console.error(`提交配置失败：${err.code}`);
    return;
  }

  // 5. 启动会话
  try {
    await videoSession.start();
  } catch (error) {
    let err = error as BusinessError;
    console.error(`启动会话失败：${err.code}`);
  }
}

注意：

• 添加输出流前先用 canAddOutput 检查。
• 必须先提交配置 (commitConfig) 才能启动会话。
• 顺序不可颠倒。

5.4 会话切换

例如从拍照模式切换到录像模式：

async function switchOutput(
  videoSession: camera.VideoSession,
  videoOutput: camera.VideoOutput,
  photoOutput: camera.PhotoOutput
): Promise<void> {
  // 1. 停止当前会话
  try {
    await videoSession.stop();
  } catch (error) {
    let err = error as BusinessError;
    console.error(`停止会话失败：${err.code}`);
  }

  // 2. 开始重新配置
  try {
    videoSession.beginConfig();
  } catch (error) {
    let err = error as BusinessError;
    console.error(`开始配置失败：${err.code}`);
  }

  // 3. 移除拍照输出流
  try {
    videoSession.removeOutput(photoOutput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`移除拍照流失败：${err.code}`);
  }

  // 4. 添加视频输出流
  try {
    videoSession.canAddOutput(videoOutput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`检查视频流失败：${err.code}`);
  }
  try {
    videoSession.addOutput(videoOutput);
  } catch (error) {
    let err = error as BusinessError;
    console.error(`添加视频流失败：${err.code}`);
  }

  // 5. 提交配置
  try {
    await videoSession.commitConfig();
  } catch (error) {
    let err = error as BusinessError;
    console.error(`提交配置失败：${err.code}`);
  }

  // 6. 启动会话
  try {
    await videoSession.start();
  } catch (error) {
    let err = error as BusinessError;
    console.error(`启动会话失败：${err.code}`);
  }
}

建议：切换模式时给用户 Loading 提示，避免误以为卡死。

常见问题与解决方案

问题 1：权限未申请直接调用

错误示例：

// 直接获取 CameraManager
let cameraManager = camera.getCameraManager(context);
// 结果：报错'权限不足'

推荐做法：

// 先申请权限
let hasPermission = await requestCameraPermission();
if (!hasPermission) {
  promptAction.showToast({ message: '需要相机权限' });
  return;
}
// 再获取 CameraManager
let cameraManager = camera.getCameraManager(context);

问题 2：相机被占用未处理

错误示例：

// 直接创建输入流
let cameraInput = cameraManager.createCameraInput(cameraDevice);
// 结果：报错'相机被占用'

推荐做法：

// 先监听相机状态
cameraManager.on('cameraStatus', (err, info) => {
  if (info.status === camera.CameraStatus.CAMERA_STATUS_AVAILABLE) {
    // 相机可用，再创建
    let cameraInput = cameraManager.createCameraInput(cameraDevice);
  }
});

问题 3：输出流添加顺序错误

错误示例：

// 先添加输出流，再添加输入流
session.addOutput(previewOutput);
session.addInput(cameraInput);
// 结果：配置失败

推荐做法：

// 先输入，后输出
session.addInput(cameraInput);
session.addOutput(previewOutput);
session.addOutput(photoOutput);

问题 4：未检查 canAddOutput

错误示例：

// 直接添加输出流
session.addOutput(previewOutput);
// 结果：某些设备不支持，报错

推荐做法：

// 先检查
let canAdd = session.canAddOutput(previewOutput);
if (!canAdd) {
  console.error('设备不支持此输出流');
  return;
}
// 再添加
session.addOutput(previewOutput);

问题 5：会话配置完未提交

错误示例：

session.addInput(cameraInput);
session.addOutput(previewOutput);
// 忘了 commitConfig
session.start();
// 结果：启动失败

推荐做法：

session.addInput(cameraInput);
session.addOutput(previewOutput);
await session.commitConfig(); // 提交配置
await session.start();        // 启动会话

问题 6：释放资源不及时

错误示例：

// 用完相机直接返回
function closeCamera() {
  // 忘了释放
  return;
}

推荐做法：

async function closeCamera(session: camera.Session, cameraInput: camera.CameraInput) {
  // 1. 停止会话
  await session.stop();
  // 2. 关闭输入流
  await cameraInput.close();
  // 3. 释放会话
  session.release();
}

问题 7：模拟器测试相机

错误现象：

// 在模拟器上测试
let cameras = cameraManager.getSupportedCameras();
// 结果：空列表，误以为代码写错

真相：模拟器无相机硬件，无法获取相机列表。

推荐做法：真机调试，勿依赖模拟器测试相机功能。

完整实战案例

场景：简单的拍照应用

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

export class SimpleCameraManager {
  private cameraManager: camera.CameraManager | undefined;
  private cameraDevice: camera.CameraDevice | undefined;
  private cameraInput: camera.CameraInput | undefined;
  private session: camera.PhotoSession | undefined;
  private previewOutput: camera.PreviewOutput | undefined;
  private photoOutput: camera.PhotoOutput | undefined;

  // 初始化
  async init(context: common.BaseContext): Promise<boolean> {
    // 1. 获取相机管理器
    this.cameraManager = camera.getCameraManager(context);
    if (!this.cameraManager) {
      console.error('获取相机管理器失败');
      return false;
    }
    // 2. 获取相机列表
    let cameras = this.cameraManager.getSupportedCameras();
    if (cameras.length === 0) {
      console.error('没有可用相机');
      return false;
    }
    // 3. 选后置相机
    this.cameraDevice =
      cameras.find(c => c.cameraPosition === camera.CameraPosition.BACK) || cameras[0];
    // 4. 创建输入流
    this.cameraInput = this.cameraManager.createCameraInput(this.cameraDevice);
    await this.cameraInput.open();
    return true;
  }

  // 创建会话
  async createSession(): Promise<boolean> {
    if (!this.cameraManager || !this.cameraDevice) {
      return false;
    }
    // 1. 创建会话
    this.session = this.cameraManager.createSession(camera.SceneMode.NORMAL_PHOTO) as camera.PhotoSession;
    // 2. 开始配置
    this.session.beginConfig();
    // 3. 添加输入流
    this.session.addInput(this.cameraInput);
    // 4. 创建并添加输出流（此处省略具体创建过程）
    // this.previewOutput = await this.createPreviewOutput();
    // this.photoOutput = await this.createPhotoOutput();
    // this.session.addOutput(this.previewOutput);
    // this.session.addOutput(this.photoOutput);
    // 5. 提交配置
    await this.session.commitConfig();
    // 6. 启动会话
    await this.session.start();
    return true;
  }

  // 拍照
  async takePhoto(): Promise<string | undefined> {
    if (!this.photoOutput) {
      console.error('拍照输出流未创建');
      return undefined;
    }
    // 触发拍照
    let photoPath = await this.photoOutput.capture();
    console.info(`照片保存路径：${photoPath}`);
    return photoPath;
  }

  // 释放资源
  async release(): Promise<void> {
    // 1. 停止会话
    if (this.session) {
      await this.session.stop();
      this.session.release();
    }
    // 2. 关闭输入流
    if (this.cameraInput) {
      await this.cameraInput.close();
    }
  }
}

// 使用示例
let cameraManager = new SimpleCameraManager();
// 初始化
await cameraManager.init(context);
// 创建会话
await cameraManager.createSession();
// 拍照
let photoPath = await cameraManager.takePhoto();
// 释放
await cameraManager.release();

总结

Camera Kit 能力

• 预览、拍照、录像
• 闪光灯、对焦、曝光控制
• 多摄同开（部分设备支持）

开发流程

1. 申请权限（CAMERA、MICROPHONE）
2. 获取 CameraManager
3. 获取相机列表，选择一个
4. 创建 CameraInput
5. 创建 CameraSession
6. 添加输入输出流
7. 提交配置，启动会话
8. 拍照/录像
9. 释放资源

常见坑点

1. 权限未申请直接调用
2. 相机被占用未处理
3. 输出流添加顺序错误
4. 未检查 canAddOutput
5. 会话配置完未提交
6. 释放资源不及时
7. 在模拟器上测试

建议

• 简单拍照功能可使用 CameraPicker，无需自行实现 Camera Kit。
• 深度定制需关注：相机状态监听、canAddOutput 检查、资源及时释放。
• 务必使用真机测试，模拟器无法模拟相机硬件。