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

也可以直接通过仓库 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

如何贡献

欢迎贡献者！我们需要您的贡献来推动项目发展。您可以[报告错误，改进文档，或 贡献代码。

我们推荐一个特定的 贡献者工作流程。从那里开始阅读。更多信息可以在 我们的维基 上找到。

有解决方案吗？ 发送一个 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，则会显示一个对话框，允许用户选择现有图片。

返回值会发送到 cameraSuccess 回调函数，以以下格式之一发送，具体取决于指定的 cameraOptions

• 包含 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 使用意图在设备上启动相机活动以捕获图像，在内存不足的手机上，Cordova 活动可能会被杀死。在这种情况下，插件调用的结果将通过 resume 事件传递。有关更多信息，请参阅Android 生命周期指南。pendingResult.result 值将包含传递给回调的值（URI/URL 或错误消息）。检查pendingResult.pluginStatus 以确定调用是否成功。

浏览器问题

只能将照片作为 Base64 编码的图像返回。

iOS 特性

在任何回调函数中包含 JavaScript alert() 都会导致问题。将警报包装在 setTimeout() 中，以允许 iOS 图像选择器或弹出窗口在警报显示之前完全关闭

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 来拍摄照片，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 对象。为此，请在 getPicture 返回的文件 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 的示例，请参阅文件插件自述文件。

此处显示的代码在您的应用程序缓存（在沙盒存储中）中创建了一个名为 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);
}