chrome.documentScan

Beschreibung

Die Document Scan API wurde entwickelt, damit Apps und Erweiterungen den Inhalt von Papierdokumenten auf einem angeschlossenen Dokumentenscanner ansehen können.

Berechtigungen

Verfügbarkeit

Konzepte und Verwendung

Diese API unterstützt zwei Methoden zum Scannen von Dokumenten. Wenn Ihr Anwendungsfall mit einem beliebigen Scanner funktioniert und keine Konfigurationssteuerung erforderlich ist, verwenden Sie die scan()-Methode. Für komplexere Anwendungsfälle ist eine Kombination von Methoden erforderlich, die nur in Chrome 124 und höher unterstützt werden.

Einfaches Scannen

Für einfache Anwendungsfälle, die mit jedem Scanner funktionieren und keine Konfigurationssteuerung erfordern, rufen Sie scan() auf. Diese Methode verwendet ein ScanOptions-Objekt und gibt ein Promise zurück, das mit einem ScanResults-Objekt aufgelöst wird. Die Funktionen dieser Option sind auf die Anzahl der Scans und die MIME-Typen beschränkt, die vom Anrufer akzeptiert werden. Scans werden als URLs zurückgegeben, die in einem <img>-Tag für eine Benutzeroberfläche angezeigt werden können.

Komplexes Scannen

Komplexe Scans werden in drei Phasen durchgeführt, wie in diesem Abschnitt beschrieben. In dieser Übersicht werden nicht alle Methodenargumente oder alle Eigenschaften beschrieben, die in einer Antwort zurückgegeben werden. Es soll Ihnen lediglich eine allgemeine Anleitung zum Schreiben von Scanner-Code geben.

Discovery

1. Rufen Sie getScannerList() auf. Verfügbare Scanner werden in einem Promise zurückgegeben, das mit einem GetScannerListResponse aufgelöst wird.

   • Das Antwortobjekt enthält ein Array von ScannerInfo-Objekten.
   • Das Array kann mehrere Einträge für einen einzelnen Scanner enthalten, wenn dieser mehrere Protokolle oder Verbindungsmethoden unterstützt.

2. Wählen Sie einen Scanner aus dem zurückgegebenen Array aus und speichern Sie den Wert des Attributs scannerId.

   Verwenden Sie die Eigenschaften einzelner ScannerInfo-Objekte, um mehrere Objekte für denselben Scanner zu unterscheiden. Objekte vom selben Scanner haben denselben Wert für das Attribut deviceUuid. ScannerInfo enthält auch die Eigenschaft imageFormats, die ein Array mit unterstützten Bildtypen enthält.

Scannerkonfiguration

1. Rufen Sie openScanner() auf und übergeben Sie die gespeicherte Scanner-ID. Es wird ein Promise zurückgegeben, das mit einem OpenScannerResponse aufgelöst wird. Das Antwortobjekt enthält:

   • Eine scannerHandle-Property, die Sie speichern müssen.

   • Eine Options-Property mit scannerspezifischen Properties, die Sie festlegen müssen. Weitere Informationen finden Sie unter Scanneroptionen abrufen.

2. (Optional) Wenn der Nutzer Werte für Scanneroptionen angeben muss, erstellen Sie eine Benutzeroberfläche. Sie benötigen die Scanneroptionen aus dem vorherigen Schritt und müssen die vom Scanner bereitgestellten Optionsgruppen abrufen. Weitere Informationen finden Sie unter Benutzeroberfläche erstellen.

3. Erstellen Sie ein Array von OptionSetting-Objekten mit programmatischen oder vom Nutzer bereitgestellten Werten. Weitere Informationen finden Sie unter „Scanneroptionen festlegen“.

4. Übergeben Sie das Array von OptionSetting-Objekten an setOptions(), um Optionen für den Scanner festzulegen. Es wird ein Promise zurückgegeben, das mit einem SetOptionsResponse aufgelöst wird. Dieses Objekt enthält eine aktualisierte Version der Scanneroptionen, die in Schritt 1 der Scannerkonfiguration abgerufen wurden.

   Da sich durch das Ändern einer Option die Einschränkungen für eine andere Option ändern können, müssen Sie diese Schritte möglicherweise mehrmals wiederholen.

Scannen

1. Erstellen Sie ein StartScanOptions-Objekt und übergeben Sie es an startScan(). Es wird ein Promise zurückgegeben, das mit einem StartScanResponse aufgelöst wird. Die job-Eigenschaft ist ein Handle, das Sie verwenden, um entweder Scandaten zu lesen oder den Scan abzubrechen.

2. Übergeben Sie den Job-Handle an readScanData(). Es wird ein Promise zurückgegeben, das mit einem ReadScanDataResponse-Objekt aufgelöst wird. Wenn Daten erfolgreich gelesen wurden, ist das Attribut result gleich SUCCESS und das Attribut data enthält ein ArrayBuffer mit einem Teil des Scans. estimatedCompletion enthält einen geschätzten Prozentsatz der bisher bereitgestellten Gesamtdaten.

3. Wiederholen Sie den vorherigen Schritt, bis das Attribut result gleich EOF ist oder ein Fehler auftritt.

Wenn das Ende des Scans erreicht ist, rufen Sie closeScanner() mit dem in Schritt 3 gespeicherten Scanner-Handle auf. Es wird ein Promise zurückgegeben, das mit einem CloseScannerResponse aufgelöst wird. Wenn Sie cancelScan() jederzeit nach der Job-Erstellung aufrufen, wird der Scan beendet.

Antwortobjekte

Alle Methoden geben ein Promise zurück, das mit einem Antwortobjekt aufgelöst wird. Die meisten enthalten eine result-Eigenschaft, deren Wert ein Element von OperationResult ist. Einige Eigenschaften von Antwortobjekten enthalten nur dann Werte, wenn der Wert von result einen bestimmten Wert hat. Diese Beziehungen werden in der Referenz für jedes Antwortobjekt beschrieben.

OpenScannerResponse.scannerHandle hat beispielsweise nur einen Wert, wenn OpenScannerResponse.result gleich SUCCESS ist.

Scanneroptionen

Die Scanneroptionen variieren je nach Gerät erheblich. Daher ist es nicht möglich, Scanneroptionen direkt in der documentScan API zu berücksichtigen. Um dieses Problem zu umgehen, enthalten das OpenScannerResponse-Objekt (abgerufen mit openScanner()) und das SetOptionsResponse-Objekt (das Antwortobjekt für setOptions()) ein options-Attribut, das ein Objekt mit scannerspezifischen Optionen ist. Jede Option ist eine Schlüssel/Wert-Zuordnung, wobei der Schlüssel eine gerätespezifische Option und der Wert eine Instanz von ScannerOption ist.

Die Struktur sieht in der Regel so aus:

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

Stellen Sie sich beispielsweise einen Scanner vor, der die Optionen „Quelle“ und „Auflösung“ zurückgibt. Die Struktur des zurückgegebenen options-Objekts sieht in etwa so aus: Der Einfachheit halber werden nur teilweise ScannerOption-Antworten angezeigt.

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

Benutzeroberfläche erstellen

Die Verwendung dieser API ist zwar nicht erforderlich, aber es kann sinnvoll sein, dass ein Nutzer den Wert für eine bestimmte Option auswählt. Dafür ist eine Benutzeroberfläche erforderlich. Verwenden Sie das OpenScannerResponse (geöffnet über openScanner()), um die Optionen für den angeschlossenen Scanner wie im vorherigen Abschnitt beschrieben abzurufen.

Bei einigen Scannern werden Optionen gerätespezifisch gruppiert. Sie haben keine Auswirkungen auf das Verhalten von Optionen. Da diese Gruppen jedoch in der Produktdokumentation eines Scanners erwähnt werden können, sollten sie dem Nutzer angezeigt werden. Sie können diese Gruppen durch Aufrufen von getOptionGroups() abrufen. Dadurch wird ein Promise zurückgegeben, das mit einem GetOptionGroupsResponse-Objekt aufgelöst wird. Die groups-Eigenschaft enthält ein scannerspezifisches Array von Gruppen. Mithilfe der Informationen in diesen Gruppen können Sie die Optionen in der OpenScannerResponse für die Anzeige organisieren.

{
  scannerHandle: "123456",
  result: SUCCESS,
  groups: [
    {
      title: "Standard",
      members: [ "resolution", "mode", "source" ]
    }
  ]
}

Wie unter „Scannerkonfiguration“ beschrieben, kann sich das Ändern einer Option auf die Einschränkungen einer anderen Option auswirken. Aus diesem Grund enthält setOptionsResponse (das Antwortobjekt für