@capacitor/camera

本项目基于 @capacitor/camera@8.0.0 开发。

简介

@capacitor/camera是capacitor生态系统中的核心插件，提供相机拍摄照片、从相册选择已有图片的功能，同时支持权限校验、图片参数配置等能力，为跨平台应用开发提供设备差异化适配能力。插件兼容Android、iOS等主流移动平台及浏览器环境，本文档仅说明在OpenHarmony环境下的使用情况。

API 可实现：相机拍摄照片或从相册中选择已有的照片。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/camera

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/camera

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
  "pkg": "@capacitor/camera",
  "classpath": "Camera"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Camera)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Camera
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中src/main/cpp/Camera目录下的Camera.h、Camera.cpp、CMakeLists.txt文件引入到capacitor模块中src/main/cpp/Camera目录下。

将源码中src/main/ets/components/ImageCompress目录下的CameraAction.ets、ErrorCode.ets、ExifInfo.ets、ImageCompressEx.ets、ImageInfo.ets文件引入到capacitor模块中src/main/ets/components/ImageCompress目录下。

将源码中src/main/ets/components/MediaAction目录下的CameraDefine.ets、CameraSelectDialog.ets、CheckCameraPermission.ets、MediaAction.ets文件引入到capacitor模块中src/main/ets/components/MediaAction目录下。

4. 添加 ArkTS 配置

在capacitor模块的build-profile.json5文件中，buildOption/arkOptions/runtimeOnly/sources配置项数组中加入步骤 3 中拷贝的 ets 文件路径：

{
  "buildOption": {
    "arkOptions": {
      "runtimeOnly": {
        "sources": [
          "./src/main/ets/components/ImageCompress/CameraAction.ets",
          "./src/main/ets/components/MediaAction/MediaAction.ets",
          "./src/main/ets/components/MediaAction/CameraSelectDialog.ets",
          "./src/main/ets/components/MediaAction/CheckCameraPermission.ets"
        ]
      }
    }
  }
}

卸载

# 卸载 camera 插件
hionic plugin remove @capacitor/camera

约束与限制

兼容性

在以下版本中已测试通过：

1. capacitor: 8.0.0-ohos-8.0.0;SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony权限参考申请应用权限 ，使用相机拍摄功能需要配置相机权限，在主工程的module.json5的requestPermissions数组中添加以下权限配置：

{
  "name": "ohos.permission.CAMERA",
  "reason": "$string:camera",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
}

使用示例

示例1：相机拍摄或相册选取单张照片

该示例演示调用相机API，弹出选择弹窗，支持用户选择相机拍摄或从相册选取单张图片，配置图片质量并以Uri格式返回，可直接渲染展示。

import { Camera, CameraResultType } from '@capacitor/camera';

const takePicture = async () => {
  const image = await Camera.getPhoto({
    quality: 90,
    allowEditing: true,
    resultType: CameraResultType.Uri
  });

  // image.webPath 包含一个可以作为图片 src 设置的路径。
  // 您可以使用 image.path 访问原始文件，如果需要，可以将其传递给 Filesystem API 以读取图片的原始数据，
  // （或者将 resultType: CameraResultType.Base64 传递给 getPhoto）
  var imageUrl = image.webPath;

  // 现在可以将其设置为图片的 src
  imageElement.src = imageUrl;
};

使用说明

引入@capacitor/camera插件的Camera模块使用，所有API均基于Promise实现，支持异步调用，使用前建议先校验并申请对应权限。

1. 获取单张照片

弹出选择框，提示用户从相册选择一张照片或使用相机拍摄新照片，支持配置图片质量、尺寸、返回格式等参数。

方法签名

getPhoto(options: ImageOptions): Promise<Photo>

ImageOptions

参数	类型	描述	默认值
quality	number	返回为JPEG的画质，范围为0到100
allowEditing	boolean	是允许用户裁剪还是做小幅编辑（针对特定平台）。在 iOS 上，它只支持 CameraSource.Camera，但不支持 CameraSource.Photos。
resultType	CameraResultType	数据返回格式。目前，仅支持 'Base64'、'DataUrl' 或 'Uri'
saveToGallery	boolean	暂时无法支持	: false
width	number	保存图像的最大宽度,按照比例
height	number	保存图像的最大期望高度,按照比例
correctOrientation	boolean	是否要自动将图像“向上”旋转以校正纵向模式	: true
source	CameraSource	照片来源，‘PROMPT’选项，会提示用户选择相册或拍照	: CameraSource.Prompt
direction	CameraDirection	摄像头方向	: CameraDirection.Rear
presentationStyle	'fullscreen'	相机风格,默认全屏	: 'fullscreen'
webUseInput	boolean	是使用PWA元素体验还是文件输入，暂不支持
promptLabelHeader	string	‘PROMPT’ 选项，显示文本	: 'Photo'
promptLabelCancel	string	‘PROMPT’ 选项，显示文本，取消按钮	: 'Cancel'
promptLabelPhoto	string	‘PROMPT’ 选项，显示文本，选择已保存图片的按钮标签	: 'From Photos'
promptLabelPicture	string	‘PROMPT’ 选项，显示文本，打开相机的按钮标签	: 'Take Picture'

Photo

参数	类型	描述
base64String	string	如果使用 CameraResultType.Base64，则是图像的 base64 编码字符串表示
dataUrl	string	以“data：image/jpeg”开头的URL;base64，'以及如果使用 CameraResultType.DataUrl，则是 base64 编码的图像字符串表示。注意：在网页版中，文件格式可能会根据浏览器不同而有所不同。
path	string	如果使用 CameraResultType.Uri，路径将包含一个完整的、平台特定的文件 URL，之后可以通过文件系统 API 读取。
webPath	string	webPath 返回一条路径，可用于设置图像的 src 属性，以实现高效的加载和渲染。
exif	any	从图像中检索的Exif数据（如有）
format	string	图片的格式，比如：jpeg、png、gif。iOS和Android只支持jpeg。网页版支持 jpeg、png 和 gif，但具体可用性可能因浏览器而异。只有当 设置为 或 设置为 时，GIF才被支持。webUseInput``true``source``Photos
saved	boolean	无论图片是否保存到画廊。在Android和iOS上，如果用户未授予所需权限，保存到画廊可能会失败。在 Web 上没有画廊，因此总是返回 false。

2. 多选相册图片

打开系统相册，允许用户从相册中选择多张图片，支持配置图片质量、尺寸、选择数量上限。

方法签名

pickImages(options: GalleryImageOptions): Promise<GalleryPhotos>

GalleryImageOptions

参数	类型	描述	默认值
quality	number	图像质量为JPEG，从0到100
width	number	保存图像的最大宽度,按照比例
height	number	保存图像的最大期望高度，按照比例
correctOrientation	boolean	是否要自动将图像“向上”旋转以校正纵向模式	:true
presentationStyle	'fullscreen'	相机风格,默认全屏	: 'fullscreen'
limit	number	用户可选择的最大图片数量	0 (unlimited)

GalleryPhotos

参数	类型	描述
photos	GalleryPhoto[]	选择图片列表

GalleryPhoto

参数	类型	描述
path	string	完整的、平台特定的文件URL，之后可以通过Filesystem API读取。
webPath	string	webPath 返回一条路径，可用于设置图像的 src 属性，以实现高效的加载和渲染。
exif	any	从图像中检索的Exif数据（如有）
format	string	图片的格式，比如：jpeg、png、gif。iOS和Android只支持jpeg。网页支持jpeg、png和gif。

3. 检查权限状态

检查相机和相册的权限授予状态，返回对应权限的当前状态。

方法签名

checkPermissions(): Promise<PermissionStatus>

4. 申请权限

主动向系统申请相机、相册相关权限，获取权限后才可正常使用拍照、选图功能。

方法签名

requestPermissions(permissions?: CameraPluginPermissions): Promise<PermissionStatus>

CameraPluginPermissions

参数	类型
permissions	CameraPermissionType[]

CameraPermissionType

'camera' | 'photos'

5. 暂不支持方法

• pickLimitedLibraryPhotos()：从受限相册选择单张图片，暂不支持

• getLimitedLibraryPhotos()：从受限相册选择多张图片，暂不支持

数据类型定义

PermissionStatus

参数名	类型
camera	CameraPermissionState
photos	CameraPermissionState

类型别名

CameraPermissionState

PermissionState | 'limited'

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

枚举类型

CameraResultType

成员	取值
Uri	'uri'
Base64	'base64'
DataUrl	'dataUrl'

CameraSource

成员	取值	描述
Prompt	'PROMPT'	弹窗选择来源
Camera	'CAMERA'	相机拍摄
Photos	'PHOTOS'	相册选取

CameraDirection

成员	取值
Rear	'REAR'
Front	'FRONT'

目录结构

|---- 目录
|     |---- src/main   # 插件的实现代码
|           |----cpp   # C++ 代码
|           |----ets   # ArkTS 代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

使用过程中发现任何问题都可以提 Issue ，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。