@capacitor/camera

Camera API 提供使用相机拍照或从相册选择现有照片的能力。

安装

npm install @capacitor/camera
npx cap sync

iOS

iOS 需要在应用的 Info.plist 中添加并填写以下使用说明：

• NSCameraUsageDescription（隐私 - 相机使用说明）
• NSPhotoLibraryAddUsageDescription（隐私 - 相册添加使用说明）
• NSPhotoLibraryUsageDescription（隐私 - 相册使用说明）

阅读 iOS 指南中的配置 Info.plist 以获取有关在 Xcode 中设置 iOS 权限的更多信息。

Android

此 API 需要在您的 AndroidManifest.xml 中添加以下权限：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

存储权限用于读取/保存照片文件。

阅读 Android 指南中的设置权限以获取有关设置 Android 权限的更多信息。

此外，由于 Camera API 会启动一个单独的 Activity 来处理拍照，您应该在 App 插件中监听 appRestoredResult，以处理在 Activity 运行时您的应用被操作系统终止的情况下可能发送的任何相机数据。

变量

该插件将使用以下项目变量（在应用的 variables.gradle 文件中定义）：

• $androidxExifInterfaceVersion：androidx.exifinterface:exifinterface 的版本（默认值：1.3.3）
• $androidxMaterialVersion：com.google.android.material:material 的版本（默认值：1.6.1）

PWA 说明

Camera 插件需要 PWA Elements 才能工作。

示例

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;
};

API

• getPhoto(...)
• pickImages(...)
• pickLimitedLibraryPhotos()
• getLimitedLibraryPhotos()
• checkPermissions()
• requestPermissions(...)
• 接口
• 类型别名
• 枚举

getPhoto(...)

getPhoto(options: ImageOptions) => Promise<Photo>

提示用户从相册选择照片或使用相机拍摄新照片。

参数	类型
options	ImageOptions

返回：

Promise<Photo>

自从： 1.0.0

---

pickImages(...)

pickImages(options: GalleryImageOptions) => Promise<GalleryPhotos>

允许用户从相册中选择多张图片。 在 iOS 13 及更早版本上，只允许选择一张图片。

参数	类型
options	GalleryImageOptions

返回：

Promise<GalleryPhotos>

自从： 1.2.0

---

pickLimitedLibraryPhotos()

pickLimitedLibraryPhotos() => Promise<GalleryPhotos>

仅 iOS 14+：允许用户更新其有限的相册选择。 在 iOS 15+ 上，在选择器关闭后返回所有有限的照片。 在 iOS 14 上或如果用户已授予对照片的完全访问权限，则返回空数组。

返回：

Promise<GalleryPhotos>

自从： 4.1.0

---

getLimitedLibraryPhotos()

getLimitedLibraryPhotos() => Promise<GalleryPhotos>

仅 iOS 14+：返回从有限相册中选择的照片数组。

返回：

Promise<GalleryPhotos>

自从： 4.1.0

---

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

检查相机和相册权限。

返回：

Promise<PermissionStatus>

自从： 1.0.0

---

requestPermissions(...)

requestPermissions(permissions?: CameraPluginPermissions | undefined) => Promise<PermissionStatus>

请求相机和相册权限。

参数	类型
permissions	CameraPluginPermissions

返回：

Promise<PermissionStatus>

自从： 1.0.0

---

接口

Photo

属性	类型	描述	自从
base64String	string	图像的 base64 编码字符串表示，如果使用 CameraResultType.Base64。	1.0.0
dataUrl	string	以 'data:image/jpeg;base64,' 开头的 URL 和图像的 base64 编码字符串表示，如果使用 CameraResultType.DataUrl。	1.0.0
path	string	如果使用 CameraResultType.Uri，该路径将包含一个完整的、平台特定的文件 URL，稍后可以使用 Filesystem API 读取。	1.0.0
webPath	string	webPath 返回一个可用于设置图像 src 属性的路径，以便高效加载和渲染。	1.0.0
exif	any	从图像中获取的 Exif 数据（如果有）。	1.0.0
format	string	图像的格式，例如：jpeg、png、gif。iOS 和 Android 仅支持 jpeg。Web 支持 jpeg 和 png。gif 仅在使用文件输入时支持。	1.0.0
saved	boolean	图像是否已保存到相册。在 Android 和 iOS 上，如果用户未授予所需的权限，保存到相册可能会失败。在 Web 上没有相册，因此始终返回 false。	1.1.0

ImageOptions

属性	类型	描述	默认值	自从
quality	number	返回的 JPEG 图像质量，0-100。		1.0.0
allowEditing	boolean	是否允许用户裁剪或进行小幅编辑（平台特定）。在 iOS 14+ 上，仅支持 CameraSource.Camera，不支持 CameraSource.Photos。		1.0.0
resultType	CameraResultType	数据应如何返回。目前仅支持 'Base64'、'DataUrl' 或 'Uri'。		1.0.0
saveToGallery	boolean	是否将照片保存到相册。如果照片是从相册中选择的，则仅在编辑后才保存。	: false	1.0.0
width	number	保存图像的最大期望宽度。会保持宽高比。		1.0.0
height	number	保存图像的最大期望高度。会保持宽高比。		1.0.0
correctOrientation	boolean	是否自动旋转图像"向上"以纠正竖屏模式下的方向。	: true	1.0.0
source	CameraSource	获取照片的来源。默认情况下，会提示用户选择相册或拍照。	: CameraSource.Prompt	1.0.0
direction	CameraDirection	仅 iOS 和 Web：相机方向。	: CameraDirection.Rear	1.0.0
presentationStyle	'fullscreen' | 'popover'	仅 iOS：相机的呈现样式。	: 'fullscreen'	1.0.0
webUseInput	boolean	仅 Web：是否使用 PWA Element 体验或文件输入。默认使用已安装的 PWA Elements，否则回退到文件输入。要始终使用文件输入，请设置为 true。了解更多：https://capacitorjs.com/docs/web/pwa-elements		1.0.0
promptLabelHeader	string	显示提示时使用的文本值。	: 'Photo'	1.0.0
promptLabelCancel	string	显示提示时使用的文本值。仅 iOS：'取消'按钮的标签。	: 'Cancel'	1.0.0
promptLabelPhoto	string	显示提示时使用的文本值。选择已保存图像的按钮标签。	: 'From Photos'	1.0.0
promptLabelPicture	string	显示提示时使用的文本值。打开相机的按钮标签。	: 'Take Picture'	1.0.0

GalleryPhotos

属性	类型	描述	自从
photos	GalleryPhoto[]	所有选定照片的数组。	1.2.0

GalleryPhoto

属性	类型	描述	自从
path	string	完整的、平台特定的文件 URL，稍后可以使用 Filesystem API 读取。	1.2.0
webPath	string	webPath 返回一个可用于设置图像 src 属性的路径，以便高效加载和渲染。	1.2.0
exif	any	从图像中获取的 Exif 数据（如果有）。	1.2.0
format	string	图像的格式，例如：jpeg、png、gif。iOS 和 Android 仅支持 jpeg。Web 支持 jpeg、png 和 gif。	1.2.0

GalleryImageOptions

属性	类型	描述	默认值	自从
quality	number	返回的 JPEG 图像质量，0-100。		1.2.0
width	number	保存图像的最大期望宽度。会保持宽高比。		1.2.0
height	number	保存图像的最大期望高度。会保持宽高比。		1.2.0
correctOrientation	boolean	是否自动旋转图像"向上"以纠正竖屏模式下的方向。	: true	1.2.0
presentationStyle	'fullscreen' | 'popover'	仅 iOS：相机的呈现样式。	: 'fullscreen'	1.2.0
limit	number	仅 iOS：用户能够选择的最大图片数量。	0（无限制）	1.2.0

PermissionStatus

属性	类型
camera	CameraPermissionState
photos	CameraPermissionState

CameraPluginPermissions

属性	类型
permissions	CameraPermissionType[]

类型别名

CameraPermissionState

PermissionState | 'limited'

PermissionState

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

CameraPermissionType

'camera' | 'photos'

枚举

CameraResultType

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

CameraSource

成员	值	描述
Prompt	'PROMPT'	提示用户选择相册或拍照。
Camera	'CAMERA'	使用相机拍摄新照片。
Photos	'PHOTOS'	从相册中选择现有照片。

CameraDirection

成员	值
Rear	'REAR'
Front	'FRONT'