browser.documentScan

Wichtig: Diese API funktioniert nur unter ChromeOS.

Beschreibung

Mit der chrome.documentScan API können Sie Bilder von angeschlossenen Dokumentenscannern finden und abrufen.

Die Document Scan API wurde entwickelt, um Apps und Erweiterungen zu ermöglichen, den Inhalt von Papierdokumenten auf einem angeschlossenen Dokumentenscanner anzuzeigen.

Berechtigungen

documentScan

Verfügbarkeit

Chrome 44 oder höher browser.* seit Chrome 148 Nur ChromeOS

Die Verfügbarkeit für später hinzugefügte API-Mitglieder wird bei diesen Mitgliedern angezeigt.

Konzepte und Verwendung

Diese API unterstützt zwei Methoden zum Scannen von Dokumenten. Wenn Ihr Anwendungsfall mit einem beliebigen Scanner funktioniert und keine Kontrolle über die Konfiguration erfordert, verwenden Sie die Methode scan(). Komplexere Anwendungsfälle erfordern eine Kombination von Methoden, die erst ab Chrome 124 unterstützt werden.

Einfaches Scannen

Für einfache Anwendungsfälle, d. h. solche, 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 Aufrufer akzeptiert werden. Scans werden als URLs zurückgegeben, die in einem <img>-Tag für eine Benutzeroberfläche angezeigt werden.

Komplexes Scannen

Komplexe Scans werden in drei Phasen durchgeführt, wie in diesem Abschnitt beschrieben. In dieser Übersicht werden nicht alle Methodenargumente oder alle in einer Antwort zurückgegebenen Attribute beschrieben. Sie soll Ihnen lediglich eine allgemeine Anleitung zum Schreiben von Scannercode geben.

Hinweis: Wenn Sie openScanner(), getScannerList() oder startScan() mehrmals aufrufen, werden Vorgänge abgebrochen, die durch vorherige Aufrufe dieser Methoden initiiert wurden. Weitere Informationen finden Sie in den Beschreibungen dieser Methoden.

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 Attribute einzelner ScannerInfo-Objekte, um zwischen mehreren Objekten für denselben Scanner zu unterscheiden. Objekte desselben Scanners haben denselben Wert für das Attribut deviceUuid. ScannerInfo enthält auch ein imageFormats-Attribut mit einem Array unterstützter Bildtypen.

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.

   • Ein options-Attribut, das scannerspezifische Attribute enthält, 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. Das Attribut job ist ein Handle, mit dem Sie entweder Scandaten lesen oder den Scan abbrechen können.

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

   Hinweis: Wenn result den Wert SUCCESS hat, aber data leer ist, warten Sie kurz, bevor Sie readScanData() noch einmal aufrufen.

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() nach dem Erstellen des Jobs aufrufen, wird der Scan beendet.

Antwortobjekte

Alle Methoden geben ein Promise zurück, das mit einem Antwortobjekt aufgelöst wird. Die meisten davon enthalten ein result-Attribut, dessen Wert ein Mitglied von OperationResult ist. Einige Attribute 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 dann 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 widerzuspiegeln. Um dieses Problem zu umgehen, enthalten OpenScannerResponse (abgerufen mit openScanner()) und SetOptionsResponse (das Antwortobjekt für setOptions()) ein options-Attribut, das ein Objekt mit scannerspezifischen Optionen ist. Jede Option ist eine Schlüssel/Wert-Zuordnung, bei der der Schlüssel eine gerätespezifische Option und der Wert eine Instanz von ScannerOption ist.

Die Struktur sieht im Allgemeinen so aus:

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

Stellen Sie sich beispielsweise einen Scanner vor, der Optionen mit den Namen „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

Für die Verwendung dieser API ist es zwar nicht erforderlich, aber Sie können einen Nutzer den Wert für eine bestimmte Option auswählen lassen. Dafür ist eine Benutzeroberfläche erforderlich. Verwenden Sie OpenScannerResponse (geöffnet von openScanner()), um die Optionen für den angeschlossenen Scanner abzurufen, wie im vorherigen Abschnitt beschrieben.

Bei einigen Scannern werden die Optionen gerätespezifisch gruppiert. Sie haben keinen Einfluss auf das Verhalten der Optionen, aber da diese Gruppen möglicherweise in der Produktdokumentation eines Scanners erwähnt werden, 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. Das Attribut groups enthält ein scannerspezifisches Array von Gruppen. Verwenden Sie die Informationen in diesen Gruppen, um die Optionen in der OpenScannerResponse für die Anzeige zu organisieren.

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

Wie unter „Scannerkonfiguration“ beschrieben, kann das Ändern einer Option die Einschränkungen für eine andere Option ändern. Aus diesem Grund enthält setOptionsResponse (das Antwortobjekt für setOptions()) ein weiteres options-Attribut. Verwenden Sie diese, um die Benutzeroberfläche zu aktualisieren. Wiederholen Sie den Vorgang nach Bedarf, bis alle Optionen festgelegt sind.

Scanneroptionen festlegen

Legen Sie Scanneroptionen fest, indem Sie ein Array von OptionSetting-Objekten an setOptions() übergeben. Ein Beispiel finden Sie im Abschnitt Eine Seite im Letter-Format scannen.

Beispiele

Seite als Blob abrufen

In diesem Beispiel wird gezeigt, wie Sie eine Seite vom Scanner als Blob abrufen und startScan() und readScanData() mit dem Wert von OperationResult verwenden.

async function pageAsBlob(handle) {
  let response = await browser.documentScan.startScan(
      handle, {format: "image/jpeg"});
  if (response.result != browser.documentScan.OperationResult.SUCCESS) {
    return null;
  }
  const job = response.job;

  let imgParts = [];
  response = await browser.documentScan.readScanData(job);
  while (response.result == browser.documentScan.OperationResult.SUCCESS) {
    if (response.data && response.data.byteLength > 0) {
        imgParts.push(response.data);
    } else {
      // Delay so hardware can make progress.
      await new Promise(r => setTimeout(r, 100));
    }
    response = await browser.documentScan.readScanData(job);
  }
  if (response.result != browser.documentScan.OperationResult.EOF) {
    return null;
  }
  if (response.data && response.data.byteLength > 0) {
    imgParts.push(response.data);
  }
  return new Blob(imgParts, { type: "image/jpeg" });
}

Eine Seite im Letter-Format scannen

In diesem Beispiel wird gezeigt, wie Sie einen Scanner auswählen, seine Optionen festlegen und ihn öffnen. Anschließend wird der Inhalt einer einzelnen Seite abgerufen und der Scanner geschlossen. In diesem Prozess wird die Verwendung von getScannerList(), openScanner(), setOptions() und closeScanner() veranschaulicht. Der Inhalt der Seite wird durch Aufrufen der Funktion pageAsBlob() aus dem vorherigen Beispiel abgerufen.

async function scan() {
    let response = await browser.documentScan.getScannerList({ secure: true });
    let scanner = await browser.documentScan.openScanner(
        response.scanners[0].scannerId);
    const handle = scanner.scannerHandle;

    let options = [];
    for (source of scanner.options["source"].constraint.list) {
        if (source.includes("ADF")) {
            options.push({
                name: "source",
                type: browser.documentScan.OptionType.STRING,
                value: { value: source }
            });
            break;
        }
    }
    options.push({
        name: "tl-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-x",
        type: browser.documentScan.OptionType.FIXED,
        value: 215.9  // 8.5" in mm
    });
    options.push({
        name: "tl-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-y",
        type: browser.documentScan.OptionType.FIXED,
        value: 279.4  // 11" in mm
    });
    response = await browser.documentScan.setOptions(handle, options);

    let imgBlob = await pageAsBlob(handle);
    if (imgBlob != null) {
        // Insert imgBlob into DOM, save to disk, etc
    }
    await browser.documentScan.closeScanner(handle);
}

Konfiguration anzeigen

Wie bereits erwähnt, müssen Sie zusätzlich zu den Scanneroptionen, die von einem Aufruf von openScanner() zurückgegeben werden, getOptionGroups() aufrufen, um einem Nutzer die Konfigurationsoptionen eines Scanners anzuzeigen. So können Nutzern in vom Hersteller definierten Gruppen Optionen angezeigt werden. In diesem Beispiel wird gezeigt, wie das geht.

async function showConfig() {
  let response = await browser.documentScan.getScannerList({ secure: true });
  let scanner = await browser.documentScan.openScanner(
      response.scanners[0].scannerId);
  let groups = await browser.documentScan.getOptionGroups(scanner.scannerHandle);

  for (const group of groups.groups) {
    console.log("=== " + group.title + " ===");
    for (const member of group.members) {
      const option = scanner.options[member];
      if (option.isActive) {
        console.log("  " + option.name + " = " + option.value);
      } else {
        console.log("  " + option.name + " is inactive");
      }
    }
  }
}

Typen

CancelScanResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Job

  String

  Stellt dasselbe Job-Handle bereit, das an cancelScan() übergeben wurde.

• Ergebnis

  OperationResult

  Das Ergebnis des Abbruchs des Scans durch das Backend. Wenn das Ergebnis OperationResult.SUCCESS oder OperationResult.CANCELLED lautet, wurde der Scan abgebrochen und der Scanner ist bereit, einen neuen Scan zu starten. Wenn das Ergebnis OperationResult.DEVICE_BUSY ist, verarbeitet der Scanner die angeforderte Stornierung noch. Der Aufrufer sollte kurz warten und die Anfrage dann noch einmal senden. Andere Ergebniswerte weisen auf einen dauerhaften Fehler hin, der nicht wiederholt werden sollte.

CloseScannerResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Ergebnis

  OperationResult

  Das Ergebnis des Schließens des Scanners. Auch wenn dieser Wert nicht SUCCESS ist, ist das Handle ungültig und sollte nicht für weitere Vorgänge verwendet werden.

• scannerHandle

  String

  Dasselbe Scanner-Handle, das an closeScanner übergeben wurde.

Configurability

Chrome 125 und höher browser.* seit Chrome 148

Wie eine Option geändert werden kann.

Enum

"NOT_CONFIGURABLE"
Die Option ist schreibgeschützt.

"SOFTWARE_CONFIGURABLE"
Die Option kann in der Software festgelegt werden.

"HARDWARE_CONFIGURABLE"
Die Option kann vom Nutzer durch Umschalten oder Drücken einer Taste am Scanner festgelegt werden.

ConnectionType

Chrome 125 und höher browser.* seit Chrome 148

Gibt an, wie der Scanner mit dem Computer verbunden ist.

Enum

"UNSPECIFIED"

USB

"NETWORK"

ConstraintType

Chrome 125 und höher browser.* seit Chrome 148

Der Datentyp der Einschränkung, dargestellt durch ein OptionConstraint.

Enum

"INT_RANGE"
Die Einschränkung für einen Bereich von OptionType.INT-Werten. Die Attribute min, max und quant von OptionConstraint werden auf long gesetzt und das Attribut list wird nicht festgelegt.

"FIXED_RANGE"
Die Einschränkung für einen Bereich von OptionType.FIXED-Werten. Die Attribute min, max und quant von OptionConstraint sind double und das Attribut list ist nicht festgelegt.

"INT_LIST"
Die Einschränkung für eine bestimmte Liste von OptionType.INT-Werten. Das Attribut OptionConstraint.list enthält long Werte und die anderen Attribute sind nicht festgelegt.

"FIXED_LIST"
Die Einschränkung für eine bestimmte Liste von OptionType.FIXED-Werten. Das Attribut OptionConstraint.list enthält double Werte und die anderen Attribute sind nicht festgelegt.

"STRING_LIST"
Die Einschränkung für eine bestimmte Liste von OptionType.STRING-Werten. Das Attribut OptionConstraint.list enthält DOMString Werte und die anderen Attribute sind nicht festgelegt.

DeviceFilter

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• lokal

  Boolesch optional

  Nur Scanner zurückgeben, die direkt mit dem Computer verbunden sind.

• sicher

  Boolesch optional

  Geben Sie nur Scanner zurück, die eine sichere Übertragung wie USB oder TLS verwenden.

GetOptionGroupsResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Gruppen

  OptionGroup[] optional

  Wenn result den Wert SUCCESS hat, wird eine Liste der Optionsgruppen in der vom Scannertreiber bereitgestellten Reihenfolge angezeigt.

• Ergebnis

  OperationResult

  Das Ergebnis des Abrufs der Optionsgruppen. Wenn der Wert SUCCESS ist, wird das Attribut groups ausgefüllt.

• scannerHandle

  String

  Dasselbe Scanner-Handle, das an getOptionGroups übergeben wurde.

GetScannerListResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Ergebnis

  OperationResult

  Das Ergebnis der Aufzählung. Beachten Sie, dass Teilergebnisse zurückgegeben werden können, auch wenn dies auf einen Fehler hinweist.

• Scanner

  ScannerInfo[]

  Eine möglicherweise leere Liste von Scannern, die mit dem angegebenen DeviceFilter übereinstimmen.

OpenScannerResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Optionen

  Objekt optional

  Wenn result den Wert SUCCESS hat, wird eine Schlüssel/Wert-Zuordnung bereitgestellt, bei der der Schlüssel eine gerätespezifische Option und der Wert eine Instanz von ScannerOption ist.

• Ergebnis

  OperationResult

  Das Ergebnis des Öffnens des Scanners. Wenn der Wert SUCCESS ist, werden die Properties scannerHandle und options ausgefüllt.

• scannerHandle

  String optional

  Wenn result den Wert SUCCESS hat, ein Handle für den Scanner, das für weitere Vorgänge verwendet werden kann.

• scannerId

  String

  Die an openScanner() übergebene Scanner-ID.

OperationResult

Chrome 125 und höher browser.* seit Chrome 148

Ein Enum, das das Ergebnis jedes Vorgangs angibt.

Enum

UNKNOWN
Ein unbekannter oder allgemeiner Fehler ist aufgetreten.

"SUCCESS"
Der Vorgang war erfolgreich.

"UNSUPPORTED"
Der Vorgang wird nicht unterstützt.

"CANCELLED"
Der Vorgang wurde abgebrochen.

"DEVICE_BUSY"
Das Gerät ist beschäftigt.

"INVALID"
Entweder die Daten oder ein an die Methode übergebenes Argument sind ungültig.

"WRONG_TYPE"
Der angegebene Wert hat den falschen Datentyp für die zugrunde liegende Option.

"EOF"
Es sind keine weiteren Daten verfügbar.

"ADF_JAMMED"
Der Dokumenteneinzug ist blockiert.

"ADF_EMPTY"
Der Dokumenteneinzug ist leer.

"COVER_OPEN"
Die Abdeckung des Flachbettscanners ist offen.

„IO_ERROR“
Bei der Kommunikation mit dem Gerät ist ein Fehler aufgetreten.

"ACCESS_DENIED"
Das Gerät erfordert eine Authentifizierung.

"NO_MEMORY"
Auf dem Chromebook ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.

„UNREACHABLE“
Das Gerät ist nicht erreichbar.

"MISSING"
Das Gerät ist nicht verbunden.

"INTERNAL_ERROR"
Es ist ein Fehler aufgetreten, der nicht von der aufrufenden Anwendung verursacht wurde.

OptionConstraint

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• list

  string[] | number[] optional

• max

  number optional

• Min.

  number optional

• quant

  number optional

• Typ

  ConstraintType

OptionGroup

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Mitglieder

  String[]

  Ein Array von Optionsnamen in der vom Treiber bereitgestellten Reihenfolge.

• Titel

  String

  Stellt einen druckbaren Titel bereit, z. B. „Geometrieoptionen“.

OptionSetting

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• name

  String

  Gibt den Namen der festzulegenden Option an.

• Typ

  OptionType

  Gibt den Datentyp der Option an. Der angeforderte Datentyp muss mit dem tatsächlichen Datentyp der zugrunde liegenden Option übereinstimmen.

• Wert

  string | number | boolean | number[] optional

  Gibt den festzulegenden Wert an. Lassen Sie das Feld leer, um die automatische Einstellung für Optionen anzufordern, für die autoSettable aktiviert ist. Der für value angegebene Datentyp muss mit type übereinstimmen.

OptionType

Chrome 125 und höher browser.* seit Chrome 148

Der Datentyp einer Option.

Enum

"UNKNOWN"
Der Datentyp der Option ist unbekannt. Das Attribut value wird aufgehoben.

"BOOL"
Die Property value ist truefalse.

"INT"
Eine vorzeichenbehaftete 32-Bit-Ganzzahl. Das Attribut value ist „long“ oder „long[]“, je nachdem, ob die Option mehr als einen Wert annimmt.

"FIXED"
Ein Double im Bereich von -32768 bis 32767,9999 mit einer Auflösung von 1/65535. Das Attribut value ist „double“ oder „double[]“, je nachdem, ob die Option mehr als einen Wert annimmt. Double-Werte, die nicht genau dargestellt werden können, werden auf den verfügbaren Bereich und die verfügbare Genauigkeit gerundet.

"STRING"
Eine Folge beliebiger Bytes außer NUL ('\0'). Das Attribut value ist ein DOMString.

"BUTTON"
Eine Option dieses Typs hat keinen Wert. Stattdessen wird durch das Festlegen einer Option dieses Typs ein optionsspezifischer Nebeneffekt im Scannertreiber verursacht. Eine Schaltflächenoption könnte beispielsweise von einem Scannertreiber verwendet werden, um Standardwerte auszuwählen oder einen automatischen Dokumenteneinzug anzuweisen, zum nächsten Blatt Papier zu wechseln.

"GROUP"
Gruppierungsoption. Kein Wert. Dies ist aus Kompatibilitätsgründen enthalten, wird aber normalerweise nicht in ScannerOption-Werten zurückgegeben. Verwenden Sie getOptionGroups(), um die Liste der Gruppen mit ihren Mitgliedsoptionen abzurufen.

OptionUnit

Chrome 125 und höher browser.* seit Chrome 148

Gibt den Datentyp für ScannerOption.unit an.

Enum

"UNITLESS"
Der Wert ist eine Zahl ohne Einheit. Das kann beispielsweise ein Schwellenwert sein.

"PIXEL"
Der Wert ist eine Anzahl von Pixeln, z. B. Scandimensionen.

"BIT"
Der Wert ist die Anzahl der Bits, z. B. die Farbtiefe.

"MM"
Der Wert wird in Millimetern gemessen, z. B. Scanabmessungen.

„DPI“
Der Wert wird in Punkten pro Zoll gemessen, z. B. die Auflösung.

"PERCENT"
Der Wert ist ein Prozentsatz, z. B. die Helligkeit.

"MICROSECOND"
Der Wert wird in Mikrosekunden gemessen, z. B. die Belichtungszeit.

ReadScanDataResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Daten

  ArrayBuffer optional

  Wenn result den Wert SUCCESS hat, enthält es den nächsten Block gescannter Bilddaten. Wenn result den Wert EOF hat, enthält es den letzten Block der gescannten Bilddaten.

• estimatedCompletion

  number optional

  Wenn result den Wert SUCCESS hat, wird ein Schätzwert für den Anteil der bisher gelieferten Scandaten im Bereich von 0 bis 100 angegeben.

• Job

  String

  Stellt das Job-Handle bereit, das an readScanData() übergeben wurde.

• Ergebnis

  OperationResult

  Das Ergebnis des Lesens von Daten. Wenn der Wert SUCCESS ist, enthält data den nächsten (möglicherweise leeren) Block von Bilddaten, der zum Lesen bereit ist. Wenn der Wert EOF ist, enthält data den letzten Block von Bilddaten.

ScannerInfo

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• connectionType

  ConnectionType

  Gibt an, wie der Scanner mit dem Computer verbunden ist.

• deviceUuid

  String

  Zum Abgleich mit anderen ScannerInfo-Einträgen, die auf dasselbe physische Gerät verweisen.

• imageFormats

  String[]

  Ein Array von MIME-Typen, die für zurückgegebene Scans angefordert werden können.

• Hersteller

  String

  Der Hersteller des Scanners.

• Modell

  String

  Das Scannermodell, falls verfügbar, oder eine allgemeine Beschreibung.

• name

  String

  Ein menschenlesbarer Name für den Scanner, der in der Benutzeroberfläche angezeigt werden soll.

• protocolType

  String

  Eine menschenlesbare Beschreibung des Protokolls oder Treibers, der für den Zugriff auf den Scanner verwendet wird, z. B. Mopria, WSD oder epsonds. Das ist vor allem dann nützlich, wenn ein Nutzer zwischen Protokollen wählen kann, falls ein Gerät mehrere Protokolle unterstützt.

• scannerId

  String

  Die ID eines bestimmten Scanners.

• sicher

  boolean

  Wenn „true“, kann die Übertragung der Scannerverbindung nicht von einem passiven Listener wie TLS oder USB abgefangen werden.

ScannerOption

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Konfigurierbarkeit

  Konfigurierbarkeit

  Gibt an, ob und wie die Option geändert werden kann.

• Einschränkung

  OptionConstraint optional

  Definiert OptionConstraint für die aktuelle Scanneroption.

• Beschreibung

  String

  Eine längere Beschreibung der Option.

• isActive (Aktiv)

  boolean

  Gibt an, dass die Option aktiv ist und festgelegt oder abgerufen werden kann. Wenn „false“, wird das Attribut value nicht festgelegt.

• isAdvanced

  boolean

  Gibt an, dass diese Option standardmäßig nicht in der Benutzeroberfläche angezeigt werden soll.

• isAutoSettable

  boolean

  Kann automatisch vom Scannertreiber festgelegt werden.

• isDetectable

  boolean

  Gibt an, dass diese Option von Software erkannt werden kann.

• isEmulated

  boolean

  Wird vom Scannertreiber emuliert, wenn „true“.

• name

  String

  Der Optionsname mit ASCII-Kleinbuchstaben, Ziffern und Bindestrichen. Diakritische Zeichen sind nicht zulässig.

• Titel

  String

  Ein druckbarer einzeiliger Titel.

• Typ

  OptionType

  Der Datentyp, der in der Property value enthalten ist und zum Festlegen dieser Option erforderlich ist.

• Einheit

  OptionUnit

  Die Maßeinheit für diese Option.

• Wert

  string | number | boolean | number[] optional

  Der aktuelle Wert der Option, falls relevant. Der Datentyp dieser Property muss mit dem in type angegebenen Datentyp übereinstimmen.

ScanOptions

Attribute

• maxImages

  number optional

  Die Anzahl der zulässigen gescannten Bilder. Der Standardwert ist 1.

• mimeTypes

  string[] optional

  Die MIME-Typen, die vom Aufrufer akzeptiert werden.

ScanResults

Attribute

• dataUrls

  String[]

  Ein Array von Datenbild-URLs in einem Format, das als „src“-Wert an ein Bild-Tag übergeben werden kann.

• mimeType

  String

  Der MIME-Typ des dataUrls.

SetOptionResult

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• name

  String

  Gibt den Namen der Option an, die festgelegt wurde.

• Ergebnis

  OperationResult

  Gibt das Ergebnis der Einstellung der Option an.

SetOptionsResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Optionen

  Objekt optional

  Eine aktualisierte Schlüssel/Wert-Zuordnung von Optionsnamen zu ScannerOption-Werten, die die neue Konfiguration enthalten, nachdem versucht wurde, alle angegebenen Optionen festzulegen. Diese hat dieselbe Struktur wie das Attribut options in OpenScannerResponse.

  Diese Property wird auch dann festgelegt, wenn einige Optionen nicht erfolgreich festgelegt wurden. Sie wird jedoch aufgehoben, wenn die aktualisierte Konfiguration nicht abgerufen werden kann (z. B. wenn der Scanner während des Scannens getrennt wird).

• Ergebnisse

  SetOptionResult[]

  Ein Array von Ergebnissen, jeweils eines für jeden übergebenen OptionSetting.

• scannerHandle

  String

  Stellt das Scanner-Handle bereit, das an setOptions() übergeben wurde.

StartScanOptions

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Format

  String

  Gibt den MIME-Typ an, in dem gescannte Daten zurückgegeben werden sollen.

• maxReadSize

  number optional

  Wenn ein Wert ungleich null angegeben wird, wird die maximale Anzahl der gescannten Bytes, die in einer einzelnen readScanData-Antwort zurückgegeben werden, auf diesen Wert begrenzt. Der kleinste zulässige Wert ist 32768 (32 KB). Wenn dieses Attribut nicht angegeben ist, kann die Größe eines zurückgegebenen Blocks so groß sein wie das gesamte gescannte Bild.

StartScanResponse

Chrome 125 und höher browser.* seit Chrome 148

Attribute

• Job

  String optional

  Wenn result den Wert SUCCESS hat, wird ein Handle bereitgestellt, mit dem Scandaten gelesen oder der Job abgebrochen werden kann.

• Ergebnis

  OperationResult

  Das Ergebnis des Startens eines Scans. Wenn der Wert SUCCESS ist, wird das Attribut job ausgefüllt.

• scannerHandle

  String

  Stellt dasselbe Scanner-Handle bereit, das an startScan() übergeben wurde.

Methoden

cancelScan()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.cancelScan(
  job: string,
): Promise<CancelScanResponse>

Bricht einen gestarteten Scan ab und gibt ein Promise zurück, das mit einem CancelScanResponse-Objekt aufgelöst wird. Wenn ein Callback verwendet wird, wird das Objekt stattdessen an diesen übergeben.

Parameter

• Job

  String

  Das Handle eines aktiven Scan-Jobs, das zuvor von einem Aufruf von startScan zurückgegeben wurde.

Ausgabe

• Promise<CancelScanResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird.

closeScanner()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.closeScanner(
  scannerHandle: string,
): Promise<CloseScannerResponse>

Schließt den Scanner mit dem übergebenen Handle und gibt ein Promise zurück, das mit einem CloseScannerResponse-Objekt aufgelöst wird. Wenn ein Callback verwendet wird, wird das Objekt stattdessen an diesen übergeben. Auch wenn die Antwort nicht erfolgreich ist, wird das angegebene Handle ungültig und sollte nicht für weitere Vorgänge verwendet werden.

Parameter

• scannerHandle

  String

  Gibt das Handle eines offenen Scanners an, das zuvor von einem Aufruf von openScanner zurückgegeben wurde.

Ausgabe

• Promise<CloseScannerResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird.

getOptionGroups()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.getOptionGroups(
  scannerHandle: string,
): Promise<GetOptionGroupsResponse>

Ruft die Gruppennamen und Mitgliederoptionen von einem Scanner ab, der zuvor von openScanner geöffnet wurde. Diese Methode gibt ein Promise zurück, das mit einem GetOptionGroupsResponse-Objekt aufgelöst wird. Wenn ein Callback an diese Funktion übergeben wird, werden die zurückgegebenen Daten stattdessen an diesen übergeben.

Parameter

• scannerHandle

  String

  Das Handle eines geöffneten Scanners, das von einem Aufruf von openScanner zurückgegeben wurde.

Ausgabe

• Promise<GetOptionGroupsResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird.

getScannerList()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.getScannerList(
  filter: DeviceFilter,
): Promise<GetScannerListResponse>

Ruft die Liste der verfügbaren Scanner ab und gibt ein Promise zurück, das mit einem GetScannerListResponse-Objekt aufgelöst wird. Wenn ein Callback an diese Funktion übergeben wird, werden die zurückgegebenen Daten stattdessen an diesen übergeben.

Parameter

• Filter

  DeviceFilter

  Ein DeviceFilter, der angibt, welche Arten von Scannern zurückgegeben werden sollen.

Ausgabe

• Promise<GetScannerListResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis und der Liste der Scanner aufgelöst wird.

openScanner()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.openScanner(
  scannerId: string,
): Promise<OpenScannerResponse>

Öffnet einen Scanner für den exklusiven Zugriff und gibt ein Promise zurück, das mit einem OpenScannerResponse-Objekt aufgelöst wird. Wenn ein Callback an diese Funktion übergeben wird, werden die zurückgegebenen Daten stattdessen an diesen übergeben.

Parameter

• scannerId

  String

  Die ID eines Scanners, der geöffnet werden soll. Dieser Wert wird von einem vorherigen Aufruf von getScannerList zurückgegeben.

Ausgabe

• Promise<OpenScannerResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird.

readScanData()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.readScanData(
  job: string,
): Promise<ReadScanDataResponse>

Liest den nächsten Block verfügbarer Bilddaten aus einem aktiven Job-Handle und gibt ein Promise zurück, das mit einem ReadScanDataResponse-Objekt aufgelöst wird. Wenn ein Callback verwendet wird, wird das Objekt stattdessen an diesen übergeben.

**Hinweis:**Es ist zulässig, dass ein Antwortergebnis SUCCESS mit einem data-Element der Länge 0 ist. Das bedeutet, dass der Scanner noch arbeitet, aber noch keine zusätzlichen Daten bereitgestellt hat. Der Anrufer sollte kurz warten und es dann noch einmal versuchen.

Wenn der Scanvorgang abgeschlossen ist, hat die Antwort den Ergebniswert EOF. Diese Antwort kann ein abschließendes data-Mitglied ungleich null enthalten.

Parameter

• Job

  String

  Aktives Job-Handle, das zuvor von startScan zurückgegeben wurde.

Ausgabe

• Promise<ReadScanDataResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird.

scan()

browser.documentScan.scan(
  options: ScanOptions,
): Promise<ScanResults>

Führt einen Dokumentenscan durch und gibt ein Promise zurück, das mit einem ScanResults-Objekt aufgelöst wird. Wenn ein Callback an diese Funktion übergeben wird, werden die zurückgegebenen Daten stattdessen an diesen übergeben.

Parameter

• Optionen

  ScanOptions

  Ein Objekt mit Scanparametern.

Ausgabe

• Promise<ScanResults>

  Chrome 96+ browser.* seit Chrome 148

  Gibt ein Promise zurück, das mit den Scanergebnissen aufgelöst wird.

setOptions()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
): Promise<SetOptionsResponse>

Legt Optionen für den angegebenen Scanner fest und gibt ein Promise zurück, das mit einem SetOptionsResponse-Objekt aufgelöst wird. Dieses Objekt enthält das Ergebnis des Versuchs, jeden Wert in der Reihenfolge des übergebenen OptionSetting-Objekts festzulegen. Wenn ein Callback verwendet wird, wird das Objekt stattdessen an diesen übergeben.

Parameter

• scannerHandle

  String

  Der Handle des Scanners, für den Optionen festgelegt werden sollen. Dies sollte ein Wert sein, der zuvor von einem Aufruf von openScanner zurückgegeben wurde.

• Optionen

  OptionSetting[]

  Eine Liste von OptionSetting-Objekten, die auf den Scanner angewendet werden sollen.

Ausgabe

• Promise<SetOptionsResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird.

startScan()

Chrome 125 und höher browser.* seit Chrome 148

browser.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
): Promise<StartScanResponse>

Startet einen Scan auf dem angegebenen Scanner und gibt ein Promise zurück, das mit einem StartScanResponse aufgelöst wird. Wenn ein Callback verwendet wird, wird das Objekt stattdessen an diesen übergeben. Wenn der Aufruf erfolgreich war, enthält die Antwort ein Job-Handle, das in nachfolgenden Aufrufen verwendet werden kann, um Scandaten zu lesen oder einen Scan abzubrechen.

Parameter

• scannerHandle

  String

  Das Handle eines geöffneten Scanners. Dies sollte ein Wert sein, der zuvor von einem Aufruf von openScanner zurückgegeben wurde.

• Optionen

  StartScanOptions

  Ein StartScanOptions-Objekt, das die Optionen für den Scan angibt. Die Property StartScanOptions.format muss mit einem der Einträge übereinstimmen, die im ScannerInfo des Scanners zurückgegeben werden.

Ausgabe

• Promise<StartScanResponse>

  Gibt ein Promise zurück, das mit dem Ergebnis aufgelöst wird.