版本：v8

@capacitor/camera

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

安装

npm install @capacitor/camera
npx cap sync

iOS

iOS 要求在您应用的 Info.plist 中添加并填写以下使用描述：

NSCameraUsageDescription（Privacy - Camera Usage Description）
NSPhotoLibraryAddUsageDescription（Privacy - Photo Library Additions Usage Description）
NSPhotoLibraryUsageDescription（Privacy - Photo Library Usage Description）

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

Android

当从设备图库中选择现有图片时，现在会使用 Android Photo Picker 组件。Photo Picker 适用于满足以下条件的设备：

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

老旧设备和运行 Android 11 或 12 且支持 Google Play 服务的 Android Go 设备，可以安装一个向后移植版本的 photo picker。要启用通过 Google Play 服务自动安装向后移植的 photo picker 模块，请在您的 AndroidManifest.xml 文件的 <application> 标签中添加以下条目：

<!-- 触发 Google Play 服务安装向后移植的 photo picker 模块。 -->
<!--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>

如果没有添加该条目，在不支持 Photo Picker 的设备上，Photo Picker 组件会回退到使用 Intent.ACTION_OPEN_DOCUMENT。

Camera 插件不需要权限，除非使用 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 权限的更多信息。

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

变量

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

androidxExifInterfaceVersion：androidx.exifinterface:exifinterface 的版本（默认值：1.4.1）
androidxMaterialVersion：com.google.android.material:material 的版本（默认值：1.13.0）

PWA 说明

在 Web 上，takePhoto 可以使用 PWA Elements 的 pwa-camera-modal 自定义元素提供类似原生的相机 UI。如果该元素未注册，插件会回退到使用 <input type="file"> 选择器。chooseFromGallery 在 Web 上始终使用 <input type="file">，无论是否安装了 PWA Elements。

以编程方式安装 PWA Elements

有关完整说明，请参阅 PWA Elements 安装指南。

提供自定义相机元素

您也可以注册自己的 pwa-camera-modal 自定义元素，而不是使用 @ionic/pwa-elements。插件通过以下接口与其交互：

成员	类型	描述
`facingMode`	`string` 属性	在呈现前设置为 `'user'`（前置摄像头）或 `'environment'`（后置摄像头）
`componentOnReady()`	方法 → `Promise<void>`	插件在创建元素后调用；当元素准备就绪时 resolve
`present()`	方法	由插件调用以显示相机 UI
`dismiss()`	方法	由插件调用以在拍照或取消后关闭相机 UI
`onPhoto`	事件	当用户拍照或取消时触发。`event.detail` 必须是 `Blob`（已拍照）、`null`（用户取消）或 `Error`（出现错误）

class MyCameraModal extends HTMLElement {
  facingMode = 'environment';

  componentOnReady() {
    return Promise.resolve();
  }

  present() {
    // 显示您的自定义相机 UI，完成后仅触发一个 'onPhoto' 事件：
    //   - Blob：用户拍了一张照片
    //   - null：用户取消了
    //   - Error：出现了错误
    // 示例：
    this.dispatchEvent(new CustomEvent('onPhoto', { detail: photoBlob }));
  }

  dismiss() {
    // 隐藏您的自定义相机 UI（插件在收到 'onPhoto' 后调用）
  }
}

customElements.define('pwa-camera-modal', MyCameraModal);

示例

拍照

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

const takePicture = async () => {
  try {
    const result = await Camera.takePhoto({
      quality: 90,
      includeMetadata: true,
    });

    // result.webPath 可以直接设置为图片元素的 src
    imageElement.src = result.webPath;

    // 在原生平台：传递 result.uri 给 Filesystem API 以获取全分辨率 base64 数据，
    // 或使用 result.thumbnail 获取较低分辨率的 base64 预览。
    // 在 Web 上：result.thumbnail 包含全图 base64 编码数据。

    console.log('格式:', result.metadata?.format);
    console.log('分辨率:', result.metadata?.resolution);
  } catch (e) {
    const error = e as any;
    // error.code 包含结构化的错误代码（例如 'OS-PLUG-CAMR-0003'）
    // 当由原生层抛出时。有关所有代码，请参阅 Errors 部分。
    const message = error.code ? `[${error.code}] ${error.message}` : error.message;
    console.error('takePhoto 失败:', message);
  }
};

从相册选择

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

const pickMedia = async () => {
  try {
    const { results } = await Camera.chooseFromGallery({
      mediaType: MediaTypeSelection.All, // 照片、视频或两者
      allowMultipleSelection: true,
      limit: 5,
      includeMetadata: true,
    });

    for (const item of results) {
      console.log('类型:', item.type);       // MediaType.Photo 或 MediaType.Video
      console.log('webPath:', item.webPath);
      console.log('格式:', item.metadata?.format);
      console.log('大小:', item.metadata?.size);
    }
  } catch (e) {
    const error = e as any;
    const message = error.code ? `[${error.code}] ${error.message}` : error.message;
    console.error('chooseFromGallery 失败:', message);
  }
};

录制和播放视频

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

const recordAndPlay = async () => {
  let videoUri: string | undefined;

  try {
    const result = await Camera.recordVideo({
      saveToGallery: false,
      isPersistent: true, // 使文件在应用启动之间保持可用
      includeMetadata: true,
    });

    videoUri = result.uri;
    console.log('时长:', result.metadata?.duration);
    console.log('已保存到相册:', result.saved);
  } catch (e) {
    const error = e as any;
    const message = error.code ? `[${error.code}] ${error.message}` : error.message;
    console.error('recordVideo 失败:', message);
    return;
  }

  if (videoUri) {
    try {
      await Camera.playVideo({ uri: videoUri });
    } catch (e) {
      const error = e as any;
      const message = error.code ? `[${error.code}] ${error.message}` : error.message;
      console.error('playVideo 失败:', message);
    }
  }
};

从 base64 字符串编辑照片

editPhoto 从 base64 编码的图像打开一个应用内编辑器，并将编辑后的图像作为 base64 字符串在 outputImage 中返回。

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

const editFromBase64 = async (base64Image: string) => {
  try {
    const { outputImage } = await Camera.editPhoto({
      inputImage: base64Image, // 原始 base64，不含 data URL 前缀
    });

    // outputImage 是编辑后的图像，base64 编码
    imageElement.src = `data:image/jpeg;base64,${outputImage}`;
  } catch (e) {
    const error = e as any;
    const message = error.code ? `[${error.code}] ${error.message}` : error.message;
    console.error('editPhoto 失败:', message);
  }
};

从 URI 编辑照片

editURIPhoto 从文件 URI（例如来自 takePhoto 或 Filesystem API）打开一个应用内编辑器，并返回一个 MediaResult。

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

const editFromURI = async (uri: string) => {
  try {
    const result = await Camera.editURIPhoto({
      uri,
      saveToGallery: false,
      includeMetadata: true,
    });

    // result.webPath 可以直接用作图片的 src
    imageElement.src = result.webPath;

    console.log('格式:', result.metadata?.format);
    console.log('大小:', result.metadata?.size);
    console.log('已保存到相册:', result.saved);
  } catch (e) {
    const error = e as any;
    const message = error.code ? `[${error.code}] ${error.message}` : error.message;
    console.error('editURIPhoto 失败:', message);
  }
};

迁移到新 API

版本 8.1.0 引入了新的改进 API，并弃用了 getPhoto 和 pickImages。

替换 `getPhoto`

getPhoto 通过 CameraSource 处理三种来源：Camera、Photos 和 Prompt。Camera 和 Photos 现在映射到不同的方法，而 Prompt 已被移除。

`CameraSource.Camera` 替换为 `takePhoto`

新 API 不再支持 CameraResultType.Base64 和 CameraResultType.DataUrl。请参阅结果类型变更了解替代方案。

// 之前
const photo = await Camera.getPhoto({
  source: CameraSource.Camera,
  quality: 90,
  allowEditing: true,
  resultType: CameraResultType.Uri,
  direction: CameraDirection.Rear,
  width: 1280,
  height: 720,
});
const imageUrl = photo.webPath;

// 之后
const result = await Camera.takePhoto({
  quality: 90,
  editable: 'in-app',        // 替换 allowEditing: true
  cameraDirection: CameraDirection.Rear, // 替换 direction
  targetWidth: 1280,         // 替换 width (1)
  targetHeight: 720,         // 替换 height (1)
});
const imageUrl = result.webPath;

(1) width/height 各自独立工作，设置最大尺寸的同时保持宽高比。targetWidth/targetHeight 必须一起使用——仅设置其中一个无效。

`CameraSource.Photos` 替换为 `chooseFromGallery`

// 之前
const photo = await Camera.getPhoto({
  source: CameraSource.Photos,
  quality: 90,
  resultType: CameraResultType.Uri,
});
const imageUrl = photo.webPath;

// 之后
const { results } = await Camera.chooseFromGallery({
  quality: 90,
});
const imageUrl = results[0].webPath;

`CameraSource.Prompt`（或默认值）

getPhoto 之前会显示一个原生提示，让用户选择相机或相册。此提示不再是插件的一部分。您应该使用自己的 UI（例如使用 @capacitor/action-sheet）构建提示，然后根据用户选择调用 takePhoto 或 chooseFromGallery。

// 之前
const photo = await Camera.getPhoto({
  // source 默认为 CameraSource.Prompt
  quality: 90,
  resultType: CameraResultType.Uri,
});

// 之后：显示您自己的 UI 来确定来源，然后调用相应的方法
const result = await Camera.takePhoto({ quality: 90 });
// 或
const { results } = await Camera.chooseFromGallery({ quality: 90 });

结果类型变更

getPhoto 返回一个 Photo 对象，其可用字段取决于 resultType。新 API 完全移除了 resultType——MediaResult 具有固定的字段集，无论照片是如何拍摄的。

`Photo` 字段	`MediaResult` 对应项
`path`	`uri`
`webPath`	`webPath`
`base64String`	`thumbnail`（在 Web 上，包含全图 base64 编码；在原生平台，包含缩略图）
`dataUrl`	无直接对应项——请参阅下面的说明
`saved`	`saved`
`format`	`metadata.format`（需要 `includeMetadata: true`）
`exif`	`metadata.exif`（需要 `includeMetadata: true`）

构建 data URL——根据您的需求有两种选择：

在所有平台上，您可以组合使用 thumbnail 和 metadata.format（需要 includeMetadata: true）。在原生平台，thumbnail 是较低分辨率的：

const dataUrl = `data:image/${result.metadata.format};base64,${result.thumbnail}`;

在原生平台，如果您需要全分辨率 base64 数据，请通过 Filesystem API 读取 uri，然后从中构建 data URL：

import { Filesystem } from '@capacitor/filesystem';

const { data } = await Filesystem.readFile({ path: result.uri });
const dataUrl = `data:image/${result.metadata.format};base64,${data}`;

替换 `pickImages` → `chooseFromGallery`

pickImages 允许从相册中选择多张照片。在 chooseFromGallery 中传递 allowMultipleSelection: true 以获得相同的行为。

// 之前
const { photos } = await Camera.pickImages({
  quality: 90,
  limit: 5,
  width: 1280,
  height: 720,
});
for (const photo of photos) {
  console.log(photo.webPath);
}

// 之后
const { results } = await Camera.chooseFromGallery({
  allowMultipleSelection: true,
  quality: 90,
  limit: 5,
  targetWidth: 1280,  // 替换 width (1)
  targetHeight: 720,  // 替换 height (1)
});
for (const result of results) {
  console.log(result.webPath);
}

(1) width/height 各自独立工作，设置最大尺寸的同时保持宽高比。targetWidth/targetHeight 必须一起使用——仅设置其中一个无效。

chooseFromGallery 还可以通过设置 mediaType 为 MediaTypeSelection.Video 或 MediaTypeSelection.All 来选择视频或混合媒体。

选项重命名摘要

旧选项	新选项	适用范围
`width`	`targetWidth` (1)	`takePhoto`, `chooseFromGallery`
`height`	`targetHeight` (1)	`takePhoto`, `chooseFromGallery`
`direction`	`cameraDirection`	`takePhoto`
`allowEditing`	`editable: 'in-app'`	`takePhoto`, `chooseFromGallery`
`resultType`	—（已移除，请参阅结果类型变更）	—
`source`	—（已移除，请使用单独的方法）	—
`promptLabel*`	—（已移除，请构建自己的 UI）	—

(1) width/height 各自独立工作，设置最大尺寸的同时保持宽高比。targetWidth/targetHeight 必须一起使用——仅设置其中一个无效。

有关现有错误代码的列表，请参阅错误。

takePhoto(...)

takePhoto(options: TakePhotoOptions) => Promise<MediaResult>

打开设备相机，允许用户拍照。

参数	类型
`options`	`TakePhotoOptions`

返回:

Promise<MediaResult>

Since: 8.1.0

recordVideo(...)

recordVideo(options: RecordVideoOptions) => Promise<MediaResult>

打开设备相机，允许用户录制视频。在 Web 上不可用。

参数	类型
`options`	`RecordVideoOptions`

返回:

Promise<MediaResult>

Since: 8.1.0

playVideo(...)

playVideo(options: PlayVideoOptions) => Promise<void>

打开原生视频播放器。在 Web 上不可用。

参数	类型
`options`	`PlayVideoOptions`

Since: 8.1.0

chooseFromGallery(...)

chooseFromGallery(options: ChooseFromGalleryOptions) => Promise<MediaResults>

允许用户直接从他们的相册中选择图片、视频或两者。

参数	类型
`options`	`ChooseFromGalleryOptions`

返回:

Promise<MediaResults>

Since: 8.1.0

editPhoto(...)

editPhoto(options: EditPhotoOptions) => Promise<EditPhotoResult>

打开一个应用内编辑界面，使用提供的 base64 字符串编辑给定照片。在 Web 上不可用。

参数	类型
`options`	`EditPhotoOptions`

返回:

Promise<EditPhotoResult>

Since: 8.1.0

editURIPhoto(...)

editURIPhoto(options: EditURIPhotoOptions) => Promise<MediaResult>

打开一个应用内编辑界面，使用提供的 URI 编辑照片。在 Web 上不可用。

参数	类型
`options`	`EditURIPhotoOptions`

返回:

Promise<MediaResult>

Since: 8.1.0

pickLimitedLibraryPhotos()

pickLimitedLibraryPhotos() => Promise<GalleryPhotos>

允许用户更新其受限的照片库选择。在选取器关闭后返回所有受限照片。如果用户授予了照片的完整访问权限，则返回空数组。

返回:

Promise<GalleryPhotos>

Since: 4.1.0

getLimitedLibraryPhotos()

getLimitedLibraryPhotos() => Promise<GalleryPhotos>

返回从受限照片库中选择的照片数组。

返回:

Promise<GalleryPhotos>

Since: 4.1.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

检查相机和相册权限。

返回:

Promise<PermissionStatus>

Since: 1.0.0

requestPermissions(...)

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

请求相机和相册权限。

参数	类型
`permissions`	`CameraPluginPermissions`

返回:

Promise<PermissionStatus>

Since: 1.0.0

getPhoto(...)

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

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

参数	类型
`options`	`ImageOptions`

返回:

Promise<Photo>

Since: 1.0.0

pickImages(...)

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

允许用户从相册中选择多张图片。

参数	类型
`options`	`GalleryImageOptions`

返回:

Promise<GalleryPhotos>

Since: 1.2.0

接口

MediaResult

属性	类型	描述	Since
`type`	`MediaType`	媒体结果的类型。可以是 `Photo` 或 `Video`。	8.1.0
`uri`	`string`	指向媒体文件的 URI。在 Web 上不可用。请在 Web 上改用 `webPath`。	8.1.0
`thumbnail`	`string`	返回媒体的缩略图，base64 编码。在 Web 上，对于 `MediaType.Photo`，完整图像会以 base64 编码返回。在 Web 上，对于 `MediaType.Video`，会返回从视频中捕获的全分辨率 JPEG 帧，以 80% 质量进行 base64 编码。	8.1.0
`saved`	`boolean`	媒体是否成功保存到相册。仅在输入选项中 `saveToGallery` 设置为 `true` 时适用。否则，`save` 始终返回 `false`。在 Web 上不可用。	8.1.0
`webPath`	`string`	webPath 返回一个可用于设置媒体项 src 属性的路径，以实现高效的加载和渲染。	8.1.0
`metadata`	`MediaMetadata`	与媒体结果关联的元数据。仅在输入选项中 `includeMetadata` 设置为 `true` 时包含。	8.1.0

MediaMetadata

属性	类型	描述	Since
`size`	`number`	媒体文件大小，以字节为单位。	8.1.0
`duration`	`number`	仅适用于 `MediaType.Video`——媒体的时长，以秒为单位。	8.1.0
`format`	`string`	图像的格式，例如：jpeg, png, mp4。Android 和 iOS 可能返回 'jpg' 而不是 'jpeg'。格式是相同的，只是名称不同。在检查返回的媒体格式是否为 JPEG 时，请同时对比 'jpeg' 和 'jpg'。Web 支持 jpeg、png 和 gif，但具体可用性可能因浏览器而异。gif 仅在 Web 的 `chooseFromGallery` 中支持。	8.1.0
`resolution`	`string`	媒体的分辨率，格式为 `<width>x<height>`。例如：'1920x1080'。	8.1.0
`creationDate`	`string`	媒体创建的日期和时间，采用 ISO 8601 格式。如果创建日期不可用（例如 Android 7 及以下版本），则返回最后修改日期。对于 Web，始终返回最后修改日期。	8.1.0
`exif`	`string`	从媒体项中检索到的 Exif 数据（如果有）。仅适用于 `MediaType.Photo`。在 Web 上不可用。	8.1.0

TakePhotoOptions

属性	类型	描述	默认值	Since
`quality`	`number`	返回图像的质量，范围 0-100。仅适用于 `EncodingType.JPEG`。注意：此选项仅在 Android 和 iOS 上支持。	`100`	8.1.0
`targetWidth`	`number`	要应用的照片目标宽度。必须为正数，并与 `targetHeight` 一起使用。注意：此选项仅在 Android 和 iOS 上支持。		8.1.0
`targetHeight`	`number`	要应用的照片目标高度。必须为正数，并与 `targetWidth` 一起使用。注意：此选项仅在 Android 和 iOS 上支持。		8.1.0
`correctOrientation`	`boolean`	是否自动旋转图像"向上"以校正竖屏模式下的方向。注意：此选项仅在 Android 和 iOS 上支持。	`true`	8.1.0
`encodingType`	`EncodingType`	拍摄照片的编码类型——JPEG 或 PNG。注意：此选项仅在 Android 和 iOS 上支持。	`EncodingType.JPEG`	8.1.0
`saveToGallery`	`boolean`	是否将照片保存到相册。注意：此选项仅在 Android 和 iOS 上支持。	`false`	8.1.0
`cameraDirection`	`CameraDirection`	仅 iOS 和 Web：相机方向。	`CameraDirection.Rear`	8.1.0
`editable`	`'in-app' \| 'external' \| 'no'`	确定用户是否可以以及如何编辑照片。- 'in-app'：使用应用内编辑器进行照片编辑。- 'external'：打开单独的（平台特定的）原生应用来处理照片编辑，如果没有可用的原生应用，则回退到应用内编辑器。注意：iOS 不支持外部编辑，将使用 'in-app'。- 'no'：不允许编辑。在 Web 上不可用。	`'no'`	8.1.0
`presentationStyle`	`'fullscreen' \| 'popover'`	仅 iOS：相机的呈现样式。	`'fullscreen'`	8.1.0
`webUseInput`	`boolean`	仅 Web：是否使用 PWA Element 体验或文件输入。默认情况下，如果安装了 PWA Elements 则使用，否则回退到文件输入。要始终使用文件输入，请将其设置为 `true`。了解更多关于 PWA Elements：https://capacitorjs.com/docs/web/pwa-elements		8.1.0
`includeMetadata`	`boolean`	MediaResult 是否应包含其元数据。如果在获取元数据时发生错误，将返回空值。	`false`	8.1.0

RecordVideoOptions

属性	类型	描述	默认值	Since
`saveToGallery`	`boolean`	是否将视频保存到相册。	`false`	8.1.0
`includeMetadata`	`boolean`	MediaResult 是否应包含其元数据。如果在获取元数据时发生错误，将返回空值。	`false`	8.1.0
`isPersistent`	`boolean`	是否将视频存储在持久化应用存储中或临时缓存中。如果您计划在应用启动之间使用返回的 `MediaResult#URI`，您可能希望将其设置为 true。否则，可以设置为 false。	`true`	8.1.0

PlayVideoOptions

属性	类型	描述	Since
`uri`	`string`	要播放的视频的 URI。您可以直接使用 `recordVideo` 或 `chooseFromGallery` 返回的 `MediaResult#URI`。	8.1.0

MediaResults

属性	类型	描述	Since
`results`	`MediaResult[]`	媒体结果列表。	8.1.0

ChooseFromGalleryOptions

属性	类型	描述	默认值	Since
`mediaType`	`MediaTypeSelection`	要选择的媒体类型。可以是图片、视频或两者。	`MediaTypeSelection.Photo`	8.1.0
`allowMultipleSelection`	`boolean`	是否允许从相册中选择多个媒体文件。	`false`	8.1.0
`limit`	`number`	用户可以选择的最大媒体文件数量。仅在 `allowMultipleSelection` 为 `true` 时适用。任何非正数将被视为无限制。注意：此选项仅在 Android 13+ 和 iOS 上支持。	`0`	8.1.0
`includeMetadata`	`boolean`	MediaResult 是否应包含其元数据。如果在获取元数据时发生错误，将返回空值。	`false`	8.1.0
`editable`	`'in-app' \| 'external' \| 'no'`	确定用户是否可以以及如何编辑照片。- 'in-app'：使用应用内编辑器进行照片编辑。- 'external'：打开单独的（平台特定的）原生应用来处理照片编辑，如果没有可用的原生应用，则回退到应用内编辑器。注意：iOS 不支持外部编辑，将使用 'in-app'。- 'no'：不允许编辑。仅适用于 `MediaTypeSelection.Photo` 且 `allowMultipleSelection` 设置为 `false`。在 Web 上不可用。	`'no'`	8.1.0
`presentationStyle`	`'fullscreen' \| 'popover'`	仅 iOS：媒体选择器的呈现样式。	`'fullscreen'`	8.1.0
`quality`	`number`	返回图像的质量，范围 0-100。仅适用于 `MediaType.Photo` 和 JPEG 格式。注意：此选项仅在 Android 和 iOS 上支持。	`100`	8.1.0
`targetWidth`	`number`	要应用的照片目标宽度。必须为正数，并与 `targetHeight` 一起使用。选择视频时不适用。注意：此选项仅在 Android 和 iOS 上支持。		1.0.0
`targetHeight`	`number`	要应用的照片目标高度。必须为正数，并与 `targetWidth` 一起使用。选择视频时不适用。注意：此选项仅在 Android 和 iOS 上支持。		8.1.0
`correctOrientation`	`boolean`	是否自动旋转图像"向上"以校正竖屏模式下的方向。选择视频时不适用。注意：此选项仅在 Android 和 iOS 上支持。	`true`	8.1.0
`webUseInput`	`boolean`	仅 Web：是否使用 PWA Element 体验或文件输入。默认情况下，如果安装了 PWA Elements 则使用，否则回退到文件输入。要始终使用文件输入，请将其设置为 `true`。了解更多关于 PWA Elements：https://capacitorjs.com/docs/web/pwa-elements		8.1.0

EditPhotoResult

属性	类型	描述	Since
`outputImage`	`string`	编辑后的图像，base64 编码。	8.1.0

EditPhotoOptions

属性	类型	描述	Since
`inputImage`	`string`	要编辑的 base64 编码图像。	8.1.0

EditURIPhotoOptions

属性	类型	描述	默认值	Since
`uri`	`string`	包含要编辑的照片的 URI。		8.1.0
`saveToGallery`	`boolean`	是否将编辑后的照片保存到相册。	`false`	8.1.0
`includeMetadata`	`boolean`	MediaResult 是否应包含其元数据。如果在获取元数据时发生错误，将返回空值。	`false`	8.1.0

GalleryPhotos

属性	类型	描述	Since
`photos`	`GalleryPhoto[]`	所有已选择照片的数组。	1.2.0

GalleryPhoto

属性	类型	描述	Since
`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

PermissionStatus

属性	类型
`camera`	`CameraPermissionState`
`photos`	`CameraPermissionState`

CameraPluginPermissions

属性	类型
`permissions`	`CameraPermissionType[]`

Photo

属性	类型	描述	Since
`base64String`	`string`	图像的 base64 编码字符串表示，如果使用了 CameraResultType.Base64。	1.0.0
`dataUrl`	`string`	以 'data:image/jpeg;base64,' 开头的 URL 加上图像的 base64 编码字符串表示，如果使用了 CameraResultType.DataUrl。注意：在 Web 上，文件格式可能因浏览器而异。	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，但具体可用性可能因浏览器而异。gif 仅在 `webUseInput` 设置为 `true` 或 `source` 设置为 `Photos` 时支持。	1.0.0
`saved`	`boolean`	图像是否已保存到相册。在 Android 和 iOS 上，如果用户未授予所需权限，保存到相册可能会失败。在 Web 上没有相册，因此始终返回 false。	1.1.0

ImageOptions

属性	类型	描述	默认值	Since
`quality`	`number`	以 JPEG 格式返回图像的质量，范围 0-100。注意：此选项仅在 Android 和 iOS 上支持。		1.0.0
`allowEditing`	`boolean`	是否允许用户裁剪或进行小幅编辑（平台特定）。注意：此选项仅在 Android 和 iOS 上支持。在 iOS 上仅支持 CameraSource.Camera，但不支持 CameraSource.Photos。		1.0.0
`resultType`	`CameraResultType`	数据的返回方式。目前仅支持 'Base64'、'DataUrl' 或 'Uri'。		1.0.0
`saveToGallery`	`boolean`	是否将照片保存到相册。如果是从相册选择的照片，则仅在编辑后保存。注意：此选项仅在 Android 和 iOS 上支持。	`false`	1.0.0
`width`	`number`	保存图像所需的最大宽度。保持宽高比。注意：此选项仅在 Android 和 iOS 上支持。		1.0.0
`height`	`number`	保存图像所需的最大高度。保持宽高比。注意：此选项仅在 Android 和 iOS 上支持。		1.0.0
`correctOrientation`	`boolean`	是否自动旋转图像"向上"以校正竖屏模式下的方向。注意：此选项仅在 Android 和 iOS 上支持。	`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`。了解更多关于 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

GalleryImageOptions

属性	类型	描述	默认值	Since
`quality`	`number`	以 JPEG 格式返回图像的质量，范围 0-100。注意：此选项仅在 Android 和 iOS 上支持。		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`	用户可以选择的最大图片数量。注意：此选项仅在 Android 13+ 和 iOS 上支持。	`0 (无限制)`	1.2.0

类型别名

CameraPermissionState

PermissionState | 'limited'

PermissionState

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

CameraPermissionType

'camera' | 'photos'

枚举

MediaType

成员	值
`Photo`	`0`
`Video`	`1`

EncodingType

成员	值
`JPEG`	`0`
`PNG`	`1`

CameraDirection

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

MediaTypeSelection

成员	值
`Photo`	`0`
`Video`	`1`
`All`	`2`

CameraResultType

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

CameraSource

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

错误

该插件在 Android 和 iOS 上返回结构化错误。每个错误都有一个 code（例如 OS-PLUG-CAMR-0003）和一个带有可读描述信息的 message。请注意，这些仅适用于从版本 8.1.0 开始引入的新 API 的原生平台：takePhoto、chooseFromGallery、editPhoto、editURIPhoto、recordVideo 和 playVideo。

错误代码	平台	描述
OS-PLUG-CAMR-0003	Android, iOS	无法访问相机。请检查您的相机权限并重试。
OS-PLUG-CAMR-0005	Android, iOS	无法访问您的相册，因为未提供访问权限。
OS-PLUG-CAMR-0006	Android, iOS	无法拍照，因为进程被取消。
OS-PLUG-CAMR-0007	Android, iOS	没有可用的相机。
OS-PLUG-CAMR-0008	iOS	所选文件包含无效数据。
OS-PLUG-CAMR-0009	Android, iOS	无法编辑图像。
OS-PLUG-CAMR-0010	Android, iOS	无法拍照。
OS-PLUG-CAMR-0011	iOS	无法从相册获取图像。
OS-PLUG-CAMR-0012	Android, iOS	无法处理图像。
OS-PLUG-CAMR-0013	Android, iOS	无法编辑照片，因为进程被取消。
OS-PLUG-CAMR-0014	iOS	无法解码'拍照'操作参数。
OS-PLUG-CAMR-0016	Android, iOS	无法录制视频。
OS-PLUG-CAMR-0017	Android, iOS	无法录制视频，因为进程被取消。
OS-PLUG-CAMR-0018	Android, iOS	无法从相册选择媒体。
OS-PLUG-CAMR-0019	iOS	无法编码媒体结果。
OS-PLUG-CAMR-0020	Android, iOS	无法从相册选择媒体，因为进程被取消。
OS-PLUG-CAMR-0021	Android	无法获取媒体文件路径。
OS-PLUG-CAMR-0023	Android, iOS	无法播放视频。
OS-PLUG-CAMR-0024	Android	URI 参数不能为空。
OS-PLUG-CAMR-0025	iOS	无法从相册获取视频。
OS-PLUG-CAMR-0026	iOS	插件存在问题。
OS-PLUG-CAMR-0027	Android, iOS	所选文件不存在。
OS-PLUG-CAMR-0028	Android, iOS	无法从 URI 检索图像。
OS-PLUG-CAMR-0031	Android	向插件方法提供了无效参数。
OS-PLUG-CAMR-0033	Android	无法获取上下文。

安装​

iOS​

Android​

变量​

PWA 说明​

以编程方式安装 PWA Elements​

提供自定义相机元素​

示例​

拍照​

从相册选择​

录制和播放视频​

从 base64 字符串编辑照片​

从 URI 编辑照片​

迁移到新 API​

替换 getPhoto​

CameraSource.Camera 替换为 takePhoto​

CameraSource.Photos 替换为 chooseFromGallery​

CameraSource.Prompt（或默认值）​

结果类型变更​

替换 pickImages → chooseFromGallery​

选项重命名摘要​

API​

takePhoto(...)​

recordVideo(...)​

playVideo(...)​

chooseFromGallery(...)​

editPhoto(...)​

editURIPhoto(...)​

pickLimitedLibraryPhotos()​

getLimitedLibraryPhotos()​

checkPermissions()​

requestPermissions(...)​

getPhoto(...)​

pickImages(...)​

接口​

MediaResult​

MediaMetadata​

TakePhotoOptions​

RecordVideoOptions​

PlayVideoOptions​

MediaResults​

ChooseFromGalleryOptions​

EditPhotoResult​

EditPhotoOptions​

EditURIPhotoOptions​

GalleryPhotos​

GalleryPhoto​

PermissionStatus​

CameraPluginPermissions​

Photo​

ImageOptions​

GalleryImageOptions​

类型别名​

CameraPermissionState​

PermissionState​

CameraPermissionType​

枚举​

MediaType​

EncodingType​

CameraDirection​

MediaTypeSelection​

CameraResultType​

CameraSource​

错误​

Contents

安装

iOS

Android

变量

PWA 说明

以编程方式安装 PWA Elements

提供自定义相机元素

示例

拍照

从相册选择

录制和播放视频

从 base64 字符串编辑照片

从 URI 编辑照片

迁移到新 API

替换 `getPhoto`

`CameraSource.Camera` 替换为 `takePhoto`

`CameraSource.Photos` 替换为 `chooseFromGallery`

`CameraSource.Prompt`（或默认值）

结果类型变更

替换 `pickImages` → `chooseFromGallery`

选项重命名摘要

API

takePhoto(...)

recordVideo(...)

playVideo(...)

chooseFromGallery(...)

editPhoto(...)

editURIPhoto(...)

pickLimitedLibraryPhotos()

getLimitedLibraryPhotos()

checkPermissions()

requestPermissions(...)

getPhoto(...)

pickImages(...)

接口

MediaResult

MediaMetadata

TakePhotoOptions

RecordVideoOptions

PlayVideoOptions

MediaResults

ChooseFromGalleryOptions

EditPhotoResult

EditPhotoOptions

EditURIPhotoOptions

GalleryPhotos

GalleryPhoto

PermissionStatus

CameraPluginPermissions

Photo

ImageOptions

GalleryImageOptions

类型别名

CameraPermissionState

PermissionState

CameraPermissionType

枚举

MediaType

EncodingType

CameraDirection

MediaTypeSelection

CameraResultType

CameraSource

错误