标题：相机

描述：使用设备相机拍照。

Android	iOS	Windows 8.1 Store	Windows 8.1 Phone	Windows 10 Store	Travis CI

cordova-plugin-camera

此插件定义了一个全局的 navigator.camera 对象，该对象提供了拍照和从系统相册中选择图像的 API。

尽管该对象附加到全局作用域的 navigator，但它仅在 deviceready 事件之后可用。

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

安装

这需要 cordova 5.0+

cordova plugin add cordova-plugin-camera

旧版本 cordova 仍然可以通过已弃用的 id 进行安装

cordova plugin add org.apache.cordova.camera

还可以直接通过 repo url 安装（不稳定）

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

如何贡献

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

我们特别推荐一个贡献者工作流程。从这里开始阅读。更多信息可在我们的维基百科中找到。

⚠️ 发现了问题吗？ 在JIRA 错误跟踪器上提交。

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

为了使您的更改被接受，您需要签署并提交 Apache ICLA（个人贡献者许可协议）。然后您的名字将出现在非贡献者或Cordova 贡献者签署的 CLA 列表中。

不要忘记测试和记录您的代码。

此文档由工具生成

⚠️在插件仓库中运行 npm install 以启用自动文档生成（如果您计划提交代码审查请求）。
使用 jsdoc-to-markdown 生成文档。
文档包括从插件 JS 代码生成的模板和 API 文档，每次提交前都应重新生成（通过 husky 自动执行，运行 npm run gen-docs 脚本作为 precommit 插件 - 详细信息请参阅 package.json）。

iOS 奇偶性

从 iOS 10 开始，必须在 info.plist 中添加 NSCameraUsageDescription 和 NSPhotoLibraryUsageDescriptionentry。

• NSCameraUsageDescription 描述了应用程序访问用户摄像头的理由。
• NSPhotoLibraryUsageDescriptionentry 描述了应用程序访问用户照片库的理由。

当系统提示用户允许访问时，此字符串将作为对话框的一部分显示。

要添加此条目，您可以在安装插件时传递以下变量。

• CAMERA_USAGE_DESCRIPTION 用于 NSCameraUsageDescription

- PHOTOLIBRARY_USAGE_DESCRIPTION 用于 NSPhotoLibraryUsageDescriptionentry

示例

cordova plugin add cordova-plugin-camera --variable CAMERA_USAGE_DESCRIPTION="your usage message"

如果您不传递变量，插件将添加一个空字符串作为值。

API 参考

• 相机

  • .getPicture(successCallback, errorCallback, options)
  • .cleanup()
  • .onError : function
  • .onSuccess : function
  • .CameraOptions : Object

• Camera

  • .DestinationType : enum
  • .EncodingType : enum
  • .MediaType : enum
  • .PictureSourceType : enum
  • .PopoverArrowDirection : enum
  • .Direction : enum

• CameraPopoverHandle

• CameraPopoverOptions

相机

camera.getPicture(successCallback, errorCallback, options)

使用相机拍照或从设备图片库中获取图片。该图片作为 Base64 编码的 String 或图片文件 URI 传递给 success 回调函数。

如果 Camera.sourceType 等于 Camera.PictureSourceType.CAMERA，则 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
• BlackBerry
• 浏览器
• Firefox
• FireOS
• iOS
• Windows
• WP8
• Ubuntu

更多示例这里。怪癖这里。

类型：camera的静态方法

示例

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

camera.cleanup()

在调用camera.getPicture后，从临时存储中删除中间图像文件。仅当Camera.sourceType的值等于Camera.PictureSourceType.CAMERA以及Camera.destinationType等于Camera.DestinationType.FILE_URI时适用。

支持的平台

• iOS

类型：camera的静态方法
示例

navigator.camera.cleanup(onSuccess, onFail);

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

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

camera.onError：function

回调函数提供错误消息。

类型：camera的静态typedef

camera.onSuccess：function

回调函数提供图像数据。

类型：camera的静态typedef

示例

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

camera.CameraOptions：Object

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

• 怪癖

类型：camera的静态typedef
属性

Camera

Camera.DestinationType：enum

定义了 Camera.getPicture 调用的输出格式。 注意：在iOS上，如果您使用 DestinationType.NATIVE_URI 并与 PictureSourceType.PHOTOLIBRARY 或 PictureSourceType.SAVEDPHOTOALBUM 一起传递，则会由于实现特定原因禁用任何图像修改（调整大小、质量改变、裁剪等）。

类型：Camera 的静态枚举属性
属性

Camera.EncodingType : 枚举

类型：Camera 的静态枚举属性
属性

Camera.MediaType : 枚举

类型：Camera 的静态枚举属性
属性

Camera.PictureSourceType : 枚举

定义了 Camera.getPicture 调用的输出格式。 注意：在iOS上，如果使用 PictureSourceType.PHOTOLIBRARY 或 PictureSourceType.SAVEDPHOTOALBUM 并与 DestinationType.NATIVE_URI 一起传递，则会由于实现特定原因禁用任何图像修改（调整大小、质量改变、裁剪等）。

类型：Camera 的静态枚举属性
属性

Camera.PopoverArrowDirection : 枚举

匹配iOS UIPopoverArrowDirection常量，以指定弹出层上的箭头位置。

类型：Camera 的静态枚举属性
属性

Camera.Direction : 枚举

类型：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)
});

// 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);
    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
 * or NATIVE_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" />
  

亚马逊火机操作系统怪癖

亚马逊火机操作系统使用意图启动设备上的相机活动以捕获图像，并且在使用低内存的手机上，Cordova活动可能会被杀死。在这种情况下，当Cordova活动恢复时，图像可能不会出现。

Android怪癖

Android使用意图启动设备上的相机活动来捕获图像，并且在使用低内存的手机上，Cordova活动可能会被杀死。在这种情况下，插件调用的结果将通过resume事件传递。请参阅Android生命周期指南以获取更多信息。The pendingResult.result的值将包含将被传递给回调函数的值（无论是URI/URL还是错误消息）。通过检查pendingResult.pluginStatus来确定调用是否成功。

浏览器怪癖

只能返回Base64编码的图像。

Firefox OS怪癖

相机插件目前使用Web Activities实现。

iOS怪癖

在任一回调函数中包含JavaScript alert()可能会导致问题。将alert包装在setTimeout()中，以便在alert显示之前iOS图像选择器或弹出对话框完全关闭

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

Windows Phone 7怪癖

当设备通过Zune连接时调用本地相机应用程序不起作用，并引发错误回调。

Windows怪癖

在Windows Phone 8.1上使用SAVEDPHOTOALBUM或PHOTOLIBRARY作为源类型会导致应用程序挂起，直到文件选择器返回所选图像，然后以在应用程序的config.xml中定义的起始页面恢复。如果从不同的页面调用camera.getPicture，这将导致从头开始重新加载起始页面，并且成功和错误回调将永远不会调用。

为了避免这种情况，我们建议使用SPA模式或仅从您的应用程序起始页调用camera.getPicture。

有关Windows Phone 8.1选择器API的更多信息，请参阅此处：在调用文件选择器后如何继续Windows Phone应用程序

Tizen怪癖

Tizen仅支持destinationType为Camera.DestinationType.FILE_URI和sourceType为Camera.PictureSourceType.PHOTOLIBRARY。

CameraOptions更正信息

亚马逊火机操作系统怪癖

• 任何cameraDirection的值都导致背面照片。

• 忽略 allowEdit 参数。

• Camera.PictureSourceType.PHOTOLIBRARY 和 Camera.PictureSourceType.SAVEDPHOTOALBUM 都显示相同的相册。

Android 宽容的行为

• 任何cameraDirection的值都导致背面照片。

• allowEdit 在 Android 上的行为不可预测，不应使用！ 此插件的 Android 实现尝试查找并使用用户设备上的应用程序来执行图像裁剪。插件无法控制用户选择的图像裁剪应用程序，用户可能选择一个不兼容的选项，从而导致插件失败。这有时能正常工作，因为大多数设备都附带了一个与该插件兼容的方式处理裁剪的图像应用程序（例如 Google Plus Photos），但依赖于这一点是不明智的。如果图像编辑对您的应用程序至关重要，请考虑寻求第三方库或插件，它提供自己的图像编辑工具，以提供更稳健的解决方案。

• Camera.PictureSourceType.PHOTOLIBRARY 和 Camera.PictureSourceType.SAVEDPHOTOALBUM 都显示相同的相册。

• 如果图像未编辑（即 quality 是 100，correctOrientation 为 false，没有指定 targetHeight 或 targetWidth），则忽略 encodingType 参数。 CAMERA 源始终返回原生相机提供的 JPEG 文件，而 PHOTOLIBRARY 和 SAVEDPHOTOALBUM 源将返回对应的所选文件，保持其现有编码。

BlackBerry 10 宽容的行为

• 忽略 quality 参数。

• 忽略 allowEdit 参数。

• 不支持 Camera.MediaType。

• 忽略 correctOrientation 参数。

• 忽略 cameraDirection 参数。

Firefox OS 宽容的行为

• 忽略 quality 参数。

• Camera.DestinationType 被忽略，等于 1（图像文件 URI）

• 忽略 allowEdit 参数。

• 忽略 PictureSourceType 参数（用户在对话框窗口中选择它）

• 忽略 encodingType

• 忽略 targetWidth 和 targetHeight

• 不支持 Camera.MediaType。

• 忽略 correctOrientation 参数。

• 忽略 cameraDirection 参数。

iOS 宽容的行为

• 使用 destinationType.FILE_URI 时，照片将保存在应用程序的临时目录中。当应用程序结束时，应用程序临时目录的内容将被删除。

• 使用 destinationType.NATIVE_URI 和 sourceType.CAMERA 时，无论 saveToPhotoAlbum 参数的值如何，照片都会保存在已保存的相册中。

• 使用 destinationType.NATIVE_URI 和 sourceType.PHOTOLIBRARY 或 sourceType.SAVEDPHOTOALBUM 时，所有编辑选项都被忽略，并返回到原始图片。

Tizen 宽容的行为

• 不支持选项

• 总是返回一个 FILE URI

Windows Phone 7 和 8 宽容的行为

• 忽略 allowEdit 参数。

• 忽略 correctOrientation 参数。

• 忽略 cameraDirection 参数。

• 忽略 saveToPhotoAlbum 参数。重要：使用 WP8/8 Cordova 摄像头 API 拍摄的图像总是复制到手机的相册中。根据用户的设置，这也可能意味着图像会自动上传到他们的 OneDrive。这可能意味着图像的受众比您的应用程序预期更广。如果这是应用程序的障碍，您需要按照 MSND 上文档将 CameraCaptureTask 实现。您还可以在问题跟踪器中评论或向上投票相关的部分。

• 忽略 cameraOptions 的 mediaType 属性，因为 Windows Phone SDK 不提供从 PHOTOLIBRARY 选择视频的方法。

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

相册插件允许您执行诸如打开设备相机应用拍照或打开文件选择器选择图片等操作。本节中的代码示例展示了不同的任务，包括

• 打开相机应用并拍照
• 拍照并返回缩略图（调整大小后的图片）
• 拍照并生成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  //Corrects Android orientation quirks
    }
    return options;
}

通常，您希望使用FILE_URI而不是DATA_URL以避免大多数内存问题。JPEG是Android推荐的编码类型。

通过将选项对象传递给getPicture函数来拍照，其中getPicture将相机选项对象作为第三个参数。当调用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;
}

要在某些平台上显示图片，可能需要在index.html中Content-Security-Policy <meta>元素中包含URI的主要部分。例如，在Windows 10上，您可以在<meta>元素中包含ms-appdata:。以下是一个示例。

<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">

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

为了获取更小的图片，您可以通过传递带有您的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 需要 File 插件。

以下是调用 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 的示例，请参阅 File 插件 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);
}