JS-виджет

JS-виджет Скапибары позволяет с легкостью реализовать функционал сканирования документов со сканнеров TWAIN/WIA/SANE в своих собственных веб-приложениях.

Установка виджета

Для установки виджета на сайт добавьте скрипт на страницу:

<script src="https://widget.scapy.ru/widget.js"></script>

При инициализации скрипт добавляет экземпляр класса Scapy в window.Scapy и генерирует на document событие scapyWidgetReady. Если ваш код может выполниться раньше загрузки виджета, дождитесь этого события:

if (window.Scapy) {
  init()
} else {
  document.addEventListener('scapyWidgetReady', init)
}

Использование

Процесс сканирования документов аналогичен процессу при использовании расширения для браузера.

В случае использования JS-виджета наличие расширения для браузера не требуется.

Методы виджета

Scapy.run(options)

Функция открывает форму сканирования.

Описание объекта options:

• target - элемент DOM в который будет добавлен виджет (по-умолчанию открывается в окне, которое монтируется в body)
• handleFiles - обработчик загрузки файлов
• handleClose - обработчик закрытия

Scapy.runForInput(options, input)

Функция открывает форму сканирования для конкретного input.

При загрузке результата сканирования эмитирует выбор файлов в input.

При использовании этой функции обработчики handleFiles и handleClose не требуются.

Описание объекта options:

• target - элемент DOM в который будет добавлен виджет (по-умолчанию открывается в окне, которое монтируется в body)

Scapy.requestFiles(options)

Функция открывает форму сканирования и возвращает Promise, который разрешается массивом отсканированных файлов после нажатия кнопки загрузки.

Если пользователь закрыл форму, не загрузив файлы, или форма уже открыта, Promise отклоняется ошибкой AbortError — так же, как отклоняется нативный выбор файла при отмене.

Описание объекта options:

• target - элемент DOM в который будет добавлен виджет (по-умолчанию открывается в окне, которое монтируется в body)

window.Scapy.requestFiles()
  .then((files) => {
    // Добавьте необходимые действия для массива с файлами - files
  })
  .catch(() => {
    // Сканирование отменили
  })

Scapy.isOpen()

Функция возвращает true, если форма сканирования открыта.

Scapy.close()

Функция закрывает форму сканирования.

Scapy.pushFilesToInput(input, files)

Функция эмитирует выбор файлов files в input.

Scapy.pushFilesToDropArea(area, files)

Функция эмитирует событие drop с файлами files на элементе area.

Используйте ее для загрузчиков, которые принимают файлы перетаскиванием и не содержат input с type="file".

Scapy.enableForAllFileInputs()

Функция включает перехват нажатий на все input с type="file".

При нажатии на любой input с type="file" будет открываться форма сканирования в окне.

Scapy.disableForAllFileInputs()

Функция отключает перехват нажатий на все input с type="file".

Отменяет действие функции Scapy.enableForAllFileInputs().

Адаптеры

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

Адаптер - это объект со следующими свойствами:

• name - название адаптера
• matches() - функция, возвращающая true, если текущая страница относится к системе адаптера
• enable() - функция включения адаптера (добавляет кнопку сканирования в интерфейс)
• disable() - функция отключения адаптера (убирает кнопку сканирования из интерфейса)

Scapy.registerAdapter(adapter)

Функция регистрирует адаптер adapter в виджете.

Scapy.hasAdapterForPage()

Функция возвращает true, если среди зарегистрированных адаптеров есть подходящий для текущей страницы.

Scapy.enableAdapters()

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

Scapy.disableAdapters()

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

Пример адаптера

const adapter = {
  name: 'my-crm',

  matches () {
    return !!document.querySelector('.my-crm-app')
  },

  enable () {
    const button = document.createElement('button')
    button.id = 'scapy-scan-button'
    button.textContent = 'Сканировать через Scapybara'
    button.addEventListener('click', () => {
      window.Scapy.requestFiles()
        .then((files) => {
          const input = document.querySelector('input[type="file"]')
          window.Scapy.pushFilesToInput(input, files)
        })
        .catch(() => {
          // Сканирование отменили
        })
    })

    document.querySelector('.my-crm-uploader').appendChild(button)
  },

  disable () {
    document.getElementById('scapy-scan-button')?.remove()
  }
}

if (window.Scapy) {
  window.Scapy.registerAdapter(adapter)
} else {
  document.addEventListener('scapyWidgetReady', () => window.Scapy.registerAdapter(adapter))
}

Пример использования на Vue.js

Установка скрипта

Добавьте следующий код в body или head в файл index.html:

<script src="https://widget.scapy.ru/widget.js"></script>

Использование в компонентах

Ниже приведен пример использования Scapybara в Vue.js.

При нажатии на кнопку будет открыто окно сканирования.

<template>
  <button @click="selectFile()">Сканировать</button>
</template>

<script>
export default {
  methods: {
    selectFile () {
      // Проверяем наличие экземпляра Scapy в window.
      if (!window.Scapy) {
        alert('Виджет сканирования не загружен!')
        return
      }

      window.Scapy.run({
        handleFiles: (files) => {
          // Добавьте необходимые действия для массива с файлами - files
          alert(`Загружено ${files.length} файла(ов)`)

          // Закрываем окно сканирования
          window.Scapy.close()
        },
        handleClose: () => {
          // Закрываем окно сканирования
          window.Scapy.close()
        }
      })
    }
  }
}
</script>