browser.documentScan

Opis

Interfejs Document Scan API umożliwia aplikacjom i rozszerzeniom wyświetlanie zawartości dokumentów papierowych na podłączonym skanerze dokumentów.

Uprawnienia

Dostępność

Pojęcia i zastosowanie

Ten interfejs API obsługuje 2 sposoby skanowania dokumentów. Jeśli Twój przypadek użycia może działać z dowolnym skanerem i nie wymaga kontroli konfiguracji, użyj metody scan(). Bardziej skomplikowane przypadki użycia wymagają połączenia metod, które są obsługiwane tylko w Chrome w wersji 124 i nowszych.

Proste skanowanie

W przypadku prostych zastosowań, czyli takich, które działają z dowolnym skanerem i nie wymagają kontroli konfiguracji, wywołaj scan(). Ta metoda przyjmuje obiekt ScanOptions i zwraca obietnicę, która jest realizowana za pomocą obiektu ScanResults. Możliwości tej opcji są ograniczone do liczby skanów i typów MIME, które będą akceptowane przez wywołującego. Skanowania są zwracane jako adresy URL do wyświetlania w tagu <img> w interfejsie.

Złożone skanowanie

Złożone skanowanie odbywa się w 3 fazach opisanych w tej sekcji. Ten zarys nie zawiera wszystkich argumentów metody ani wszystkich właściwości zwracanych w odpowiedzi. Ma ona jedynie stanowić ogólny przewodnik po pisaniu kodu skanera.

Odkrywanie

1. Zadzwoń pod numer getScannerList(). Dostępne skanery są zwracane w obietnicy, która jest realizowana za pomocą GetScannerListResponse.

   • Obiekt odpowiedzi zawiera tablicę obiektów ScannerInfo.
   • Tablica może zawierać wiele wpisów dla jednego skanera, jeśli obsługuje on wiele protokołów lub metod połączenia.

2. Wybierz skaner z zwróconej tablicy i zapisz wartość jego właściwości scannerId.

   Użyj właściwości poszczególnych obiektów ScannerInfo, aby odróżnić od siebie wiele obiektów tego samego skanera. Obiekty z tego samego skanera będą miały tę samą wartość właściwości deviceUuid. ScannerInfo zawiera też właściwość imageFormats, która zawiera tablicę obsługiwanych typów obrazów.

Konfiguracja skanera

1. Wywołaj funkcję openScanner(), przekazując zapisany identyfikator skanera. Zwraca obietnicę, która jest realizowana z wartością OpenScannerResponse. Obiekt odpowiedzi zawiera:

   • Właściwość scannerHandle, którą musisz zapisać.

   • Właściwość opcji zawierająca właściwości specyficzne dla skanera, które musisz ustawić. Więcej informacji znajdziesz w artykule Pobieranie opcji skanera.

2. (Opcjonalnie) Jeśli chcesz, aby użytkownik podał wartości opcji skanera, utwórz interfejs. Będziesz potrzebować opcji skanera podanych w poprzednim kroku oraz grup opcji udostępnionych przez skaner. Więcej informacji znajdziesz w artykule Tworzenie interfejsu użytkownika.

3. Utwórz tablicę obiektów OptionSetting, używając wartości podanych przez użytkownika lub uzyskanych programowo. Więcej informacji znajdziesz w artykule Ustawianie opcji skanera.

4. Przekaż tablicę obiektów OptionSetting do funkcji setOptions(), aby ustawić opcje skanera. Zwraca Promise, który jest rozwiązywany za pomocą obiektu SetOptionsResponse. Ten obiekt zawiera zaktualizowaną wersję opcji skanera pobranych w kroku 1 konfiguracji skanera.

   Zmiana jednej opcji może wpłynąć na ograniczenia innej opcji, dlatego może być konieczne powtórzenie tych kroków kilka razy.

Skanowanie

1. Utwórz obiekt StartScanOptions i przekaż go do funkcji startScan(). Zwraca obietnicę, która jest realizowana z wartością StartScanResponse. Jego właściwość job to uchwyt, którego użyjesz do odczytania danych skanowania lub anulowania skanowania.

2. Przekaż uchwyt zadania do funkcji readScanData(). Zwraca obiekt Promise, który jest rozwiązywany za pomocą obiektu ReadScanDataResponse. Jeśli dane zostały odczytane prawidłowo, właściwość result ma wartość SUCCESS, a właściwość data zawiera ArrayBuffer z częścią skanu. Pamiętaj, że estimatedCompletion zawiera szacunkowy odsetek łącznej ilości danych, które zostały dotychczas dostarczone.

3. Powtarzaj poprzedni krok, aż właściwość result będzie równa EOF lub wystąpi błąd.

Gdy skanowanie dobiegnie końca, wywołaj funkcję closeScanner() z uchwytem skanera zapisanym w kroku 3. Zwraca obietnicę, która jest spełniana z wartością CloseScannerResponse. Wywołanie funkcji Calling cancelScan() w dowolnym momencie po utworzeniu zadania spowoduje zakończenie skanowania.

Obiekty odpowiedzi

Wszystkie metody zwracają obiekt Promise, który jest rozwiązywany za pomocą obiektu odpowiedzi określonego typu. Większość z nich zawiera właściwość result, której wartość jest elementem zbioru OperationResult. Niektóre właściwości obiektów odpowiedzi nie będą zawierać wartości, chyba że wartość parametru result będzie określona. Te relacje są opisane w informacjach o poszczególnych obiektach odpowiedzi.

Na przykład parametr OpenScannerResponse.scannerHandle będzie miał wartość tylko wtedy, gdy parametr OpenScannerResponse.result będzie równy SUCCESS.

Opcje skanera

Opcje skanera różnią się znacznie w zależności od urządzenia. W związku z tym nie można odzwierciedlić opcji skanera bezpośrednio w interfejsie documentScan API. Aby to obejść, obiekty OpenScannerResponse (pobierany za pomocą openScanner()) i SetOptionsResponse (obiekt odpowiedzi dla setOptions()) zawierają właściwość options, która jest obiektem zawierającym opcje specyficzne dla skanera. Każda opcja to mapowanie klucz-wartość, w którym klucz jest opcją specyficzną dla urządzenia, a wartość jest instancją ScannerOption.

Struktura wygląda zwykle tak:

{
  "key1": { scannerOptionInstance }
  "key2": { scannerOptionInstance }
}

Wyobraź sobie skaner, który zwraca opcje o nazwach „source” i „resolution”. Struktura zwróconego obiektu options będzie podobna do tej z poniższego przykładu. Dla uproszczenia wyświetlane są tylko częściowe odpowiedzi ScannerOption.

{
  "source": {
    "name": "source",
    "type": OptionType.STRING,
...
},
  "resolution": {
    "name": "resolution",
    "type": OptionType.INT,
...