cordova-plugin-camera

此插件定義一個全域的 navigator.camera 物件，它提供一個 API 來拍照以及從系統的圖片庫中選擇圖片。

雖然該物件附加到全域範圍的 navigator，但它直到 deviceready 事件之後才可用。

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log(navigator.camera);
}

安裝

cordova plugin add cordova-plugin-camera

也可以直接透過 repo url 安裝 ( 不穩定 )

cordova plugin add https://github.com/apache/cordova-plugin-camera.git

插件變數

該插件使用 ANDROIDX_CORE_VERSION 變數來配置 androidx.core:core 相依性。這樣可以避免與其他具有硬編碼相依性的插件發生衝突。如果沒有傳遞任何值，它將使用 1.6.+ 作為預設值。

該變數在安裝時配置

cordova plugin add cordova-plugin-camera --variable ANDROIDX_CORE_VERSION=1.8.0

如何貢獻

歡迎貢獻者！我們需要您的貢獻來保持專案向前發展。您可以[回報錯誤、改善文件，或 貢獻程式碼。

我們建議採用特定的 貢獻者工作流程。從那裡開始閱讀。更多資訊請參閱 我們的 wiki。

有解決方案嗎？ 送出 Pull Request。

為了使您的變更被接受，您需要簽署並提交一份 Apache ICLA (個人貢獻者授權協議)。然後您的名字將會出現在由 非提交者 或 Cordova 提交者簽署的 CLA 清單中。

並且別忘了測試並記錄您的程式碼。

iOS 特性

自 iOS 10 起，如果嘗試存取隱私敏感資料，則必須在 info.plist 中提供使用說明。當系統提示使用者允許存取時，此使用說明字串將顯示為權限對話方塊的一部分，但如果您未提供使用說明，則應用程式將在顯示對話方塊之前崩潰。此外，Apple 會拒絕存取私人資料但未提供使用說明的應用程式。

此插件需要以下使用說明

• NSCameraUsageDescription 指定您的應用程式存取裝置相機的原因。
• NSPhotoLibraryUsageDescription 指定您的應用程式存取使用者相片庫的原因。
• NSLocationWhenInUseUsageDescription 指定您的應用程式在您的應用程式使用時存取使用者位置資訊的原因。(如果您將 CameraUsesGeolocation 偏好設定為 true，請設定它)
• NSPhotoLibraryAddUsageDescription 指定您的應用程式取得使用者相片庫唯寫權限的原因

若要將這些項目新增到 info.plist 中，您可以使用 config.xml 中的 edit-config 標籤，如下所示

<edit-config target="NSCameraUsageDescription" file="*-Info.plist" mode="merge">
    <string>need camera access to take pictures</string>
</edit-config>

<edit-config target="NSPhotoLibraryUsageDescription" file="*-Info.plist" mode="merge">
    <string>need photo library access to get pictures from there</string>
</edit-config>

<edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>

<edit-config target="NSPhotoLibraryAddUsageDescription" file="*-Info.plist" mode="merge">
    <string>need photo library access to save pictures there</string>
</edit-config>

API 參考

• 相機
  • .getPicture(successCallback, errorCallback, options)
  • .cleanup()
  • .onError : function
  • .onSuccess : function
  • .CameraOptions : Object
• 相機
  • .DestinationType : enum
  • .EncodingType : enum
  • .MediaType : enum
  • .PictureSourceType : enum
  • .PopoverArrowDirection : enum
  • .Direction : enum
• CameraPopoverHandle
• CameraPopoverOptions

相機

camera.getPicture(successCallback, errorCallback, options)

使用相機拍照，或從裝置的圖片庫中擷取相片。影像以 Base64 編碼的 String 或影像檔案的 URI 傳遞到成功回呼。

camera.getPicture 函式會開啟裝置的預設相機應用程式，該應用程式預設允許使用者拍照 - 當 Camera.sourceType 等於 Camera.PictureSourceType.CAMERA 時，會發生此行為。一旦使用者拍下照片，相機應用程式就會關閉，並還原應用程式。

如果 Camera.sourceType 是 Camera.PictureSourceType.PHOTOLIBRARY 或 Camera.PictureSourceType.SAVEDPHOTOALBUM，則會顯示一個對話方塊，允許使用者選取現有的影像。

傳回值會根據指定的 cameraOptions，以以下其中一種格式傳送到 cameraSuccess 回呼函式

• 一個包含 Base64 編碼相片影像的 String。
• 一個代表本機儲存上影像檔案位置的 String (預設)。

您可以對編碼的影像或 URI 執行任何您想要的操作，例如

• 在 <img> 標籤中呈現影像，如下例所示
• 在本機儲存資料 (LocalStorage、Lawnchair 等)
• 將資料張貼到遠端伺服器

注意：較新裝置上的相片解析度非常好。即使指定了 quality 參數，從裝置圖庫中選取的相片也不會縮小到較低的品質。為避免常見的記憶體問題，請將 Camera.destinationType 設定為 FILE_URI 而不是 DATA_URL。

支援的平台

• Android
• 瀏覽器
• iOS

更多範例 在此。特性 在此。

種類：[camera](#module_camera) 的靜態方法

範例

navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);

camera.cleanup()

移除在呼叫 camera.getPicture 後保留在暫存儲存空間中的中繼影像檔案。僅在 Camera.sourceType 的值等於 Camera.PictureSourceType.CAMERA 且 Camera.destinationType 等於 Camera.DestinationType.FILE_URI 時適用。

支援的平台

• iOS

種類：[camera](#module_camera) 的靜態方法
範例

navigator.camera.cleanup(onSuccess, onFail);

function onSuccess() {
    console.log("Camera cleanup success.")
}

function onFail(message) {
    alert('Failed because: ' + message);
}

camera.onError : function

提供錯誤訊息的回呼函式。

種類：[camera](#module_camera) 的靜態 typedef

camera.onSuccess : function

提供影像資料的回呼函式。

種類：[camera](#module_camera) 的靜態 typedef

範例

// Show image
//
function cameraCallback(imageData) {
   var image = document.getElementById('myImage');
   image.src = "data:image/jpeg;base64," + imageData;
}

camera.CameraOptions : Object

可自訂相機設定的選用參數。

• 特性

種類：[camera](#module_camera) 的靜態 typedef
屬性

相機

Camera.DestinationType : enum

定義 Camera.getPicture 呼叫的輸出格式。

種類：[Camera](#module_Camera) 的靜態列舉屬性
屬性

Camera.EncodingType : enum

種類：[Camera](#module_Camera) 的靜態列舉屬性
屬性

Camera.MediaType : enum

種類：[Camera](#module_Camera) 的靜態列舉屬性
屬性

Camera.PictureSourceType : enum

定義 Camera.getPicture 呼叫的輸出格式。

種類：[Camera](#module_Camera) 的靜態列舉屬性
屬性

Camera.PopoverArrowDirection : enum

符合 iOS UIPopoverArrowDirection 常數，以指定彈出視窗上的箭頭位置。

種類：[Camera](#module_Camera) 的靜態列舉屬性
屬性

Camera.Direction : enum

種類：[Camera](#module_Camera) 的靜態列舉屬性
屬性

CameraPopoverOptions

僅限 iOS 的參數，用於指定從 iPad 的圖庫或相簿中選取影像時，彈出視窗的錨定元素位置和箭頭方向。請注意，彈出視窗的大小可能會變更，以調整箭頭的方向和螢幕的方向。在指定錨定元素位置時，請務必考慮方向變更。

CameraPopoverHandle

圖像選擇器彈出視窗的控制代碼。

支援的平台

• iOS

範例

navigator.camera.getPicture(onSuccess, onFail,
{
    destinationType: Camera.DestinationType.FILE_URI,
    sourceType: Camera.PictureSourceType.PHOTOLIBRARY,
    popoverOptions: new CameraPopoverOptions(300, 300, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY, 300, 600)
});

// Reposition the popover if the orientation changes.
window.onorientationchange = function() {
    var cameraPopoverHandle = new CameraPopoverHandle();
    var cameraPopoverOptions = new CameraPopoverOptions(0, 0, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY, 400, 500);
    cameraPopoverHandle.setPosition(cameraPopoverOptions);
}

camera.getPicture 勘誤

範例

拍攝照片並檢索圖像的檔案位置

navigator.camera.getPicture(onSuccess, onFail, { quality: 50,
    destinationType: Camera.DestinationType.FILE_URI });

function onSuccess(imageURI) {
    var image = document.getElementById('myImage');
    image.src = imageURI;
}

function onFail(message) {
    alert('Failed because: ' + message);
}

拍攝照片並以 Base64 編碼圖像的形式檢索

/**
 * Warning: Using DATA_URL is not recommended! The DATA_URL destination
 * type is very memory intensive, even with a low quality setting. Using it
 * can result in out of memory errors and application crashes. Use FILE_URI
 * instead.
 */
navigator.camera.getPicture(onSuccess, onFail, { quality: 25,
    destinationType: Camera.DestinationType.DATA_URL
});

function onSuccess(imageData) {
    var image = document.getElementById('myImage');
    image.src = "data:image/jpeg;base64," + imageData;
}

function onFail(message) {
    alert('Failed because: ' + message);
}

偏好設定 (iOS)

• CameraUsesGeolocation（布林值，預設為 false）。對於擷取 JPEG，設定為 true 可在 EXIF 標頭中取得地理位置資料。如果設定為 true，這將觸發請求地理位置權限。

   <preference name="CameraUsesGeolocation" value="false" />
  

Android 特性

Android 使用 intents 在裝置上啟動相機活動以擷取圖像，而在記憶體不足的手機上，Cordova 活動可能會被終止。在這種情況下，外掛程式呼叫的結果將通過 resume 事件傳遞。請參閱Android 生命周期指南以獲取更多資訊。pendingResult.result 值將包含傳遞給回呼的值（URI/URL 或錯誤訊息）。檢查 pendingResult.pluginStatus 以確定呼叫是否成功。

瀏覽器特性

只能以 Base64 編碼圖像的形式返回照片。

iOS 特性

在任何一個回呼函式中包含 JavaScript alert() 都可能導致問題。將 alert 包裹在 setTimeout() 中，以便 iOS 圖像選擇器或彈出視窗在 alert 顯示之前完全關閉

setTimeout(function() {
    // do your thing here!
}, 0);

CameraOptions 勘誤

Android 特性

• 任何 cameraDirection 值都會產生背向照片。（= 您只能使用後置相機）

• allowEdit 在 Android 上是不可預測的，不應使用！ 此外掛程式的 Android 實現試圖在用戶的裝置上找到並使用一個應用程式來執行圖像裁剪。外掛程式無法控制使用者選擇哪個應用程式來執行圖像裁剪，並且使用者很可能會選擇不相容的選項並導致外掛程式失敗。這有時會起作用，因為大多數裝置都帶有一個應用程式可以以與此外掛程式相容的方式處理裁剪（Google 相簿），但依賴這種情況是不明智的。如果圖像編輯對您的應用程式至關重要，請考慮尋找第三方庫或外掛程式，它提供自己的圖像編輯實用程式以獲得更強大的解決方案。

• Camera.PictureSourceType.PHOTOLIBRARY 和 Camera.PictureSourceType.SAVEDPHOTOALBUM 都顯示相同的相簿。

• 如果圖像未經編輯（即 quality 為 100、correctOrientation 為 false 且未指定 targetHeight 或 targetWidth），則忽略 encodingType 參數。CAMERA 來源將始終返回原生相機提供的 JPEG 檔案，而 PHOTOLIBRARY 和 SAVEDPHOTOALBUM 來源將返回所選檔案的現有編碼。

iOS 特性

• 使用 destinationType.FILE_URI 時，照片會儲存在應用程式的臨時目錄中。當應用程式結束時，應用程式臨時目錄的內容將被刪除。

範例：拍攝照片、從圖片庫中選擇圖片並取得縮圖

相機外掛程式允許您執行諸如打開裝置的相機應用程式並拍攝照片或打開檔案選擇器並選擇一張照片之類的操作。本節中的程式碼片段示範了不同的任務，包括

• 打開相機應用程式並拍攝照片
• 拍攝照片並返回縮圖（調整大小的圖片）
• 拍攝照片並產生 FileEntry 物件
• 從圖片庫中選擇檔案
• 選擇 JPEG 圖像並返回縮圖（調整大小的圖像）
• 選擇圖像並產生 FileEntry 物件

拍攝照片

在拍攝照片之前，您需要設定一些相機外掛程式選項以傳遞到相機外掛程式的 getPicture 函式中。以下是一組常見的建議。在此範例中，您建立將用於相機選項的物件，並動態設定 sourceType 以支援相機應用程式和檔案選擇器。

function setOptions(srcType) {
    var options = {
        // Some common settings are 20, 50, and 100
        quality: 50,
        destinationType: Camera.DestinationType.FILE_URI,
        // In this app, dynamically set the picture source, Camera or photo gallery
        sourceType: srcType,
        encodingType: Camera.EncodingType.JPEG,
        mediaType: Camera.MediaType.PICTURE,
        allowEdit: true,
        correctOrientation: true
    }
    return options;
}

通常，您希望使用 FILE_URI 而不是 DATA_URL 以避免大多數記憶體問題。JPEG 是 Android 推薦的編碼類型。

您通過將選項物件傳遞給 getPicture 來拍攝照片，該物件將 CameraOptions 物件作為第三個參數。當您呼叫 setOptions 時，請傳遞 Camera.PictureSourceType.CAMERA 作為圖片來源。

function openCamera(selection) {

    var srcType = Camera.PictureSourceType.CAMERA;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    navigator.camera.getPicture(function cameraSuccess(imageUri) {

        displayImage(imageUri);
        // You may choose to copy the picture, save it somewhere, or upload.
        func(imageUri);

    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");

    }, options);
}

拍攝照片後，您可以顯示它或執行其他操作。在此範例中，從前面的程式碼中呼叫應用程式的 displayImage 函式。

function displayImage(imgUri) {

    var elem = document.getElementById('imageFile');
    elem.src = imgUri;
}

拍攝照片並返回縮圖（調整圖片大小）

若要取得較小的圖像，您可以通過使用 CameraOptions 物件傳遞 targetHeight 和 targetWidth 值來返回調整大小的圖像。在此範例中，您將返回的圖像調整大小以適合 100px x 100px 的方塊（保持長寬比，因此 100px 是高度或寬度，以來源中較大者為準）。

function openCamera(selection) {

    var srcType = Camera.PictureSourceType.CAMERA;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    if (selection == "camera-thmb") {
        options.targetHeight = 100;
        options.targetWidth = 100;
    }

    navigator.camera.getPicture(function cameraSuccess(imageUri) {

        // Do something

    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");

    }, options);
}

從圖片庫中選擇檔案

使用檔案選擇器選擇檔案時，您還需要設定 CameraOptions 物件。在此範例中，將 sourceType 設定為 Camera.PictureSourceType.SAVEDPHOTOALBUM。若要開啟檔案選擇器，請像在先前範例中所做的那樣呼叫 getPicture，並傳遞成功和錯誤回呼以及 CameraOptions 物件。

function openFilePicker(selection) {

    var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    navigator.camera.getPicture(function cameraSuccess(imageUri) {

        // Do something

    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");

    }, options);
}

選擇圖像並返回縮圖（調整大小的圖像）

調整使用檔案選擇器選擇的檔案的大小與使用相機應用程式調整大小的工作方式相同；設定 targetHeight 和 targetWidth 選項。

function openFilePicker(selection) {

    var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM;
    var options = setOptions(srcType);
    var func = createNewFileEntry;

    if (selection == "picker-thmb") {
        // To downscale a selected image,
        // Camera.EncodingType (e.g., JPEG) must match the selected image type.
        options.targetHeight = 100;
        options.targetWidth = 100;
    }

    navigator.camera.getPicture(function cameraSuccess(imageUri) {

        // Do something with image

    }, function cameraError(error) {
        console.debug("Unable to obtain picture: " + error, "app");

    }, options);
}

拍攝照片並取得 FileEntry 物件

如果您想執行諸如將圖像複製到其他位置，或使用 FileTransfer 外掛程式將其上傳到某處之類的操作，則需要取得返回圖片的 FileEntry 物件。為此，請在相機應用程式返回的檔案 URI 上呼叫 window.resolveLocalFileSystemURL。如果您需要使用 FileEntry 物件，請在 CameraOptions 物件中將 destinationType 設定為 Camera.DestinationType.FILE_URI（這也是預設值）。

注意 您需要檔案外掛程式才能呼叫 window.resolveLocalFileSystemURL。

以下是對 window.resolveLocalFileSystemURL 的呼叫。圖像 URI 會從 getPicture 的成功回呼傳遞到此函式。resolveLocalFileSystemURL 的成功處理程序會接收 FileEntry 物件。

function getFileEntry(imgUri) {
    window.resolveLocalFileSystemURL(imgUri, function success(fileEntry) {

        // Do something with the FileEntry object, like write to it, upload it, etc.
        // writeFile(fileEntry, imgUri);
        console.log("got file: " + fileEntry.fullPath);
        // displayFileData(fileEntry.nativeURL, "Native URL");

    }, function () {
      // If don't get the FileEntry (which may happen when testing
      // on some emulators), copy to a new FileEntry.
        createNewFileEntry(imgUri);
    });
}

在前面程式碼中顯示的範例中，如果您沒有取得有效的 FileEntry 物件，則會呼叫應用程式的 createNewFileEntry 函式。從相機應用程式返回的圖像 URI 應產生有效的 FileEntry，但某些模擬器上的平台行為對於從檔案選擇器返回的檔案可能會有所不同。

注意 若要查看寫入 FileEntry 的範例，請參閱檔案外掛程式的 README。

這裡顯示的程式碼會在您應用程式的快取（在沙箱儲存空間中）中建立名為 tempFile.jpeg 的檔案。使用新的 FileEntry 物件，您可以將圖像複製到檔案或執行其他操作，例如上傳。

function createNewFileEntry(imgUri) {
    window.resolveLocalFileSystemURL(cordova.file.cacheDirectory, function success(dirEntry) {

        // JPEG file
        dirEntry.getFile("tempFile.jpeg", { create: true, exclusive: false }, function (fileEntry) {

            // Do something with it, like write to it, upload it, etc.
            // writeFile(fileEntry, imgUri);
            console.log("got file: " + fileEntry.fullPath);
            // displayFileData(fileEntry.fullPath, "File copied to");

        }, onErrorCreateFile);

    }, onErrorResolveUrl);
}