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 по-прежнему могут быть установлены с помощью устаревшего идентификатора

cordova plugin add org.apache.cordova.camera

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

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

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

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

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

:warning: Обнаружена проблема? Сообщите об этом в системе отслеживания ошибок JIRA.

Есть решение? Отправьте запрос на добавление изменений.

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

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

Эта документация сгенерирована инструментом

:warning: Запустите npm install в репозитории плагина, чтобы включить автоматическое генерирование документации, если вы планируете отправлять PR.
jsdoc-to-markdown используется для генерации документации.
Документация состоит из шаблона и документации API, сгенерированной из кода плагина JS, и должна быть перегенерирована перед каждым коммитом (автоматически выполняется через husky, выполняя npm run gen-docs скрипт как precommit хук - см. package.json для подробностей).

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

С iOS 10 обязательно добавить NSCameraUsageDescription и NSPhotoLibraryUsageDescription в info.plist.

• NSCameraUsageDescription описывает причину доступа приложения к камере пользователя.
• NSPhotoLibraryUsageDescription описывает причину доступа приложения к фотобиблиотеке пользователя.

При запросе системы на разрешение доступа эта строка отображается в диалоговом окне.

Для добавления этой записи можно передать следующие переменные при установке плагина.

• CAMERA_USAGE_DESCRIPTION для NSCameraUsageDescription
• PHOTOLIBRARY_USAGE_DESCRIPTION для NSPhotoLibraryUsageDescription

Пример:

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

Если вы не передадите переменную, плагин добавит пустую строку в качестве значения.

Справочник по 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
• 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

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.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)
});

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

Особенности Amazon Fire OS

Amazon Fire OS использует намерения для запуска действия камеры на устройстве для захвата изображений, а на телефонах с малым объёмом памяти активность Cordova может быть завершена. В этом случае изображение может не отобразиться при восстановлении активности Cordova.

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

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

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

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

Особенности Firefox OS

Плагин камеры в настоящее время реализован с использованием Web Activities.

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

Включение JavaScript alert() в любом из функций обратного вызова может вызвать проблемы. Оберните всплывающее окно в setTimeout() для того, чтобы позволить 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 только с начальной страницы приложения.

Дополнительную информацию об API средств выбора файла Windows Phone 8.1 можно найти здесь: Как продолжить работу приложения Windows Phone после вызова средства выбора файла

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

Tizen поддерживает только destinationType Camera.DestinationType.FILE_URI и sourceType Camera.PictureSourceType.PHOTOLIBRARY.

CameraOptions Ошибки

Особенности Amazon Fire OS

• Любое значение cameraDirection приводит к фото с задней камерой.

• Игнорирует параметр allowEdit.

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

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

• Любое значение cameraDirection приводит к фото с задней камерой.

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

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

• Игнорирует параметр encodingType, если изображение не отредактировано (т.е. quality равно 100, correctOrientation ложно, и не указаны targetHeight или targetWidth). Источник 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. ВАЖНО: все изображения, сделанные с помощью Cordova API камеры WP8/8, всегда копируются в фотогалерею телефона. В зависимости от настроек пользователя, это также может означать автоматическую загрузку изображения в OneDrive. Это может означать, что изображение будет доступно более широкой аудитории, чем предполагалось вашим приложением. Если это является проблемой для вашего приложения, вам необходимо реализовать CameraCaptureTask, как описано в MSDN. Вы также можете прокомментировать или проголосовать за соответствующую задачу в системе отслеживания ошибок.

• Игнорирует свойство mediaType cameraOptions, так как 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;
}

Обычно для предотвращения большинства проблем с памятью вы хотите использовать 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);
    });
}

В приведённом выше примере, если вы не получите действительный объект FileEntry, вызывается функция createNewFileEntry приложения. 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);
}