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

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

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

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

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

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

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

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

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

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

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

Начиная с iOS 10 необходимо добавить NSCameraUsageDescription и NSPhotoLibraryUsageDescriptionentry в файл info.plist.

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

Когда система запросит разрешение у пользователя, эта строка отобразится в диалоговом окне.

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

• CAMERA_USAGE_DESCRIPTION для NSCameraUsageDescription

- PHOTOLIBRARY_USAGE_DESCRIPTION для NSPhotoLibraryUsageDescriptionentry

Пример:

cordova plugin add cordova-plugin-camera --variable CAMERA_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)

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

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

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

Возвращаемое значение отправляется в функцию обратного вызова cameraSuccess, в одном из следующих форматов, в зависимости от указанных cameraOptions.

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

Вы можете сделать с закодированным изображением или 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

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

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

camera.onSuccess : function

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

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

Пример

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

camera.CameraOptions : Object

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

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

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

Пример

Сделать снимок и получить расположение файла изображения:

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 по жизненному циклу Android для получения дополнительной информации. Значение pendingResult.result будет содержать значение, которое будет передано в обратные вызовы (либо URI/URL, либо сообщение об ошибке). Проверьте pendingResult.pluginStatus, чтобы определить, был ли вызов успешным.

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

Может возвращать фотографии только в формате Base64.

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

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

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

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

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

CameraOptions Errata

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

• Игнорирует свойство mediaType объекта cameraOptions, так как Windows Phone SDK не предоставляет способ выбора видео из PHOTOLIBRARY.

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

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

• Открыть приложение камеры и сделать снимок
• Сделать снимок и вернуть миниатюры (уменьшенное изображение)
• Сделать снимок и сгенерировать объект FileEntry
• Выбрать файл из фотогалереи
• Выбрать изображение JPEG и вернуть миниатюры (уменьшенное изображение)
• Выбрать изображение и сгенерировать объект FileEntry

Сделать снимок

Прежде чем вы сможете сделать снимок, вам необходимо установить некоторые параметры плагина Camera, чтобы передать их в функцию плагина Camera 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.

Вы делаете снимок, передавая объект options в 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);
}