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 上找到。

有解决方案吗？发送一个拉取请求。

为了使您的更改被接受，您需要签署并提交 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) 的静态类型定义

camera.onSuccess : function

提供图像数据的回调函数。

类型：[camera](#module_camera) 的静态类型定义

示例

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

camera.CameraOptions : Object

用于自定义相机设置的可选参数。

• 特性

类型：[camera](#module_camera) 的静态类型定义
属性

相机

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

浏览器特性

只能以 Base64 编码的图像形式返回照片。

iOS 特性

在任何回调函数中包含 JavaScript alert() 可能会导致问题。将 alert 包裹在 setTimeout() 中，以便在显示 alert 之前让 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 时，照片将保存在应用程序的临时目录中。当应用程序结束时，应用程序临时目录的内容将被删除。

示例：拍摄照片、从图片库中选择图片和获取缩略图

Camera 插件允许您执行诸如打开设备的相机应用程序并拍摄照片，或打开文件选择器并选择一个照片之类的操作。本节中的代码片段演示了不同的任务，包括：

• 打开相机应用并拍摄照片
• 拍摄照片并返回缩略图（调整大小后的图片）
• 拍摄照片并生成 FileEntry 对象
• 从图片库中选择文件
• 选择 JPEG 图像并返回缩略图（调整大小后的图像）
• 选择图像并生成 FileEntry 对象

拍摄照片

在拍摄照片之前，您需要设置一些 Camera 插件选项，以传递给 Camera 插件的 getPicture 函数。这是一个常见的建议集合。在此示例中，您创建一个将用于 Camera 选项的对象，并将 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 推荐的编码类型。

通过将 options 对象传递给 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;
}

拍摄照片并返回缩略图（调整图片大小）

要获取较小的图像，您可以通过将 targetHeight 和 targetWidth 值与您的 CameraOptions 对象一起传递来返回调整大小后的图像。在此示例中，将返回的图像调整大小以适合 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（这也是默认值）。

注意 您需要File 插件才能调用 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);
}