@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,' 开头并包含图片 base64 编码字符串的 URL，当使用 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

属性	类型	说明	默认值	开始版本
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 Elements 体验还是文件输入。默认情况下，如果安装了 PWA Elements 则使用它，否则回退到文件输入。要始终使用文件输入，请将此值设为 true。了解更多关于 PWA Elements 的信息：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

属性	类型	说明	起始版本
path	string	完整的、平台特定的文件 URL，后续可以通过 Filesystem API 进行读取。	1.2.0
webPath	string	返回一个可用于设置图像 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 (unlimited)	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'