chrome.documentScan

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.documentScan per rilevare e recuperare immagini dagli scanner di documenti collegati.

Autorizzazioni

documentScan

Disponibilità

Chrome 44 e versioni successive Solo ChromeOS

API Document Scan

L'API Document Scan è progettata per consentire ad app ed estensioni di visualizzare i contenuti dei documenti cartacei su uno scanner per documenti collegato.

Tipi

CancelScanResponse

Chrome 125 e versioni successive

Proprietà

  • job

    stringa

    Fornisce lo stesso handle del job passato a cancelScan().

  • risultato

    OperationResult

    Il risultato dell'annullamento della scansione del backend. Se il risultato è OperationResult.SUCCESS o OperationResult.CANCELLED, la scansione è stata annullata e lo scanner è pronto per avviarne una nuova. Se il risultato è OperationResult.DEVICE_BUSY , lo scanner sta ancora elaborando l'annullamento richiesto; il chiamante deve attendere un breve periodo di tempo e riprovare a inviare la richiesta. Altri valori dei risultati indicano un errore permanente per cui non è necessario riprovare.

CloseScannerResponse

Chrome 125 e versioni successive

Proprietà

  • risultato

    OperationResult

    Il risultato della chiusura dello scanner. Anche se questo valore non è SUCCESS, l'handle non sarà valido e non deve essere utilizzato per altre operazioni.

  • scannerHandle

    stringa

    Lo stesso handle dello scanner passato a closeScanner.

Configurability

Chrome 125 e versioni successive

Come è possibile modificare un'opzione.

Enum

"NOT_CONFIGURABLE"
L'opzione è di sola lettura.

"SOFTWARE_CONFIGURABLE"
L'opzione può essere impostata nel software.

"HARDWARE_CONFIGURABLE"
L'opzione può essere impostata dall'utente attivando/disattivando o premendo un pulsante sullo scanner.

ConnectionType

Chrome 125 e versioni successive

Indica come lo scanner è collegato al computer.

Enum

"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

Chrome 125 e versioni successive

Il tipo di dati del vincolo rappresentato da un OptionConstraint.

Enum

"INT_RANGE"
Il vincolo su un intervallo di valori OptionType.INT. Le proprietà min, max e quant di OptionConstraint saranno long e la proprietà list non sarà impostata.

"FIXED_RANGE"
Il vincolo su un intervallo di valori OptionType.FIXED. Le proprietà min, max e quant di OptionConstraint saranno double e la proprietà list non verrà impostata.

"INT_LIST"
Il vincolo su un elenco specifico di valori OptionType.INT. La proprietà OptionConstraint.list conterrà i valori long e le altre proprietà non verranno impostate.

"FIXED_LIST"
Il vincolo su un elenco specifico di valori OptionType.FIXED. La proprietà OptionConstraint.list conterrà i valori double e le altre proprietà non verranno impostate.

"STRING_LIST"
Il vincolo su un elenco specifico di valori OptionType.STRING. La proprietà OptionConstraint.list conterrà i valori DOMString e le altre proprietà non verranno impostate.

DeviceFilter

Chrome 125 e versioni successive

Proprietà

  • local

    boolean facoltativo

    Restituisci solo gli scanner collegati direttamente al computer.

  • sicuro

    boolean facoltativo

    Restituisci solo gli scanner che utilizzano un trasporto sicuro, come USB o TLS.

GetOptionGroupsResponse

Chrome 125 e versioni successive

Proprietà

  • gruppi

    OptionGroup[] facoltativo

    Se result è SUCCESS, fornisce un elenco di gruppi di opzioni nell'ordine fornito dal driver dello scanner.

  • risultato

    OperationResult

    Il risultato del recupero dei gruppi di opzioni. Se il valore è SUCCESS, verrà compilata la proprietà groups.

  • scannerHandle

    stringa

    Lo stesso handle dello scanner passato a getOptionGroups.

GetScannerListResponse

Chrome 125 e versioni successive

Proprietà

  • risultato

    OperationResult

    Il risultato dell'enumerazione. Tieni presente che potrebbero essere restituiti risultati parziali anche se questo indica un errore.

  • scanner

    ScannerInfo[]

    Un elenco, eventualmente vuoto, di scanner che corrispondono al valore DeviceFilter fornito.

OpenScannerResponse

Chrome 125 e versioni successive

Proprietà

  • opzioni

    object facoltativo

    Se result è SUCCESS, fornisce una mappatura chiave-valore in cui la chiave è un'opzione specifica del dispositivo e il valore è un'istanza di ScannerOption.

  • risultato

    OperationResult

    Il risultato dell'apertura dello scanner. Se il valore è SUCCESS, verranno compilate le proprietà scannerHandle e options.

  • scannerHandle

    stringa facoltativa

    Se result è SUCCESS, un handle dello scanner che può essere utilizzato per ulteriori operazioni.

  • scannerId

    stringa

    L'ID scanner passato a openScanner().

OperationResult

Chrome 125 e versioni successive

Un enum che indica il risultato di ogni operazione.

Enum

"UNKNOWN"
Si è verificato un errore sconosciuto o generico.

"SUCCESS"
L'operazione è riuscita.

"UNSUPPORTED"
L'operazione non è supportata.

"CANCELLED"
L'operazione è stata annullata.

"DEVICE_BUSY"
Il dispositivo è occupato.

"INVALID"
I dati o un argomento passato al metodo non sono validi.

"WRONG_TYPE"
Il valore fornito è del tipo di dati errato per l'opzione sottostante.

"EOF"
Non sono disponibili altri dati.

"ADF_JAMMED"
L'alimentatore di documenti è inceppato.

"ADF_EMPTY"
L'alimentatore di documenti è vuoto.

"COVER_OPEN"
Il coperchio dello scanner è aperto.

"IO_ERROR"
Si è verificato un errore durante la comunicazione con il dispositivo.

"ACCESS_DENIED"
Il dispositivo richiede l'autenticazione.

"NO_MEMORY"
La memoria disponibile su Chromebook non è sufficiente per completare l'operazione.

"UNREACHABLE"
Il dispositivo non è raggiungibile.

"MISSING"
Il dispositivo è disconnesso.

"INTERNAL_ERROR"
Si è verificato un errore in un punto diverso dall'applicazione chiamante.

OptionConstraint

Chrome 125 e versioni successive

Proprietà

  • list

    string[] | number[] facoltativo

  • max

    number optional

  • min

    number optional

  • quant

    number optional

OptionGroup

Chrome 125 e versioni successive

Proprietà

  • membri

    string[]

    Un array di nomi di opzioni nell'ordine fornito dal driver.

  • titolo

    stringa

    Fornisce un titolo stampabile, ad esempio "Opzioni di geometria".

OptionSetting

Chrome 125 e versioni successive

Proprietà

  • nome

    stringa

    Indica il nome dell'opzione da impostare.

  • tipo

    OptionType

    Indica il tipo di dati dell'opzione. Il tipo di dati richiesto deve corrispondere al tipo di dati reale dell'opzione sottostante.

  • valore

    string | number | boolean | number[] facoltativo

    Indica il valore da impostare. Non impostare questo campo per richiedere l'impostazione automatica per le opzioni con autoSettable abilitato. Il tipo di dati fornito per value deve corrispondere a type.

OptionType

Chrome 125 e versioni successive

Il tipo di dati di un'opzione.

Enum

"UNKNOWN"
Il tipo di dati dell'opzione è sconosciuto. La proprietà value verrà annullata.

"BOOL"
La proprietà value sarà uno dei valori truefalse.

"INT"
Un numero intero con segno a 32 bit. La proprietà value sarà long o long[], a seconda che l'opzione accetti più di un valore.

"FIXED"
Un valore double nell'intervallo -32768-32767.9999 con una risoluzione di 1/65535. La proprietà value sarà double o double[] a seconda che l'opzione accetti più di un valore. I valori Double che non possono essere rappresentati esattamente verranno arrotondati all'intervallo e alla precisione disponibili.

"STRING"
Una sequenza di byte, ad eccezione di NUL ('\0'). La proprietà value sarà una DOMString.

"BUTTON"
Un'opzione di questo tipo non ha valore. Al contrario, l'impostazione di un'opzione di questo tipo causa un effetto collaterale specifico dell'opzione nel driver dello scanner. Ad esempio, un'opzione di tipo pulsante potrebbe essere utilizzata da un driver dello scanner per fornire un mezzo per selezionare i valori predefiniti o per indicare a un alimentatore automatico di documenti di passare al foglio di carta successivo.

"GROUP"
Opzione di raggruppamento. Nessun valore. Questo valore è incluso per motivi di compatibilità, ma normalmente non viene restituito nei valori ScannerOption. Utilizza getOptionGroups() per recuperare l'elenco dei gruppi con le relative opzioni per i membri.

OptionUnit

Chrome 125 e versioni successive

Indica il tipo di dati per ScannerOption.unit.

Enum

"UNITLESS"
Il valore è un numero senza unità. Ad esempio, può essere una soglia.

"PIXEL"
Il valore è un numero di pixel, ad esempio le dimensioni della scansione.

"BIT"
Il valore è il numero di bit, ad esempio la profondità di colore.

"MM"
Il valore viene misurato in millimetri, ad esempio le dimensioni della scansione.

"DPI"
Il valore viene misurato in punti per pollice, ad esempio la risoluzione.

"PERCENT"
Il valore è una percentuale, ad esempio la luminosità.

"MICROSECOND"
Il valore viene misurato in microsecondi, ad esempio il tempo di esposizione.

ReadScanDataResponse

Chrome 125 e versioni successive

Proprietà

  • dati

    ArrayBuffer facoltativo

    Se result è SUCCESS, contiene il blocco successivo di dati dell'immagine scansionata. Se result è EOF, contiene l'ultimo blocco di dati dell'immagine scansionata.

  • estimatedCompletion

    number optional

    Se result è SUCCESS, una stima della quantità di dati di scansione totali inviati finora, nell'intervallo compreso tra 0 e 100.

  • job

    stringa

    Fornisce l'handle del job passato a readScanData().

  • risultato

    OperationResult

    Il risultato della lettura dei dati. Se il valore è SUCCESS, data contiene il blocco di dati immagine successivo (potenzialmente di lunghezza zero) pronto per la lettura. Se il valore è EOF, data contiene l'ultimo blocco di dati dell'immagine.

ScannerInfo

Chrome 125 e versioni successive

Proprietà

  • connectionType

    ConnectionType

    Indica come lo scanner è collegato al computer.

  • deviceUuid

    stringa

    Per la corrispondenza con altre voci ScannerInfo che rimandano allo stesso dispositivo fisico.

  • imageFormats

    string[]

    Un array di tipi MIME che possono essere richiesti per le scansioni restituite.

  • produttore

    stringa

    Il produttore dello scanner.

  • modello

    stringa

    Il modello dello scanner, se disponibile, o una descrizione generica.

  • nome

    stringa

    Un nome leggibile per lo scanner da visualizzare nella UI.

  • protocolType

    stringa

    Una descrizione leggibile del protocollo o del driver utilizzato per accedere allo scanner, ad esempio Mopria, WSD o epsonds. Ciò è utile principalmente per consentire a un utente di scegliere tra i protocolli se un dispositivo ne supporta più di uno.

  • scannerId

    stringa

    L'ID di uno scanner specifico.

  • sicuro

    booleano

    Se impostato su true, il trasporto della connessione dello scanner non può essere intercettato da un listener passivo, ad esempio TLS o USB.

ScannerOption

Chrome 125 e versioni successive

Proprietà

  • configurabilità

    Configurabilità

    Indica se e come l'opzione può essere modificata.

  • vincolo

    OptionConstraint facoltativo

    Definisce OptionConstraint nell'opzione di scansione corrente.

  • descrizione

    stringa

    Una descrizione più lunga dell'opzione.

  • isActive

    booleano

    Indica che l'opzione è attiva e può essere impostata o recuperata. Se viene impostato su false, la proprietà value non verrà impostata.

  • isAdvanced

    booleano

    Indica che la UI non deve visualizzare questa opzione per impostazione predefinita.

  • isAutoSettable

    booleano

    Può essere impostata automaticamente dal driver dello scanner.

  • isDetectable

    booleano

    Indica che questa opzione può essere rilevata dal software.

  • isEmulated

    booleano

    Emulato dal driver dello scanner se true.

  • nome

    stringa

    Il nome dell'opzione che utilizza lettere ASCII minuscole, numeri e trattini. I segni diacritici non sono consentiti.

  • titolo

    stringa

    Un titolo di una riga stampabile.

  • tipo

    OptionType

    Il tipo di dati contenuto nella proprietà value, necessario per impostare questa opzione.

  • unità

    OptionUnit

    L'unità di misura per questa opzione.

  • valore

    string | number | boolean | number[] facoltativo

    Il valore attuale dell'opzione, se pertinente. Tieni presente che il tipo di dati di questa proprietà deve corrispondere a quello specificato in type.

ScanOptions

Proprietà

  • maxImages

    number optional

    Il numero di immagini scansionate consentite. Il valore predefinito è 1.

  • mimeTypes

    string[] facoltativo

    I tipi MIME accettati dal chiamante.

ScanResults

Proprietà

  • dataUrls

    string[]

    Un array di URL di immagini di dati in un formato che può essere passato come valore "src" a un tag immagine.

  • mimeType

    stringa

    Il tipo MIME di dataUrls.

SetOptionResult

Chrome 125 e versioni successive

Proprietà

  • nome

    stringa

    Indica il nome dell'opzione impostata.

  • risultato

    OperationResult

    Indica il risultato dell'impostazione dell'opzione.

SetOptionsResponse

Chrome 125 e versioni successive

Proprietà

  • opzioni

    object facoltativo

    Una mappatura chiave-valore aggiornata dai nomi delle opzioni ai valori ScannerOption contenenti la nuova configurazione dopo aver tentato di impostare tutte le opzioni fornite. Ha la stessa struttura della proprietà options in OpenScannerResponse.

    Questa proprietà verrà impostata anche se alcune opzioni non sono state impostate correttamente, ma verrà annullata se il recupero della configurazione aggiornata non va a buon fine (ad esempio, se lo scanner viene disconnesso durante la scansione).

  • risultati

    SetOptionResult[]

    Un array di risultati, uno per ogni OptionSetting passato.

  • scannerHandle

    stringa

    Fornisce l'handle dello scanner passato a setOptions().

StartScanOptions

Chrome 125 e versioni successive

Proprietà

  • formato

    stringa

    Specifica il tipo MIME in cui restituire i dati scansionati.

  • maxReadSize

    number optional

    Se viene specificato un valore diverso da zero, limita il numero massimo di byte scansionati restituiti in una singola risposta readScanData a quel valore. Il valore minimo consentito è 32768 (32 KB). Se questa proprietà non viene specificata, le dimensioni di un blocco restituito potrebbero essere pari a quelle dell'intera immagine scansionata.

StartScanResponse

Chrome 125 e versioni successive

Proprietà

  • job

    stringa facoltativa

    Se result è SUCCESS, fornisce un handle che può essere utilizzato per leggere i dati di scansione o annullare il job.

  • risultato

    OperationResult

    Il risultato dell'avvio di una scansione. Se il valore è SUCCESS, verrà compilata la proprietà job.

  • scannerHandle

    stringa

    Fornisce lo stesso handle dello scanner passato a startScan().

Metodi

cancelScan()

Promise Chrome 125+ 
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
): Promise<CancelScanResponse>

Annulla una scansione avviata e restituisce una promessa che si risolve con un oggetto CancelScanResponse. Se viene utilizzato un callback, l'oggetto viene passato a quest'ultimo.

Parametri

  • job

    stringa

    L'handle di un job di scansione attivo restituito in precedenza da una chiamata a startScan.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (response: CancelScanResponse) => void

Resi

  • Restituisce una promessa che si risolve con il risultato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

closeScanner()

Promise Chrome 125+ 
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
): Promise<CloseScannerResponse>

Chiude lo scanner con l'handle passato e restituisce una Promise che si risolve con un oggetto CloseScannerResponse. Se viene utilizzato un callback, l'oggetto viene passato a quest'ultimo. Anche se la risposta non ha esito positivo, l'handle fornito diventa non valido e non deve essere utilizzato per ulteriori operazioni.

Parametri

  • scannerHandle

    stringa

    Specifica l'handle di uno scanner aperto restituito in precedenza da una chiamata a openScanner.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (response: CloseScannerResponse) => void

Resi

  • Restituisce una promessa che si risolve con il risultato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getOptionGroups()

Promise Chrome 125+ 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
): Promise<GetOptionGroupsResponse>

Recupera i nomi dei gruppi e le opzioni dei membri da uno scanner aperto in precedenza da openScanner. Questo metodo restituisce una Promise che si risolve con un oggetto GetOptionGroupsResponse. Se a questa funzione viene passato un callback, i dati restituiti vengono passati al callback.

Parametri

Resi

  • Restituisce una promessa che si risolve con il risultato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

getScannerList()

Promise Chrome 125+ 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
): Promise<GetScannerListResponse>

Recupera l'elenco degli scanner disponibili e restituisce una Promise che si risolve con un oggetto GetScannerListResponse. Se a questa funzione viene passato un callback, i dati restituiti vengono passati al callback.

Parametri

Resi

  • Restituisce una Promise che si risolve con il risultato e l'elenco degli scanner.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

openScanner()

Promise Chrome 125+ 
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
): Promise<OpenScannerResponse>

Apre uno scanner per l'accesso esclusivo e restituisce una Promise che si risolve con un oggetto OpenScannerResponse. Se a questa funzione viene passato un callback, i dati restituiti vengono passati al callback.

Parametri

  • scannerId

    stringa

    L'ID di uno scanner da aprire. Questo valore viene restituito da una chiamata precedente a getScannerList.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (response: OpenScannerResponse) => void

Resi

  • Restituisce una promessa che si risolve con il risultato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

readScanData()

Promise Chrome 125+ 
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
): Promise<ReadScanDataResponse>

Legge il blocco successivo di dati immagine disponibili da un handle di job attivo e restituisce una Promise che si risolve con un oggetto ReadScanDataResponse. Se viene utilizzato un callback, l'oggetto viene passato a quest'ultimo.

**Nota:**è valido un risultato della risposta SUCCESS con un membro data di lunghezza pari a zero. Ciò significa che lo scanner è ancora in funzione, ma non ha ancora dati aggiuntivi pronti. Il chiamante deve attendere un breve periodo di tempo e riprovare.

Al termine del job di scansione, la risposta avrà il valore del risultato EOF. Questa risposta potrebbe contenere un membro data finale diverso da zero.

Parametri

Resi

  • Restituisce una promessa che si risolve con il risultato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

scan()

Promise 
chrome.documentScan.scan(
  options: ScanOptions,
  callback?: function,
): Promise<ScanResults>

Esegue una scansione del documento e restituisce una Promise che si risolve con un oggetto ScanResults. Se a questa funzione viene passato un callback, i dati restituiti vengono passati al callback.

Parametri

  • opzioni

    ScanOptions

    Un oggetto contenente i parametri di scansione.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: ScanResults) => void

Resi

  • Promise<ScanResults>

    Chrome 96 e versioni successive

    Restituisce una Promise che si risolve con i risultati della scansione.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

setOptions()

Promise Chrome 125+ 
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
): Promise<SetOptionsResponse>

Imposta le opzioni sullo scanner specificato e restituisce una Promise che si risolve con un oggetto SetOptionsResponse contenente il risultato del tentativo di impostare ogni valore nell'ordine dell'oggetto OptionSetting passato. Se viene utilizzato un callback, l'oggetto viene passato a quest'ultimo.

Parametri

  • scannerHandle

    stringa

    L'handle dello scanner su cui impostare le opzioni. Deve essere un valore restituito in precedenza da una chiamata a openScanner.

  • opzioni

    OptionSetting[]

    Un elenco di oggetti OptionSetting da applicare allo scanner.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (response: SetOptionsResponse) => void

Resi

  • Restituisce una promessa che si risolve con il risultato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

startScan()

Promise Chrome 125+ 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
): Promise<StartScanResponse>

Avvia una scansione sullo scanner specificato e restituisce una Promise che si risolve con un StartScanResponse. Se viene utilizzato un callback, l'oggetto viene passato a quest'ultimo. Se la chiamata è andata a buon fine, la risposta include un handle del job che può essere utilizzato nelle chiamate successive per leggere i dati di scansione o annullare una scansione.

Parametri

  • scannerHandle

    stringa

    Il punto di manipolazione di uno scanner aperto. Deve essere un valore restituito in precedenza da una chiamata a openScanner.

  • Un oggetto StartScanOptions che indica le opzioni da utilizzare per la scansione. La proprietà StartScanOptions.format deve corrispondere a una delle voci restituite in ScannerInfo dello scanner.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (response: StartScanResponse) => void

Resi

  • Restituisce una promessa che si risolve con il risultato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.