inglobal-qr v2.2.2

INGLOBAL-QR

JavaScript-модуль для сканирования QR-кодов на стороне клиента.

ОБЩЕЕ ОПИСАНИЕ

Сканирование QR-кодов осуществляется через считывание файла из DOM (file input) и передачу его содержимого в модуль @zxing/library в формате base64. На выходе формируется объект с результатами сканирования. При успешном сканировании из свойства text данного объекта можно получить текстовое содержимое отсканированного QR-кода.

ПОДКЛЮЧЕНИЕ

Работает и как js-модуль, и как простой js-скрипт, скомпилированный в es5. Файл простого js-скрипта находится здесь: examples/es5/inglobal-qr_browser.min.js. Если он отсутствует, в терминале перейдите в папку проекта и выполните команду npm run prepublishOnly, которая должна скомпилировать файл и положить его по этому пути. В случае использования скрипта examples/es5/inglobal-qr_browser.min.js и необходимости поддерживать Internet Explorer, необходимо также подключить файл id.min.js, который содержит нужный полифилл. Если требуется отладка, также можно выполнить команду npm run buildDev.

В обоих случаях для использования методов модуля необходимо создать экземпляр объекта:

var qr = new InglobalQR(inputFile);

где inputFile - это объект File, полученный из инпута, например:

var inputFile = document.querySelector('input[name="photo"]').files[0];

ОСНОВНЫЕ МЕТОДЫ

КОНСТРУКТОР

создание экземпляра объекта
принимает 2 параметра

inputFile object

Объект типа File, извлекаемый из объекта FileList. Является необязательным параметром при работе с камерой.

defaultTimeout number

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

returnType number | string

Тип ответа, возвращаемого методами объекта. Если передано 1 или "promise", устанавливается тип ответа Promise, если передано 2 или "objectInstance", устанавливается тип ответа - текущий экземпляр объекта InglobalQR. Если передано любое другое значение, оно игнорируется. По умолчанию тип возвращаемого ответа - Promise.

setReturnType()

задать тип ответа, возвращаемого методами объекта
принимает 1 параметр
возвращает Promise c результатами

returnType number | string

Тип ответа, возвращаемого методами объекта. Если передано 1 или "promise", устанавливается тип ответа Promise, если передано 2 или "objectInstance", устанавливается тип ответа - текущий экземпляр объекта InglobalQR.

setInputFile()

указать объект File с картинкой, которая будет использоваться для сканирования QR-кода
принимает 1 параметр
возвращает Promise c результатами

inputFile object

Объект типа File, извлекаемый из объекта FileList.

setDefaultTimeout()

указать объект File с картинкой, которая будет использоваться для сканирования QR-кода
принимает 1 параметр
возвращает Promise c результатами

timeout number

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

scanImage()

сканирование QR-кода в изображении, которое было передано в конструктор
принимает 1 параметр
возвращает Promise c результатами

failureTimeout number

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

getVideoDevices()

Получить список доступных видео-устройств.
не принимает параметры
возвращает Promise c результатами

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

decodeFromCamera()

Распознать QR-код с помощью камеры.
принимает 2 параметра
возвращает Promise c результатами

deviceId string

ID видео-устройства, полученный с помощью метода getVideoDevices. Может быть undefined, в таком случае считывание произойдёт с одного из доступных устройств, предпочтение отдаётся главной камере.

videoElement string | object

Коллбек, который устанавливается на указанное событие (в первом параметре коллбека приходит объект с результатом выполнения операции) Контейнер на странице, в котором будет отображаться видео во время распознавания. Можно передать или id элемента, или HTMLVideoElement. Если undefined, отображения видео не будет.

resetCamera()

Сбросить считыватель до первоначального состояния. Отменяет любое запущенное сканирование с камеры.
принимает 2 параметра
возвращает текущий экземпляр объекта InglobalQR

scanImageViaApi()

Сканирование QR-кода в изображении, которое было передано в конструктор, с использованием внешнего API (выполняется POST-запрос на внешний сервис).
принимает 2 параметра
возвращает Promise c результатами

failureTimeout number

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

apiUrl string

URL, по которому будет отправляться POST-запрос для распознавания QR-кода. На этот URL будет отправлен POST-запрос в формате multipart/form-data с параметром image, который будет содержать в себе переданную в объект картинку с QR-кодом (inputFile). Для корректной работы метода необходимо, чтобы указанный URL возвращал в ответе JSON с полем success типа boolean (результат распознавания). Тем не менее, теоретически, можно использовать URL, возвращающий JSON без поля success или с этим полем, но другим типом данных, но в таком случае не будет генерироваться событие api_scan_recognized, а при использовании промисов будет происходить reject, - любой результат, где нет поля success или где это поле не равно true (строгое сравнение), сгенерирует событие api_scan_not_recognized (или reject в случае с промисами). Обратите внимание, что если отработает таймаут, то тоже будет сгенерировано это событие. По умолчанию в качестве внешнего API используется URL https://4002.ru:8443/scan_image, который возвращает корректный тип ответа, и при успехе генерируется событие api_scan_recognized.

on(), once()

(см. документацию по EventEmitter)
установка коллбека на одно из событий, генерируемых объектом
принимает 2 параметра
возвращает текущий экземпляр объекта InglobalQR

eventName string

Название события, на которое устанавливается коллбек.

callback function

Коллбек, который устанавливается на указанное событие (в первом параметре коллбека приходит объект с результатом выполнения операции)

СОБЫТИЯ, ГЕНЕРИРУЕМЫЕ ОБЪЕКТОМ

scanImage

scan_recognized

Генерируется методом scanImage сразу, когда QR-код успешно распознан

scan_not_recognized

Генерируется методом scanImage, если обработчику не удалось распознать QR-код (либо сразу, либо по истечении таймаута defaultTimeout или failureTimeout)

scan_error

Генерируется методом scanImage при иных ошибках в ходе распознания QR-кода (ошибки скрипта)

getVideoDevices

video_error

Генерируется методом getVideoDevices при неудачной попытке получить список видео-устройств, либо если возвращён пустой массив (т.е. устройства не подключены)

video_devices

Генерируется методом getVideoDevices при успешном получении массива видео-устройств

decodeFromCamera

not_allowed_error

Генерируется методом decodeFromCamera в случае отклонения пользователем доступа к камере, а также если доступ к камере блокируется каким-либо ПО

decode_error

Генерируется методом decodeFromCamera при иных ошибках в ходе распознания QR-кода через камеру

decode_result

Генерируется методом decodeFromCamera сразу, когда QR-код успешно распознан через камеру

scanImageViaApi

api_scan_recognized

Генерируется методом scanImageViaApi сразу после получения ответа от API с успешно распознанным кодом

api_scan_not_recognized

Генерируется методом scanImageViaApi сразу после получения ответа от API о том, что QR-код распознать не удалось (либо сразу, либо по истечении таймаута defaultTimeout или failureTimeout)

api_scan_invalid_json

Генерируется методом scanImageViaApi сразу после получения ответа от API с недействительной JSON-строкой

api_scan_error

Генерируется методом scanImageViaApi при иных ошибках в ходе распознания QR-кода через API

ПРИМЕР ИСПОЛЬЗОВАНИЯ СОБЫТИЙ

Для отлавливания событий, необходимо воспользоваться методом on объекта InglobalQR.

var qr = new InglobalQR();

qr.setInputFile(document.querySelector('input[name="photo"]').files[0])
  .setReturnType(2)
  .scanImageViaApi(30000, "https://4002.ru:8443/scan_image")
  .once('api_scan_recognized', function(response) {
      console.log('Изображение распознано', response);
  })
  .once('api_scan_not_recognized', function(response) {
      console.log('Изображение не распознано. QR-код не найден', response);
  })
  .once('api_scan_invalid_json', function(response) {
      console.log('Изображение не распознано. Невалидный JSON', response);
  })
  .once('api_scan_error', function(error) {
      console.log('Изображение не распознано. Ошибка распознавания', error);
  });

Аналогично можно обращаться к другим методам и ставить обработчики на генерируемые этими методами события.

ПРИМЕР ИСПОЛЬЗОВАНИЯ В КАЧЕСТВЕ МОДУЛЯ

Обычная работа с объектом Promise.

import {InglobalQR} from 'inglobal-qr';

(async()=>{
    let result = null;
    
    try {
        let qr = new InglobalQR(document.querySelector('input[name="photo"]').files[0]);
        result = await qr.scanImageViaApi();

        console.log('success');
    } catch(err) {
        result = err;
        
        console.log('failed');
    }

    // выводит результат по завершении операции
    console.log(result);
})();