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

Также возможно установить через URL репозитория напрямую (нестабильно)

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

Как внести вклад

Вкладчики приветствуются! Нам нужны ваши contributions, чтобы проект продолжал развиваться. Вы можете [сообщить об ошибках, улучшить документацию или внести код.

Мы рекомендуем использовать специфический рабочий процесс для вкладчиков. Начните с чтения его. Дополнительная информация доступна на нашем вики-сайте.

Есть решение? Отправьте запрос на вытягивание.

Для принятия ваших изменений необходимо подписать и отправить соглашение Apache ICLA (Индивидуальное соглашение о лицензии на вклад). Тогда ваше имя появится в списке подписанных не-коммитеров или коммитеров Cordova.

И не забудьте протестировать и задокументировать свой код.

Особенности iOS

Начиная с iOS 10, обязательно указывать описание использования в info.plist, если вы пытаетесь получить доступ к данным, чувствительным к конфиденциальности. Когда система предложит пользователю разрешить доступ, это описание использования будет отображено в диалоговом окне разрешений, но если вы не предоставите его, приложение аварийно завершит работу перед отображением диалога. Кроме того, Apple отклонит приложения, которые получают доступ к конфиденциальным данным, но не предоставляют описание использования.

Этот плагин требует следующих описаний использования:

• NSCameraUsageDescription описывает причину доступа приложения к камере устройства.
• NSPhotoLibraryUsageDescription описывает причину доступа приложения к фотогалерее пользователя.
• NSLocationWhenInUseUsageDescription описывает причину доступа приложения к информации о местоположении пользователя во время работы приложения. (Установите его, если у вас есть CameraUsesGeolocation предпочитаемый true)
• NSPhotoLibraryAddUsageDescription описывает причину доступа приложения к записи только в фотогалерее пользователя.

Чтобы добавить эти записи в info.plist, вы можете использовать тег edit-config в config.xml, как показано ниже:

<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

• camera

  • .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

camera.getPicture(successCallback, errorCallback, options)

Снимает фотографию с помощью камеры или извлекает фотографию из галереи устройства. Изображение передается в обратный вызов success как закодированная в Base64 String или как URI файла изображения.

Функция camera.getPicture открывает стандартное приложение камеры устройства, которое по умолчанию позволяет пользователям делать снимки — это поведение происходит, когда Camera.sourceType равно Camera.PictureSourceType.CAMERA. После того, как пользователь сделает снимок, приложение камеры закрывается, и приложение восстанавливается.

Если Camera.sourceType равно Camera.PictureSourceType.PHOTOLIBRARY или Camera.PictureSourceType.SAVEDPHOTOALBUM, отображается диалоговое окно, позволяющее пользователю выбрать существующее изображение.

Значение возврата отправляется в обратный вызов cameraSuccess в одном из следующих форматов в зависимости от заданных cameraOptions:

• String, содержащая изображение фотографии в кодировке Base64.
• String, представляющий расположение файла изображения в локальном хранилище (по умолчанию).

Вы можете делать с закодированным изображением или URI все, что хотите, например:

• Отобразить изображение в теге <img>, как в примере ниже
• Сохранить данные локально (LocalStorage, Lawnchair и т. д.)
• Отправить данные на удаленный сервер

ПРИМЕЧАНИЕ: Разрешение фото на более новых устройствах довольно хорошее. Фотографии, выбранные из галереи устройства, не уменьшаются до низкого качества, даже если указан параметр quality. Для предотвращения распространенных проблем с памятью, задайте Camera.destinationType значение FILE_URI вместо DATA_URL.

Поддерживаемые платформы

• Android
• Браузер
• iOS
• Windows
• OSX

Дополнительные примеры здесь. Особенности здесь.

Вид: статический метод 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

camera.onSuccess : function

Функция обратного вызова, которая предоставляет данные изображения.

Вид: статический тип camera

Пример

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

camera.CameraOptions : Object

Необязательные параметры для настройки параметров камеры.

• Особенности

Вид: статический тип camera
Свойства

Camera

Camera.DestinationType : enum

Определяет формат вывода вызова Camera.getPicture. Примечание: на iOS передача DestinationType.NATIVE_URI вместе с PictureSourceType.PHOTOLIBRARY или PictureSourceType.SAVEDPHOTOALBUM отключит любые изменения изображений (изменение размера, качества, обрезка и т.д.) из-за особенностей реализации.

Тип: статическое свойство перечисления Camera
Свойства

Camera.EncodingType : enum

Тип: статическое свойство перечисления Camera
Свойства

Camera.MediaType : enum

Тип: статическое свойство перечисления Camera
Свойства

Camera.PictureSourceType : enum

Определяет формат вывода вызова Camera.getPicture. Примечание: на iOS передача PictureSourceType.PHOTOLIBRARY или PictureSourceType.SAVEDPHOTOALBUM вместе с DestinationType.NATIVE_URI отключит любые изменения изображений (изменение размера, качества, обрезка и т.д.) из-за особенностей реализации.

Тип: статическое свойство перечисления Camera
Свойства

Camera.PopoverArrowDirection : enum

Сопоставляет константы iOS UIPopoverArrowDirection для указания местоположения стрелки на всплывающем окне.

Тип: статическое свойство перечисления Camera
Свойства

Camera.Direction : enum

Тип: статическое свойство перечисления 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
 * 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" />
  

Особенности Android

Android использует намерения для запуска деятельности камеры на устройстве для захвата изображений, а на телефонах с низкой памятью активность Cordova может быть убита. В этом случае результат вызова плагина будет передан через событие возобновления. См. Руководство по жизненному циклу Android для получения дополнительной информации. Значение pendingResult.result будет содержать значение, которое будет передано в обратные вызовы (либо URI/URL, либо сообщение об ошибке). Проверьте значение pendingResult.pluginStatus, чтобы определить, был ли вызов успешным.

Особенности браузера

Может возвращать фотографии только в формате изображения, закодированного в Base64.

Особенности iOS

Включение JavaScript alert() в любом из обратных вызовов может вызвать проблемы. Оберните alert в setTimeout(), чтобы позволить iOS-выбору изображения или всплывающему окну полностью закрыться перед отображением alert:

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 см. здесь: Как продолжить работу приложения Windows Phone после вызова средства выбора файлов

CameraOptions Ошибки

Особенности Android

• Любое значение cameraDirection приводит к фото с задней камеры. (= Вы можете использовать только заднюю камеру)

• allowEdit непредсказуемо в Android, и его не следует использовать! Реализация этого плагина в Android пытается найти и использовать приложение на устройстве пользователя для обрезки изображений. Плагин не имеет контроля над тем, какое приложение пользователь выберет для обрезки изображения, и очень вероятно, что пользователь выберет несовместимый вариант, что приведет к ошибке плагина. Иногда это работает, потому что большинство устройств поставляются с приложением, которое обрабатывает обрезку таким образом, который совместим с этим плагином (Google Plus Photos), но полагаться на это неразумно. Если редактирование изображений необходимо для вашего приложения, рассмотрите использование сторонней библиотеки или плагина, который предоставляет собственное средство редактирования изображений для более надежного решения.

• Camera.PictureSourceType.PHOTOLIBRARY и Camera.PictureSourceType.SAVEDPHOTOALBUM отображают один и тот же фотоальбом.

• Игнорирует параметр encodingType, если изображение не отредактировано (т.е. quality равно 100, correctOrientation равно false и не указаны targetHeight или targetWidth). Источник CAMERA всегда возвращает JPEG-файл, предоставляемый родной камерой, а источники PHOTOLIBRARY и SAVEDPHOTOALBUM возвращают выбранный файл в его существующей кодировке.

Особенности iOS

• При использовании destinationType.FILE_URI, фотографии сохраняются в временном каталоге приложения. Содержимое временного каталога приложения удаляется при завершении работы приложения.

• При использовании destinationType.NATIVE_URI и sourceType.CAMERA, фотографии сохраняются в сохранённом фотоальбоме независимо от значения параметра saveToPhotoAlbum.

• При использовании destinationType.NATIVE_URI и sourceType.PHOTOLIBRARY или sourceType.SAVEDPHOTOALBUM, все параметры редактирования игнорируются, и ссылка возвращается к исходному изображению.

Пример: Сделать фотографии, выбрать фотографии из галереи и получить миниатюры

Плагин камеры позволяет выполнять такие действия, как открытие приложения камеры устройства и фотографирование, или открытие выбора файла и выбор одного. Приведённые в этом разделе фрагменты кода демонстрируют различные задачи, включая:

• Открыть приложение камеры и сделать фотографию
• Сделать фотографию и вернуть миниатюры (изменённое изображение)
• Сделать фотографию и сгенерировать объект 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;
}

Как правило, вы хотите использовать FILEURI вместо DATAURL, чтобы избежать большинства проблем с памятью. 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;
}

Для отображения изображения на некоторых платформах вам может потребоваться включить основную часть URI в элемент Content-Security-Policy <meta> в файле index.html. Например, в Windows 10 вы можете включить ms-appdata: в свой элемент <meta>. Вот пример.

<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 *">

Сделать фотографию и вернуть миниатюры (изменить размер изображения)

Чтобы получить меньшие изображения, вы можете вернуть изменённое изображение, передав как targetHeight, так и targetWidth значения с объектом CameraOptions. В этом примере вы изменяете размер возвращаемого изображения, чтобы оно поместилось в прямоугольник 100x100 пикселей (сохраняется соотношение сторон, поэтому 100 пикселей — это либо высота, либо ширина, в зависимости от того, какая больше в источнике).

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 для возвращённого изображения. Для этого вызовите window.resolveLocalFileSystemURL для URI файла, возвращённого приложением камеры. Если вам нужен объект FileEntry, установите destinationType в Camera.DestinationType.FILE_URI в вашем объекте CameraOptions (это также значение по умолчанию).

Примечание Вам нужен плагин 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);
    });
}

В примере, показанном в предыдущем коде, вызывается функция createNewFileEntry приложения, если вы не получаете действительный объект FileEntry. URI изображения, возвращаемый приложением камеры, должен привести к созданию действительного объекта FileEntry, но поведение платформы в некоторых эмуляторах может отличаться для файлов, возвращаемых выбором файла.

Примечание Чтобы увидеть пример записи в FileEntry, см. README плагина File.

Здесь показанный код создаёт файл в кэше приложения (в защищённом хранилище) с именем 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);
}