跳至主要內容
版本：v8

@capacitor/camera

相機 API 提供使用相機拍照或從相簿中選擇現有照片的功能。

安裝​

npm install @capacitor/camera
npx cap sync

iOS​

iOS 需要在您的應用程式的 Info.plist 中新增並填寫以下使用說明

  • NSCameraUsageDescription (隱私權 - 相機使用說明)
  • NSPhotoLibraryAddUsageDescription (隱私權 - 照片圖庫新增使用說明)
  • NSPhotoLibraryUsageDescription (隱私權 - 照片圖庫使用說明)

請參閱 在 Info.plist 中設定，以及 iOS 指南，以獲取更多關於在 Xcode 中設定 iOS 權限的資訊。

Android​

從裝置圖庫選擇現有圖片時，現在使用 Android 照片選擇器元件。照片選擇器適用於符合以下條件的裝置

  • 執行 Android 11 (API 等級 30) 或更高版本
  • 透過 Google 系統更新接收模組化系統元件的變更

執行 Android 11 或 12 且支援 Google Play 服務的舊裝置和 Android Go 裝置可以安裝回溯移植版本的照片選擇器。若要透過 Google Play 服務啟用回溯移植照片選擇器模組的自動安裝，請將以下項目新增至您的 AndroidManifest.xml 檔案中的 <application> 標籤



<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 will contain a path that can be set as an image src.
  // You can access the original file using image.path, which can be
  // passed to the Filesystem API to read the raw data of the image,
  // if desired (or pass resultType: CameraResultType.Base64 to getPhoto)
  var imageUrl = image.webPath;

  // Can be set to the src of an image now
  imageElement.src = imageUrl;
};

API​

getPhoto(...)​

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

提示使用者從相簿中選擇照片，或使用相機拍攝新照片。

參數類型
選項ImageOptions

傳回： Promise<Photo>

從 1.0.0

pickImages(...)​

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

允許使用者從照片圖庫中選擇多張圖片。在 iOS 13 及更舊版本中，僅允許選擇一張圖片。

參數類型
選項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>

請求相機和相簿權限

參數類型
權限CameraPluginPermissions

傳回： Promise<PermissionStatus>

從 1.0.0

介面​

Photo​

屬性類型說明從
base64String字串如果使用 CameraResultType.Base64，則為影像的 base64 編碼字串表示法。1.0.0
dataUrl字串以 'data:image/jpeg;base64,' 開頭的網址，以及如果使用 CameraResultType.DataUrl，則為影像的 base64 編碼字串表示法。注意：在網頁上，檔案格式可能會根據瀏覽器而變更。1.0.0
path字串如果使用 CameraResultType.Uri，則路徑將包含完整的平台特定檔案 URL，稍後可以使用檔案系統 API 讀取該 URL。1.0.0
webPath字串webPath 會傳回可用於設定影像 src 屬性的路徑，以便有效率地載入和呈現。1.0.0
exif任何從影像擷取的 Exif 資料（如果有的話）1.0.0
format字串影像的格式，例如：jpeg、png、gif。iOS 和 Android 僅支援 jpeg。網頁支援 jpeg、png 和 gif，但確切的可用性可能因瀏覽器而異。僅當 webUseInput 設定為 true 或 source 設定為 Photos 時才支援 gif。1.0.0
saved布林值影像是否已儲存到圖庫。在 Android 和 iOS 上，如果使用者未授予必要的權限，則儲存到圖庫可能會失敗。在網頁上沒有圖庫，因此永遠傳回 false。1.1.0

ImageOptions​

屬性類型說明預設值從
品質數字以 JPEG 傳回的影像品質，範圍從 0 到 100。注意：此選項僅在 Android 和 iOS 上支援1.0.0
allowEditing布林值是否允許使用者裁剪或進行小編輯（平台特定）。在 iOS 14+ 上，僅支援 CameraSource.Camera，但不支援 CameraSource.Photos。1.0.0
resultTypeCameraResultType應如何傳回資料。目前僅支援 'Base64'、'DataUrl' 或 'Uri'1.0.0
saveToGallery布林值是否將照片儲存到圖庫。如果照片是從圖庫中選取的，則只會在編輯時儲存。: false1.0.0
width數字儲存影像的所需最大寬度。長寬比會保留。1.0.0
height數字儲存影像的所需最大高度。長寬比會保留。1.0.0
correctOrientation布林值是否自動將影像旋轉「向上」以校正在直向模式下的方向: true1.0.0
sourceCameraSource從中取得照片的來源。預設情況下，這會提示使用者選取相簿或拍攝照片。: CameraSource.Prompt1.0.0
directionCameraDirection僅限 iOS 和網頁：相機方向。: CameraDirection.Rear1.0.0
presentationStyle'全螢幕' | '彈出式視窗'僅限 iOS：相機的呈現樣式。：'全螢幕'1.0.0
webUseInput布林值僅限網頁：是否使用 PWA 元素體驗或檔案輸入。預設值為如果已安裝 PWA 元素則使用，否則回退至檔案輸入。若要永遠使用檔案輸入，請將此設定為 true。深入瞭解 PWA 元素：https://capacitorjs.com/docs/web/pwa-elements1.0.0
promptLabelHeader字串顯示提示時要使用的文字值。：'照片'1.0.0
promptLabelCancel字串顯示提示時要使用的文字值。僅限 iOS：'取消' 按鈕的標籤。：'取消'1.0.0
promptLabelPhoto字串顯示提示時要使用的文字值。用於選擇已儲存影像的按鈕標籤。：'從照片'1.0.0
promptLabelPicture字串顯示提示時要使用的文字值。用於開啟相機的按鈕標籤。：'拍照'1.0.0

GalleryPhotos​

屬性類型說明從
photosGalleryPhoto[]所有已選取照片的陣列。1.2.0

GalleryPhoto​

屬性類型說明從
path字串完整的、平台特定的檔案 URL，稍後可以使用 Filesystem API 讀取。1.2.0
webPath字串webPath 會傳回可用於設定影像 src 屬性的路徑，以便有效率地載入和呈現。1.2.0
exif任何從影像擷取的 Exif 資料（如果有的話）1.2.0
format字串影像的格式，例如：jpeg、png、gif。僅限 iOS 和 Android 支援 jpeg。網頁支援 jpeg、png 和 gif。1.2.0

GalleryImageOptions​

屬性類型說明預設值從
品質數字要以 JPEG 格式回傳的影像品質，從 0-100。注意：此選項僅在 Android 和 iOS 上支援。1.2.0
width數字儲存影像的所需最大寬度。長寬比會保留。1.2.0
height數字儲存影像的所需最大高度。長寬比會保留。1.2.0
correctOrientation布林值是否自動將影像旋轉「向上」以校正在直向模式下的方向: true1.2.0
presentationStyle'全螢幕' | '彈出式視窗'僅限 iOS：相機的呈現樣式。：'全螢幕'1.2.0
limit數字使用者可以選擇的最大圖片數量。注意：此選項僅在 Android 13+ 和 iOS 上支援。0（無限制）1.2.0

PermissionStatus​

屬性類型
cameraCameraPermissionState
photosCameraPermissionState

CameraPluginPermissions​

屬性類型
權限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'使用相機拍攝新照片。
Photos'PHOTOS'從圖庫或相簿中選擇現有照片。

CameraDirection​

成員值
Rear'REAR'
Front'FRONT'

目錄

編輯此頁面