chrome.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 ermöglicht es Apps und Erweiterungen, den Inhalt von Papierdokumenten auf einem angeschlossenen Dokumentenscanner anzusehen.

Berechtigungen

documentScan

Verfügbarkeit

Chrome 44 und höher 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 Möglichkeiten zum Scannen von Dokumenten. Wenn Ihr Anwendungsfall mit jedem Scanner funktioniert und keine Kontrolle der Konfiguration erfordert, verwenden Sie die Methode scan(). 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, also solche, die mit jedem Scanner funktionieren und keine Konfigurationssteuerung erfordern, rufen Sie scan() auf. Diese Methode nimmt ein ScanOptions-Objekt entgegen 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.

Komplexes Scannen

Komplexe Scans werden in drei Phasen durchgeführt, wie in diesem Abschnitt beschrieben. In diesem Überblick werden nicht alle Methodenargumente oder alle Eigenschaften beschrieben, die in einer Antwort zurückgegeben werden. Sie soll Ihnen nur einen allgemeinen Leitfaden 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 einer 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 Scanner mehrere Protokolle oder Verbindungsmethoden unterstützt.

2. Wählen Sie einen Scanner aus dem zurückgegebenen Array aus und speichern Sie den Wert seiner Property 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 die Property deviceUuid. ScannerInfo enthält außerdem die Eigenschaft imageFormats mit einem Array unterstützter Bildtypen.

Scannerkonfiguration

1. Rufen Sie openScanner() auf und geben Sie die gespeicherte Scanner-ID an. Es gibt ein Versprechen zurück, das mit einer OpenScannerResponse aufgelöst wird. Das Antwortobjekt enthält:

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

   • Eine Optionseigenschaft mit scannerspezifischen Eigenschaften, die Sie festlegen müssen. Weitere Informationen finden Sie unter Scanneroptionen abrufen.

2. Optional: Wenn der Nutzer Werte für Scanneroptionen angeben soll, 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 von Nutzern bereitgestellten Werten. Weitere Informationen finden Sie unter „Scanneroptionen festlegen“.

4. Übergeben Sie das Array der OptionSetting-Objekte an setOptions(), um Optionen für den Scanner festzulegen. Es gibt ein Promise zurück, 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 die Änderung einer Option die Einschränkungen für eine andere Option ändern können, müssen Sie diese Schritte möglicherweise mehrmals wiederholen.

Scannen

1. Erstelle ein StartScanOptions-Objekt und übergebe es an startScan(). Es gibt ein Versprechen zurück, das mit einem StartScanResponse aufgelöst wird. Die Eigenschaft job ist ein Handle, mit dem Sie entweder Scandaten lesen oder den Scan abbrechen können.

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

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

3. Wiederholen Sie den vorherigen Schritt, bis das Attribut result EOF oder einen Fehler zurückgibt.

Wenn das Ende des Scans erreicht ist, rufen Sie closeScanner() mit dem in Schritt 3 gespeicherten Scanner-Handle auf. Es gibt ein Versprechen zurück, das mit einem CloseScannerResponse aufgelöst wird. Wenn Sie nach dem Erstellen des Jobs jederzeit cancelScan() aufrufen, wird der Scanvorgang beendet.

Antwortobjekte

Alle Methoden geben ein Versprechen zurück, das mit einem Antwortobjekt einer bestimmten Art aufgelöst wird. Die meisten davon enthalten eine result-Eigenschaft, deren Wert zu OperationResult gehört. Einige Eigenschaften von Antwortobjekten enthalten nur dann Werte, wenn 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 zu berücksichtigen. Um dieses Problem zu umgehen, enthalten OpenScannerResponse (abgerufen mit openScanner()) und SetOptionsResponse (das Antwortobjekt für setOptions()) das Attribut options, ein Objekt mit scannerspezifischen Optionen. 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 }
}

Angenommen, ein Scanner gibt die Optionen „Quelle“ und „Auflösung“ zurück. 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, Sie können aber festlegen, dass ein Nutzer den Wert für eine bestimmte Option auswählen muss. Dazu ist eine Benutzeroberfläche erforderlich. Verwenden Sie die Taste OpenScannerResponse (geöffnet durch openScanner()), um wie im vorherigen Abschnitt beschrieben die Optionen für den angeschlossenen Scanner abzurufen.

Einige Scanner gruppieren Optionen auf gerätespezifische Weise. 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. Dies gibt ein Promise zurück, das mit einem GetOptionGroupsResponse-Objekt aufgelöst wird. Die Eigenschaft groups enthält ein scannerspezifisches Array von Gruppen. Anhand der Informationen in diesen Gruppen können Sie die Optionen in OpenScannerResponse für die Anzeige organisieren.

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

Wie unter „Scannerkonfiguration“ erwähnt, kann sich durch das Ändern einer Option die Einschränkung einer anderen Option ändern. Deshalb enthält setOptionsResponse (das Antwortobjekt für setOptions()) eine weitere options-Property. Damit können Sie die Benutzeroberfläche aktualisieren. Wiederholen Sie dann diesen Schritt nach Bedarf, bis alle Optionen festgelegt sind.

Scanneroptionen festlegen

Legen Sie die 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 eine Möglichkeit zum Abrufen einer Seite aus dem Scanner als Blob gezeigt. Außerdem wird die Verwendung von startScan() und readScanData() mit dem Wert von OperationResult veranschaulicht.

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

  let imgParts = [];
  response = await chrome.documentScan.readScanData(job);
  while (response.result == chrome.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 chrome.documentScan.readScanData(job);
  }
  if (response.result != chrome.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 ruft er den Inhalt einer einzelnen Seite ab und schließt den Scanner. In diesem Beispiel werden getScannerList(), openScanner(), setOptions() und closeScanner() verwendet. Der Inhalt der Seite wird durch Aufrufen der pageAsBlob()-Funktion aus dem vorherigen Beispiel abgerufen.

async function scan() {
    let response = await chrome.documentScan.getScannerList({ secure: true });
    let scanner = await chrome.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: chrome.documentScan.OptionType.STRING,
                value: { value: source }
            });
            break;
        }
    }
    options.push({
        name: "tl-x",
        type: chrome.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-x",
        type: chrome.documentScan.OptionType.FIXED,
        value: 215.9  // 8.5" in mm
    });
    options.push({
        name: "tl-y",
        type: chrome.documentScan.OptionType.FIXED,
        value: 0.0
    });
    options.push({
        name: "br-y",
        type: chrome.documentScan.OptionType.FIXED,
        value: 279.4  // 11" in mm
    });
    response = await chrome.documentScan.setOptions(handle, options);

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

Konfiguration anzeigen

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

async function showConfig() {
  let response = await chrome.documentScan.getScannerList({ secure: true });
  let scanner = await chrome.documentScan.openScanner(
      response.scanners[0].scannerId);
  let groups = await chrome.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

Attribute

• Job

  String

  Derselbe Job-Handle, der an cancelScan() übergeben wurde.

• Ergebnis

  OperationResult

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

CloseScannerResponse

Chrome 125 und höher

Attribute

• Ergebnis

  OperationResult

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

• scannerHandle

  String

  Derselbe Scanner-Handle, der an closeScanner übergeben wurde.

Configurability

Chrome 125 und höher

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 Ein-/Ausschalten oder Drücken einer Taste am Scanner festgelegt werden.

ConnectionType

Chrome 125 und höher

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

Enum

„UNBESCHRIEBEN“

„USB“

„Netzwerk“

ConstraintType

Chrome 125 und höher

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

Enum

INT_RANGE
Die Einschränkung für einen Bereich von OptionType.INT-Werten. Die Attribute min, max und quant von OptionConstraint sind long und das Attribut list ist 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"
Einschränkung für eine bestimmte Liste von OptionType.INT-Werten. Die Property OptionConstraint.list enthält long-Werte und die anderen Properties sind nicht festgelegt.

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

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

DeviceFilter

Chrome 125 und höher

Attribute

• lokal

  boolescher Wert optional

  Senden Sie nur Scanner zurück, die direkt mit dem Computer verbunden sind.

• sicher

  boolescher Wert optional

  Senden Sie nur Scanner zurück, die einen sicheren Transport wie USB oder TLS verwenden.

GetOptionGroupsResponse

Chrome 125 und höher

Attribute

• Gruppen

  OptionGroup[] optional

  Wenn result SUCCESS ist, wird eine Liste der Optionsgruppen in der vom Scannertreiber angegebenen Reihenfolge angezeigt.

• Ergebnis

  OperationResult

  Das Ergebnis des Abrufens der Optionsgruppen. Wenn der Wert SUCCESS ist, wird die Property groups ausgefüllt.

• scannerHandle

  String

  Derselbe Scanner-Handle, der an getOptionGroups übergeben wurde.

GetScannerListResponse

Chrome 125 und höher

Attribute

• Ergebnis

  OperationResult

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

• Scanner

  ScannerInfo[]

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

OpenScannerResponse

Chrome 125 und höher

Attribute

• Optionen

  object optional

  Wenn result = SUCCESS ist, geben Sie eine Schlüssel/Wert-Zuordnung an, 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 SUCCESS ist, ein Handle für den Scanner, der für weitere Vorgänge verwendet werden kann.

• scannerId

  String

  Die Scanner-ID, die an openScanner() übergeben wurde.

OperationResult

Chrome 125 und höher

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.

„ABGEBROCHEN“
Der Vorgang wurde abgebrochen.

„DEVICE_BUSY“
Das Gerät ist belegt.

„INVALID“
Entweder sind die Daten oder ein an die Methode übergebenes Argument 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 klemmt.

„ADF_EMPTY“
Der Dokumenteneinzug ist leer.

„COVER_OPEN“
Der Deckel des Flachbettscanners ist geöffnet.

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

„ACCESS_DENIED“
Für das Gerät ist eine Authentifizierung erforderlich.

„NO_MEMORY“
Auf dem Chromebook ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang auszuführen.

„UNREACHABLE“
Das Gerät ist nicht erreichbar.

„FEHLEND“
Das Gerät ist nicht verbunden.

"INTERNAL_ERROR"
Ein Fehler ist nicht in der anrufenden Anwendung aufgetreten.

OptionConstraint

Chrome 125 und höher

Attribute

• list

  string[] | number[] optional

• max

  number optional

• Min.

  number optional

• quant

  number optional

• Typ

  ConstraintType

OptionGroup

Chrome 125 und höher

Attribute

• Mitglieder

  String[]

  Ein Array von Optionsnamen in der vom Fahrer angegebenen Reihenfolge.

• Titel

  String

  Ein druckbarer Titel, z. B. „Geometrieoptionen“.

OptionSetting

Chrome 125 und höher

Attribute

• name

  String

  Gibt den Namen der Option an, die festgelegt werden soll.

• 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 Wert an, der festgelegt werden soll. 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

Der Datentyp einer Option.

Enum

„UNKNOWN“
Der Datentyp der Option ist unbekannt. Das Attribut „value“ wird zurückgesetzt.

BOOL
Die Property value hat den Wert truefalse.

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

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

STRING
Eine beliebige Bytefolge mit Ausnahme von NUL ('\0'). Das Attribut value ist ein DOMString.

„BUTTON“
Eine Option dieses Typs hat keinen Wert. Stattdessen führt die Einstellung einer Option dieser Art zu einer optionspezifischen Nebenwirkung im Scannertreiber. So kann ein Scannertreiber beispielsweise eine Schaltflächenoption verwenden, um Standardwerte auszuwählen oder einen automatischen Dokumenteneinzug anzuweisen, zum nächsten Blatt Papier zu wechseln.

„GROUP“
Gruppierungsoption. Kein Wert. Dieser Wert ist aus Gründen der Kompatibilität enthalten, wird aber normalerweise nicht in ScannerOption-Werten zurückgegeben. Mit getOptionGroups() können Sie die Liste der Gruppen mit ihren Mitgliederoptionen abrufen.

OptionUnit

Chrome 125 und höher

Gibt den Datentyp für ScannerOption.unit an.

Enum

„UNITLESS“
Der Wert ist eine wertlose Zahl. Das kann beispielsweise ein Grenzwert sein.

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

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. Auflösung.

„PERCENT“
Der Wert ist ein Prozentsatz, z. B. für die Helligkeit.

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

ReadScanDataResponse

Chrome 125 und höher

Attribute

• Daten

  ArrayBuffer optional

  Wenn result SUCCESS ist, enthält es den nächsten Teil der gescannten Bilddaten. Wenn result EOF ist, enthält es den letzten Teil der gescannten Bilddaten.

• estimatedCompletion

  number optional

  Wenn result SUCCESS ist, eine Schätzung, wie viel Prozent der gesamten Scandaten bisher übermittelt wurden, im Bereich von 0 bis 100.

• Job

  String

  Gibt den Job-Handle an, der an readScanData() übergeben wird.

• Ergebnis

  OperationResult

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

ScannerInfo

Chrome 125 und höher

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 Scannerhersteller.

• Modell

  String

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

• name

  String

  Ein für Menschen lesbarer Name für den Scanner, der auf der Benutzeroberfläche angezeigt werden soll.

• protocolType

  String

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

• scannerId

  String

  Die ID eines bestimmten Scanners.

• sicher

  boolean

  Wenn diese Option aktiviert ist, kann der Transport der Scannerverbindung nicht von einem passiven Listener wie TLS oder USB abgefangen werden.

ScannerOption

Chrome 125 und höher

Attribute

• Konfigurierbarkeit

  Konfiguration

  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 ausführlichere Beschreibung der Option.

• isActive (Aktiv)

  boolean

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

• isAdvanced

  boolean

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

• isAutoSettable

  boolean

  Kann vom Scannertreiber automatisch festgelegt werden.

• isDetectable

  boolean

  Gibt an, dass diese Option über die Software erkannt werden kann.

• isEmulated

  boolean

  Wird vom Scannertreiber emuliert, wenn „wahr“ festgelegt ist.

• name

  String

  Der Optionenname muss Kleinbuchstaben, Ziffern und Bindestriche enthalten. Akzente sind nicht zulässig.

• Titel

  String

  Ein druckbarer einzeiliger Titel.

• Typ

  OptionType

  Der Datentyp in der value-Eigenschaft, der 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 zutreffend. Der Datentyp dieser Property muss mit dem in type angegebenen Datentyp übereinstimmen.

ScanOptions

Attribute

• maxImages

  number optional

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

• mimeTypes

  string[] optional

  Die MIME-Typen, die vom Anrufer akzeptiert werden.

ScanResults

Attribute

• dataUrls

  String[]

  Ein Array von Datenbild-URLs in einer Form, die als „src“-Wert an ein Bild-Tag übergeben werden kann.

• mimeType

  String

  Der MIME-Typ der dataUrls.

SetOptionResult

Chrome 125 und höher

Attribute

• name

  String

  Der Name der festgelegten Option.

• Ergebnis

  OperationResult

  Gibt das Ergebnis der Option an.

SetOptionsResponse

Chrome 125 und höher

Attribute

• Optionen

  object optional

  Eine aktualisierte Schlüssel/Wert-Zuordnung von Optionennamen zu ScannerOption-Werten, die die neue Konfiguration enthält, nachdem versucht wurde, alle angegebenen Optionen festzulegen. Sie hat dieselbe Struktur wie die Property options in OpenScannerResponse.

  Diese Eigenschaft wird auch dann festgelegt, wenn einige Optionen nicht erfolgreich festgelegt wurden. Sie wird jedoch aufgehoben, wenn der Abruf der aktualisierten Konfiguration fehlschlägt (z. B. wenn die Verbindung zum Scanner während des Scans getrennt wird).

• Ergebnisse

  SetOptionResult[]

  Ein Array von Ergebnissen, jeweils eines für jede übergebene OptionSetting.

• scannerHandle

  String

  Der Scanner-Handle, der an setOptions() übergeben wird.

StartScanOptions

Chrome 125 und höher

Attribute

• Format

  String

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

• maxReadSize

  number optional

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

StartScanResponse

Chrome 125 und höher

Attribute

• Job

  String optional

  Wenn result SUCCESS ist, 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 die Property job ausgefüllt.

• scannerHandle

  String

  Derselbe Scanner-Handle, der an startScan() übergeben wurde.

Methoden

cancelScan()

Versprechen Chrome 125 und höher

chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

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

Parameter

• Job

  String

  Der Handle eines aktiven Scanjobs, der zuvor von einem Aufruf von startScan zurückgegeben wurde.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: CancelScanResponse) => void

  • Antwort

    CancelScanResponse

Gibt Folgendes zurück:

• Promise<CancelScanResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

closeScanner()

Versprechen Chrome 125 und höher

chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

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 ihn übergeben. Auch wenn die Antwort nicht erfolgreich war, wird der angegebene Handle ungültig und darf nicht für weitere Vorgänge verwendet werden.

Parameter

• scannerHandle

  String

  Gibt den Handle eines geöffneten Scanners an, der zuvor von einem Aufruf von openScanner zurückgegeben wurde.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: CloseScannerResponse) => void

  • Antwort

    CloseScannerResponse

Gibt Folgendes zurück:

• Promise<CloseScannerResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getOptionGroups()

Versprechen Chrome 125 und höher

chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

Hiermit werden die Gruppennamen und Mitgliedsoptionen von einem Scanner abgerufen, der zuvor mit openScanner geöffnet wurde. Diese Methode gibt ein Promise zurück, das mit einem GetOptionGroupsResponse-Objekt aufgelöst wird. Wenn dieser Funktion ein Rückruf übergeben wird, werden stattdessen die zurückgegebenen Daten übergeben.

Parameter

• scannerHandle

  String

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

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: GetOptionGroupsResponse) => void

  • Antwort

    GetOptionGroupsResponse

Gibt Folgendes zurück:

• Promise<GetOptionGroupsResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

getScannerList()

Versprechen Chrome 125 und höher

chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

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

Parameter

• Filter

  DeviceFilter

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

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: GetScannerListResponse) => void

  • Antwort

    GetScannerListResponse

Gibt Folgendes zurück:

• Promise<GetScannerListResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

openScanner()

Versprechen Chrome 125 und höher

chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

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

Parameter

• scannerId

  String

  Die ID eines zu öffnenden Scanners. Dieser Wert wurde von einem vorherigen Aufruf von getScannerList zurückgegeben.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: OpenScannerResponse) => void

  • Antwort

    OpenScannerResponse

Gibt Folgendes zurück:

• Promise<OpenScannerResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

readScanData()

Versprechen Chrome 125 und höher

chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

Liest den nächsten verfügbaren Teil der 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 ihn übergeben.

**Hinweis:**Ein Antwortergebnis kann SUCCESS mit einem data-Element mit einer Länge von null sein. Das bedeutet, dass der Scanner noch funktioniert, aber noch keine weiteren Daten verfügbar sind. Der Anrufer sollte kurz warten und es dann noch einmal versuchen.

Wenn der Scanjob abgeschlossen ist, enthält die Antwort den Ergebniswert EOF. Diese Antwort kann ein abschließendes data-Element ungleich null enthalten.

Parameter

• Job

  String

  Der Handle des aktiven Jobs, der zuvor von startScan zurückgegeben wurde.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: ReadScanDataResponse) => void

  • Antwort

    ReadScanDataResponse

Gibt Folgendes zurück:

• Promise<ReadScanDataResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

scan()

Promise

chrome.documentScan.scan(
  options: ScanOptions,
  callback?: function,
)

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

Parameter

• Optionen

  ScanOptions

  Ein Objekt mit Scanparametern.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (result: ScanResults) => void

  • Ergebnis

    ScanResults

Gibt Folgendes zurück:

• Promise<ScanResults>

  Chrome 96 und höher

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

setOptions()

Versprechen Chrome 125 und höher

chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
)

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

Parameter

• scannerHandle

  String

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

• Optionen

  OptionSetting[]

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

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: SetOptionsResponse) => void

  • Antwort

    SetOptionsResponse

Gibt Folgendes zurück:

• Promise<SetOptionsResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

startScan()

Versprechen Chrome 125 und höher

chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
)

Startet einen Scan auf dem angegebenen Scanner und gibt ein Promise zurück, das mit einer StartScanResponse aufgelöst wird. Wenn ein Callback verwendet wird, wird das Objekt stattdessen an ihn übergeben. Wenn der Aufruf erfolgreich war, enthält die Antwort einen Job-Handle, der in nachfolgenden Aufrufen zum Lesen von Scandaten oder zum Abbrechen eines Scans verwendet werden kann.

Parameter

• scannerHandle

  String

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

• Optionen

  StartScanOptions

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

• callback

  function optional

  Der Parameter callback sieht so aus:

  (response: StartScanResponse) => void

  • Antwort

    StartScanResponse

Gibt Folgendes zurück:

• Promise<StartScanResponse>

  Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.