Камера

Описание: Возможность делать фотографии с помощью камеры устройства.

Установка

Для этого требуется 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

Этот плагин определяет глобальный объект navigator.camera, который предоставляет API для съёмки фотографий и выбора изображений из библиотеки изображений системы.

Хотя объект присоединён к глобальному объекту navigator, он недоступен до тех пор, пока не произойдёт событие deviceready.

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

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

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

Существует специальный рабочий процесс для участников, который мы рекомендуем. Начните читать там. Более подробная информация доступна на нашем сайте. ### Этот текст представляет собой перевод исходного текста на русский язык:

Обнаружили проблему? Зарегистрируйте её в системе отслеживания ошибок JIRA по ссылке JIRA issue tracker.

Есть решение? Отправьте запрос на включение изменений (Pull Request) по ссылке Pull Request.

Чтобы ваши изменения были приняты, вам необходимо подписать и отправить индивидуальное лицензионное соглашение участника Apache (Individual Contributor License Agreement). После этого ваше имя появится в списке CLA, подписанном не коммиттерами или коммиттерами Cordova (см. ссылки ниже).

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

Эта документация создана с помощью инструмента

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

API Reference

• 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 или в виде URI файла изображения.

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

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

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

• Строка, содержащая изображение в формате Base64.

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

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

• Отобразить изображение в теге <img>, как в примере ниже.

• Сохранить данные локально (LocalStorage, ### CameraPopoverOptions

CameraPopoverOptions — это параметры, которые используются только на iOS и определяют расположение popover в iPad.

• ARROW_UP — 1;
• ARROW_DOWN — 2;
• ARROW_LEFT — 4;
• ARROW_RIGHT — 8;
• ARROW_ANY — 15.

| sourceRect | Rect | Задаёт область предварительного просмотра изображения. | | cameraDirection | Direction | Определяет камеру, которая будет использоваться (фронтальная или тыловая). |

Браузерные особенности

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

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

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

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

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

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

Windows Phone 7: особенности

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

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 — false, а 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.

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

• Параметры не поддерживаются.
• Всегда возвращается URI файла.

Windows Phone 7 и 8: особенности

• Игнорируется параметр allowEdit.
• Игнорируется параметр correctOrientation.
• Игнорируется параметр cameraDirection.
• Игнорируется параметр saveToPhotoAlbum. Важно: все изображения, сделанные с помощью WP8/8 Cordova camera API, всегда копируются в фотоальбом телефона. В зависимости от настроек пользователя это также может означать, что изображение

[web_activities]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Activities_API Автоматически загружено в OneDrive. Это может означать, что изображение доступно более широкой аудитории, чем предполагалось вашим приложением. Если это является блокировщиком для вашего приложения, вам необходимо реализовать CameraCaptureTask, как описано в MSDN. Вы также можете прокомментировать или проголосовать за соответствующую проблему в системе отслеживания проблем.

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

Образцы: Делайте снимки, выбирайте изображения из библиотеки изображений и получайте эскизы

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

• Открытие приложения камеры и съёмку фотографии;
• Съёмку фотографии и получение эскизов (изображение изменённого размера);
• Съёмку фотографии и генерацию объекта FileEntry;
• Выбор файла из библиотеки изображений;
• Выбор изображения JPEG и получение эскизов (изменённое изображение);
• Выбор изображения и генерация объекта FileEntry.

Съёмка фотографии

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

function setOptions(srcType) {
    var options = {
        // Некоторые общие настройки — 20, 50 и 100
        quality: 50,
        destinationType: Camera.DestinationType.FILE_URI,
        // В этом приложении динамически установите источник изображения, камеру или фотогалерею
        sourceType: srcType,
        encodingType: Camera.EncodingType.JPEG,
        mediaType: Camera.MediaType.PICTURE,
        allowEdit: true,
        correctOrientation: true  //Исправляет ошибки ориентации Android
    }
    return options;
}

Обычно вы хотите использовать FILE_URI вместо DATA_URL, чтобы избежать большинства проблем с памятью. 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);
        // Вы можете выбрать копирование изображения, сохранение его где-нибудь или загрузку.
        func(imageUri);

    }, function cameraError(error) {
        console.debug("Невозможно получить изображение: " + error, "app");

    }, options);
}

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

function displayImage(imgUri) {

    var elem = document.getElementById('imageFile');
    elem.src = imgUri;
}

Чтобы отобразить изображение на некоторых платформах, вам может потребоваться включить основную часть URI в элемент <meta> Content-Security-Policy в 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. В этом примере изображение уменьшается до размера 100 на 100 пикселей (соотношение сторон сохраняется, поэтому 100 пикселями будет либо высота, либо ширина, в зависимости от того, что больше в исходном изображении).

```js
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.SAVEDPHOTOALBUME;
    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") {
        // Чтобы уменьшить выбранное изображение,
        // Camera.EncodingType (например, JPEG) должен соответствовать выбранному типу изображения.
        options.targetHeight = 100;
        options.targetWidth = 100;
    }

    navigator.camera.getPicture(function cameraSuccess(imageUri) {

        // Сделайте что-нибудь с изображением

    }, function cameraError(error) {
        console.debug("Невозможно получить изображение: " + ошибка, "приложение");

    }, параметры);
}

Сделайте снимок и получите объект 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) {

        // Сделайте что-нибудь с объектом FileEntry, например, запишите в него, загрузите и т. д.
        // writeFile(fileEntry, imgUri);
        console.log("получил файл: " + fileEntry.fullPath);
        // displayFileData(fileEntry.nativeURL, "Native URL");

    }, function () {
      // Если вы не получаете объект FileEntry (что может произойти при тестировании
      // на некоторых эмуляторах), скопируйте его в новый объект FileEntry.
        createNewFileEntry(imgUri);
    });
}

В примере, показанном в предыдущем коде, вы вызываете функцию приложения createNewFileEntry, если вы не получили объект FileEntry (который может произойти при тестировании на некоторых эмуляторах). Допустимый объект 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) {

            // Сделайте что-нибудь с ним, например запишите в него данные, загрузите и т. д.
            // writeFile(fileEntry, imgUri);
            console.log("получен файл: " + fileEntry.fullPath);
            // displayFileData(fileEntry.fullPath, "Файл скопирован в");

        }, onErrorCreateFile);

    }, onErrorResolveUrl);
}