跳到主要内容
版本：v6

@capacitor/camera

相机API提供调用设备摄像头拍照或从相册中选择现有照片的功能。

安装​

npm install @capacitor/camera
npx cap sync

iOS配置​

iOS需要在应用的Info.plist文件中添加并填写以下使用描述字段：

  • NSCameraUsageDescription (隐私-相机使用说明)
  • NSPhotoLibraryAddUsageDescription (隐私-相册添加权限说明)
  • NSPhotoLibraryUsageDescription (隐私-相册使用说明)

更多关于在Xcode中设置iOS权限的信息，请参阅iOS指南中的配置Info.plist章节

Android配置​

当从设备相册选择现有图片时，Android系统会使用照片选择器组件。该组件在满足以下条件的设备上可用：

  • 运行Android 11（API级别30）或更高版本
  • 通过Google系统更新接收模块化系统组件变更

对于旧设备以及运行Android 11或12并支持Google Play服务的Android Go设备，可以安装向后兼容版本的照片选择器。要启用通过Google Play服务自动安装向后兼容的模块，请在AndroidManifest.xml文件的<application>标签内添加以下配置：

<!-- 触发Google Play服务安装向后兼容的照片选择器模块 -->
<!--suppress AndroidDomInspection -->
<service android:name="com.google.android.gms.metadata.ModuleDependencies"
    android:enabled="false"
    android:exported="false"
    tools:ignore="MissingClass">
    <intent-filter>
        <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
    </intent-filter>
    <meta-data android:name="photopicker_activity:0:required" android:value="" />
</service>

如果未添加此配置，不支持照片选择器的设备将回退使用Intent.ACTION_OPEN_DOCUMENT。

除非使用saveToGallery: true参数，否则相机插件不需要任何权限。如需使用该参数，则应在AndroidManifest.xml中添加以下权限：

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

也可以仅针对需要请求权限的Android版本进行指定：

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

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

更多关于设置Android权限的信息，请参阅Android指南中的权限设置章节。

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

变量​

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

  • androidxExifInterfaceVersion: androidx.exifinterface:exifinterface的版本（默认：1.3.6）
  • androidxMaterialVersion: com.google.android.material:material的版本（默认：1.10.0）

PWA注意事项​

相机插件需要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来获取Base64数据）
  var imageUrl = image.webPath;

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

API​

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

Interfaces​

Photo​

属性类型描述版本
base64Stringstring如果使用CameraResultType.Base64，则返回图像的base64编码字符串1.0.0
dataUrlstring如果使用CameraResultType.DataUrl，则返回以'data:image/jpeg;base64,'开头的URL和图像的base64编码字符串。注意：在Web上，文件格式可能因浏览器而异。1.0.0
pathstring如果使用CameraResultType.Uri，则path包含完整的平台特定文件URL，稍后可以使用Filesystem API读取。1.0.0
webPathstringwebPath返回可用于设置图片src属性的路径，以实现高效加载和渲染。1.0.0
exifany从图像中检索的Exif数据（如果有）1.0.0
formatstring图像格式，如jpeg、png、gif。iOS和Android仅支持jpeg。Web支持jpeg、png和gif，但具体可用性可能因浏览器而异。gif仅在webUseInput设置为true或source设置为Photos时支持。1.0.0
savedboolean图像是否已保存到相册。在Android和iOS上，如果用户未授予所需权限，保存到相册可能会失败。在Web上没有相册，因此始终返回false。1.1.0

ImageOptions​

属性类型描述默认值版本
qualitynumber返回JPEG图像的质量，0-100。注意：此选项仅在Android和iOS上受支持1.0.0
allowEditingboolean是否允许用户裁剪或进行小编辑（平台特定）。在iOS 14+上仅支持CameraSource.Camera，不支持CameraSource.Photos。1.0.0
resultType
CameraResultType
数据返回方式。当前仅支持'Base64'、'DataUrl'或'Uri'1.0.0
saveToGalleryboolean是否将照片保存到相册。如果照片是从相册选取的，则仅在编辑后才会保存。: false1.0.0
widthnumber保存图像的期望最大宽度。保持宽高比。1.0.0
heightnumber保存图像的期望最大高度。保持宽高比。1.0.0
correctOrientationboolean是否在竖屏模式下自动旋转图像"向上"以校正方向: true1.0.0
source
CameraSource
获取照片的来源。默认提示用户选择相册或拍照。: CameraSource.Prompt1.0.0
direction
CameraDirection
仅iOS和Web：相机方向。: CameraDirection.Rear1.0.0
presentationStyle'fullscreen' | 'popover'仅iOS：相机的呈现样式。: 'fullscreen'1.0.0
webUseInputboolean仅Web：是否使用PWA Element体验或文件输入。默认为如果安装了PWA Elements则使用它，否则回退到文件输入。要始终使用文件输入，请将此设置为true。了解更多关于PWA Elements：https://capacitorjs.com/docs/web/pwa-elements1.0.0
promptLabelHeaderstring显示提示时使用的文本值。: 'Photo'1.0.0
promptLabelCancelstring显示提示时使用的文本值。仅iOS：'取消'按钮的标签。: 'Cancel'1.0.0
promptLabelPhotostring显示提示时使用的文本值。选择已保存图像的按钮标签。: 'From Photos'1.0.0
promptLabelPicturestring显示提示时使用的文本值。打开相机的按钮标签。: 'Take Picture'1.0.0

GalleryPhotos​

属性类型描述版本
photosGalleryPhoto[]所有已选择照片的数组。1.2.0

GalleryPhoto​

属性类型描述版本
pathstring完整的平台特定文件URL，稍后可以使用Filesystem API读取。1.2.0
webPathstringwebPath返回可用于设置图片src属性的路径，以实现高效加载和渲染。1.2.0
exifany从图像中检索的Exif数据（如果有）1.2.0
formatstring图像格式，如jpeg、png、gif。iOS和Android仅支持jpeg。Web支持jpeg、png和gif。1.2.0

GalleryImageOptions​

属性类型描述默认值版本
qualitynumber返回JPEG图像的质量，0-100。注意：此选项仅在Android和iOS上受支持。1.2.0
widthnumber保存图像的期望最大宽度。保持宽高比。1.2.0
heightnumber保存图像的期望最大高度。保持宽高比。1.2.0
correctOrientationboolean是否在竖屏模式下自动旋转图像"向上"以校正方向: true1.2.0
presentationStyle'fullscreen' | 'popover'仅iOS：相机的呈现样式。: 'fullscreen'1.2.0
limitnumber用户能够选择的图片最大数量。注意：此选项仅在Android 13+和iOS上受支持。0 (无限制)1.2.0

PermissionStatus​

属性类型
camera
CameraPermissionState
photos
CameraPermissionState

CameraPluginPermissions​

属性类型
permissionsCameraPermissionType[]

Type Aliases​

CameraPermissionState​


  PermissionState | 'limited'

PermissionState​

Contents

编辑此页