chrome.documentScan

refresh date: 2026-09-25 robots: noindex

Important : Cette API ne fonctionne que sur ChromeOS.

Description

Utilisez l'API chrome.documentScan pour découvrir et récupérer des images à partir de scanners de documents associés.

Autorisations

documentScan

Disponibilité

Chrome 44 ou version ultérieure ChromeOS uniquement

API Document Scan

L'API Document Scan est conçue pour permettre aux applications et aux extensions d'afficher le contenu de documents papier sur un scanner de documents associé.

Remarque : Cette API dépend de fonctionnalités de l'OS qui peuvent ne pas être disponibles en fonction du système d'exploitation sous-jacent. À l'heure où nous écrivons ces lignes, seul ChromeOS pour certains appareils connectés en USB est connu pour fonctionner correctement.

Types

CancelScanResponse

Chrome 125 ou version ultérieure

Propriétés

• job

  chaîne

  Fournit le même handle de job que celui transmis à cancelScan().

• résultat

  OperationResult

  Résultat de l'annulation de l'analyse du backend. Si le résultat est OperationResult.SUCCESS ou OperationResult.CANCELLED, l'analyse a été annulée et l'analyseur est prêt à en lancer une nouvelle. Si le résultat est OperationResult.DEVICE_BUSY , le scanner est toujours en train de traiter l'annulation demandée. L'appelant doit attendre un peu et réessayer. Les autres valeurs de résultat indiquent une erreur permanente qui ne doit pas être relancée.

CloseScannerResponse

Chrome 125 ou version ultérieure

Propriétés

• résultat

  OperationResult

  Résultat de la fermeture du scanner. Même si cette valeur n'est pas SUCCESS, le handle ne sera pas valide et ne devra pas être utilisé pour d'autres opérations.

• scannerHandle

  chaîne

  Le même handle de scanner que celui transmis à closeScanner.

Configurability

Chrome 125 ou version ultérieure

Comment modifier une option.

Énumération

"NOT_CONFIGURABLE"
L'option est en lecture seule.

"SOFTWARE_CONFIGURABLE"
L'option peut être définie dans le logiciel.

"HARDWARE_CONFIGURABLE"
L'option peut être définie par l'utilisateur en activant ou en appuyant sur un bouton du scanner.

ConnectionType

Chrome 125 ou version ultérieure

Indique comment le scanner est connecté à l'ordinateur.

Énumération

"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

Chrome 125 ou version ultérieure

Type de données de la contrainte représenté par un OptionConstraint.

Énumération

"INT_RANGE"
Contrainte sur une plage de valeurs OptionType.INT. Les propriétés min, max et quant de OptionConstraint seront long, et sa propriété list ne sera pas définie.

"FIXED_RANGE"
Contrainte sur une plage de valeurs OptionType.FIXED. Les propriétés min, max et quant de OptionConstraint seront double, et sa propriété list ne sera pas définie.

"INT_LIST"
Contrainte sur une liste spécifique de valeurs OptionType.INT. La propriété OptionConstraint.list contiendra des valeurs long, et les autres propriétés ne seront pas définies.

"FIXED_LIST"
Contrainte sur une liste spécifique de valeurs OptionType.FIXED. La propriété OptionConstraint.list contiendra des valeurs double, et les autres propriétés ne seront pas définies.

"STRING_LIST"
Contrainte sur une liste spécifique de valeurs OptionType.STRING. La propriété OptionConstraint.list contiendra des valeurs DOMString, et les autres propriétés ne seront pas définies.

DeviceFilter

Chrome 125 ou version ultérieure

Propriétés

• local

  boolean facultatif

  Ne renvoyer que les scanners directement connectés à l'ordinateur.

• sécurisé

  boolean facultatif

  Ne renvoie que les scanners qui utilisent un transport sécurisé, tel que USB ou TLS.

GetOptionGroupsResponse

Chrome 125 ou version ultérieure

Propriétés

• groupes

  OptionGroup[] facultatif

  Si result est défini sur SUCCESS, fournit une liste de groupes d'options dans l'ordre fourni par le pilote du scanner.

• résultat

  OperationResult

  Résultat de l'obtention des groupes d'options. Si la valeur est SUCCESS, la propriété groups sera renseignée.

• scannerHandle

  chaîne

  Le même handle de scanner que celui transmis à getOptionGroups.

GetScannerListResponse

Chrome 125 ou version ultérieure

Propriétés

• résultat

  OperationResult

  Résultat de l'énumération. Notez que des résultats partiels peuvent être renvoyés même si cela indique une erreur.

• scanners

  ScannerInfo[]

  Liste éventuellement vide de scanners correspondant au DeviceFilter fourni.

OpenScannerResponse

Chrome 125 ou version ultérieure

Propriétés

• options

  objet facultatif

  Si result est SUCCESS, fournit un mappage clé-valeur où la clé est une option spécifique à l'appareil et la valeur est une instance de ScannerOption.

• résultat

  OperationResult

  Résultat de l'ouverture du scanner. Si la valeur est SUCCESS, les propriétés scannerHandle et options seront renseignées.

• scannerHandle

  chaîne facultatif

  Si result est SUCCESS, un handle vers le scanner qui peut être utilisé pour d'autres opérations.

• scannerId

  chaîne

  ID du scanner transmis à openScanner().

OperationResult

Chrome 125 ou version ultérieure

Énumération indiquant le résultat de chaque opération.

Énumération

"UNKNOWN"
Une erreur inconnue ou générique s'est produite.

"SUCCESS"
L'opération a réussi.

"UNSUPPORTED"
L'opération n'est pas acceptée.

"CANCELLED"
L'opération a été annulée.

"DEVICE_BUSY"
L'appareil est occupé.

"INVALID"
Les données ou un argument transmis à la méthode ne sont pas valides.

"WRONG_TYPE"
La valeur fournie n'est pas du bon type de données pour l'option sous-jacente.

"EOF"
Aucune autre donnée n'est disponible.

"ADF_JAMMED"
Le chargeur de documents est bloqué.

"ADF_EMPTY"
Le chargeur de documents est vide.

"COVER_OPEN"
Le capot du scanner à plat est ouvert.

"IO_ERROR"
Une erreur s'est produite lors de la communication avec l'appareil.

"ACCESS_DENIED"
L'appareil nécessite une authentification.

"NO_MEMORY"
La mémoire disponible sur le Chromebook est insuffisante pour effectuer l'opération.

"UNREACHABLE"
L'appareil n'est pas accessible.

"MISSING"
L'appareil est déconnecté.

"INTERNAL_ERROR"
Une erreur s'est produite ailleurs que dans l'application appelante.

OptionConstraint

Chrome 125 ou version ultérieure

Propriétés

• list

  string[] | number[] facultatif

• max

  number facultatif

• min

  number facultatif

• quant

  number facultatif

• type

  ConstraintType

OptionGroup

Chrome 125 ou version ultérieure

Propriétés

• membres

  chaîne[]

  Tableau de noms d'options dans l'ordre fourni par le pilote.

• titre

  chaîne

  Fournit un titre imprimable, par exemple "Options de géométrie".

OptionSetting

Chrome 125 ou version ultérieure

Propriétés

• nom

  chaîne

  Indique le nom de l'option à définir.

• type

  OptionType

  Indique le type de données de l'option. Le type de données demandé doit correspondre au type de données réel de l'option sous-jacente.

• valeur

  string | number | boolean | number[] facultatif

  Indique la valeur à définir. Laissez ce champ vide pour demander la configuration automatique des options pour lesquelles autoSettable est activé. Le type de données fourni pour value doit correspondre à type.

OptionType

Chrome 125 ou version ultérieure

Type de données d'une option.

Énumération

"UNKNOWN"
Le type de données de l'option est inconnu. La propriété value sera désactivée.

"BOOL"
La propriété value sera l'une des valeurs truefalse.

"INT"
Entier signé de 32 bits. La propriété value sera de type long ou long[], selon que l'option accepte ou non plusieurs valeurs.

"FIXED"
Double dans la plage -32768-32767.9999 avec une résolution de 1/65535. La propriété value sera de type double ou double[] selon que l'option accepte ou non plusieurs valeurs. Les valeurs doubles qui ne peuvent pas être représentées exactement seront arrondies à la plage et à la précision disponibles.

"STRING"
Séquence d'octets, à l'exception de NUL ('\0'). La propriété value sera une DOMString.

"BUTTON"
Une option de ce type n'a pas de valeur. Au lieu de cela, la définition d'une option de ce type entraîne un effet secondaire spécifique à l'option dans le pilote du scanner. Par exemple, une option de type bouton peut être utilisée par un pilote de scanner pour permettre de sélectionner des valeurs par défaut ou pour indiquer à un chargeur automatique de documents de passer à la feuille de papier suivante.

"GROUP"
Option de regroupement. Aucune valeur. Il est inclus pour des raisons de compatibilité, mais n'est normalement pas renvoyé dans les valeurs ScannerOption. Utilisez getOptionGroups() pour récupérer la liste des groupes avec leurs options de membre.

OptionUnit

Chrome 125 ou version ultérieure

Indique le type de données pour ScannerOption.unit.

Énumération

"UNITLESS"
La valeur est un nombre sans unité. Par exemple, il peut s'agir d'un seuil.

"PIXEL"
La valeur est un nombre de pixels, par exemple les dimensions de numérisation.

"BIT"
La valeur correspond au nombre de bits, par exemple la profondeur de couleur.

"MM"
La valeur est mesurée en millimètres, par exemple les dimensions de numérisation.

"DPI"
La valeur est mesurée en points par pouce (par exemple, la résolution).

"PERCENT"
La valeur est un pourcentage, par exemple la luminosité.

"MICROSECOND"
La valeur est mesurée en microsecondes, par exemple le temps d'exposition.

ReadScanDataResponse

Chrome 125 ou version ultérieure

Propriétés

• données

  ArrayBuffer facultatif

  Si result est défini sur SUCCESS, contient le prochain fragment de données d'image scannées. Si result est défini sur EOF, contient le dernier fragment de données d'image scannées.

• estimatedCompletion

  number facultatif

  Si result est défini sur SUCCESS, une estimation de la quantité de données d'analyse totale qui a été fournie jusqu'à présent, comprise entre 0 et 100.

• job

  chaîne

  Fournit le handle de job transmis à readScanData().

• résultat

  OperationResult

  Résultat de la lecture des données. Si sa valeur est SUCCESS, data contient le prochain fragment de données d'image (éventuellement de longueur nulle) prêt à être lu. Si sa valeur est EOF, data contient le dernier fragment de données d'image.

ScannerInfo

Chrome 125 ou version ultérieure

Propriétés

• connectionType

  ConnectionType

  Indique comment le scanner est connecté à l'ordinateur.

• deviceUuid

  chaîne

  Pour la mise en correspondance avec d'autres entrées ScannerInfo qui pointent vers le même appareil physique.

• imageFormats

  chaîne[]

  Tableau de types MIME pouvant être demandés pour les analyses renvoyées.

• manufacturer

  chaîne

  Fabricant du scanner.

• modèle

  chaîne

  Le modèle du scanner s'il est disponible, ou une description générique.

• nom

  chaîne

  Nom du scanner lisible par l'humain à afficher dans l'interface utilisateur.

• protocolType

  chaîne

  Description lisible par l'humain du protocole ou du pilote utilisé pour accéder au scanner, par exemple Mopria, WSD ou epsonds. Cela est principalement utile pour permettre à un utilisateur de choisir entre plusieurs protocoles si un appareil en accepte plusieurs.

• scannerId

  chaîne

  ID d'un scanner spécifique.

• sécurisé

  booléen

  Si la valeur est "true", le transport de la connexion du lecteur ne peut pas être intercepté par un écouteur passif, tel que TLS ou USB.

ScannerOption

Chrome 125 ou version ultérieure

Propriétés

• configurabilité

  Configurabilité

  Indique si l'option peut être modifiée et comment.

• contrainte

  OptionConstraint facultatif

  Définit OptionConstraint sur l'option de scanner actuelle.

• description

  chaîne

  Une description plus longue de l'option.

• isActive

  booléen

  Indique que l'option est active et peut être définie ou récupérée. Si la valeur est "false", la propriété value n'est pas définie.

• isAdvanced

  booléen

  Indique que l'UI ne doit pas afficher cette option par défaut.

• isAutoSettable

  booléen

  Peut être défini automatiquement par le pilote du scanner.

• isDetectable

  booléen

  Indique que cette option peut être détectée par un logiciel.

• isEmulated

  booléen

  Émulé par le pilote du scanner si la valeur est "true".

• nom

  chaîne

  Nom de l'option, composé de lettres ASCII minuscules, de chiffres et de tirets. Les signes diacritiques ne sont pas autorisés.

• titre

  chaîne

  Un titre imprimable sur une seule ligne.

• type

  OptionType

  Type de données contenu dans la propriété value, nécessaire pour définir cette option.

• unité

  OptionUnit

  Unité de mesure de cette option.

• valeur

  string | number | boolean | number[] facultatif

  Valeur actuelle de l'option, le cas échéant. Notez que le type de données de cette propriété doit correspondre au type de données spécifié dans type.

ScanOptions

Propriétés

• maxImages

  number facultatif

  Nombre d'images scannées autorisées. La valeur par défaut est 1.

• mimeTypes

  string[] facultatif

  Types MIME acceptés par l'appelant.

ScanResults

Propriétés

• dataUrls

  chaîne[]

  Tableau d'URL d'images de données dans un format pouvant être transmis en tant que valeur "src" à un tag d'image.

• mimeType

  chaîne

  Type MIME de dataUrls.

SetOptionResult

Chrome 125 ou version ultérieure

Propriétés

• nom

  chaîne

  Indique le nom de l'option qui a été définie.

• résultat

  OperationResult

  Indique le résultat de la définition de l'option.

SetOptionsResponse

Chrome 125 ou version ultérieure

Propriétés

• options

  objet facultatif

  Mappage clé-valeur mis à jour des noms d'options aux valeurs ScannerOption contenant la nouvelle configuration après avoir tenté de définir toutes les options fournies. Cette propriété a la même structure que la propriété options dans OpenScannerResponse.

  Cette propriété sera définie même si certaines options n'ont pas été définies correctement, mais elle sera annulée si la récupération de la configuration mise à jour échoue (par exemple, si le scanner est déconnecté en cours d'analyse).

• résultats

  SetOptionResult[]

  Un tableau de résultats, un pour chaque OptionSetting transmis.

• scannerHandle

  chaîne

  Fournit le handle du scanner transmis à setOptions().

StartScanOptions

Chrome 125 ou version ultérieure

Propriétés

• format

  chaîne

  Spécifie le type MIME dans lequel renvoyer les données analysées.

• maxReadSize

  number facultatif

  Si une valeur non nulle est spécifiée, limite à cette valeur le nombre maximal d'octets analysés renvoyés dans une seule réponse readScanData. La plus petite valeur autorisée est 32768 (32 Ko). Si cette propriété n'est pas spécifiée, la taille d'un fragment renvoyé peut être aussi grande que l'image scannée entière.

StartScanResponse

Chrome 125 ou version ultérieure

Propriétés

• job

  chaîne facultatif

  Si result est défini sur SUCCESS, fournit un handle qui peut être utilisé pour lire les données d'analyse ou annuler le job.

• résultat

  OperationResult

  Résultat du démarrage d'une analyse. Si la valeur est SUCCESS, la propriété job sera renseignée.

• scannerHandle

  chaîne

  Fournit le même handle de scanner que celui transmis à startScan().

Méthodes

cancelScan()

Promise Chrome 125+

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

Annule une analyse démarrée et renvoie une promesse qui se résout avec un objet CancelScanResponse. Si un rappel est utilisé, l'objet lui est transmis à la place.

Paramètres

• job

  chaîne

  Handle d'un job d'analyse actif précédemment renvoyé par un appel à startScan.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: CancelScanResponse) => void

  • réponse

    CancelScanResponse

Renvoie

• Promise<CancelScanResponse>

  Renvoie une promesse qui se résout avec le résultat.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

closeScanner()

Promise Chrome 125+

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

Ferme le scanner avec le handle transmis et renvoie une promesse qui se résout avec un objet CloseScannerResponse. Si un rappel est utilisé, l'objet lui est transmis à la place. Même si la réponse n'est pas un succès, le handle fourni devient non valide et ne doit pas être utilisé pour d'autres opérations.

Paramètres

• scannerHandle

  chaîne

  Spécifie le handle d'un scanner ouvert qui a été précédemment renvoyé par un appel à openScanner.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: CloseScannerResponse) => void

  • réponse

    CloseScannerResponse

Renvoie

• Promise<CloseScannerResponse>

  Renvoie une promesse qui se résout avec le résultat.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getOptionGroups()

Promise Chrome 125+

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

Récupère les noms de groupes et les options de membres d'un scanner précédemment ouvert par openScanner. Cette méthode renvoie une promesse qui se résout avec un objet GetOptionGroupsResponse. Si un rappel est transmis à cette fonction, les données renvoyées lui sont transmises à la place.

Paramètres

• scannerHandle

  chaîne

  Handle d'un scanner ouvert renvoyé par un appel à openScanner.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: GetOptionGroupsResponse) => void

  • réponse

    GetOptionGroupsResponse

Renvoie

• Promise<GetOptionGroupsResponse>

  Renvoie une promesse qui se résout avec le résultat.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getScannerList()

Promise Chrome 125+

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

Récupère la liste des scanners disponibles et renvoie une promesse qui se résout avec un objet GetScannerListResponse. Si un rappel est transmis à cette fonction, les données renvoyées lui sont transmises à la place.

Paramètres

• filtre

  DeviceFilter

  Un DeviceFilter indiquant les types de scanners à renvoyer.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: GetScannerListResponse) => void

  • réponse

    GetScannerListResponse

Renvoie

• Promise<GetScannerListResponse>

  Renvoie une promesse qui se résout avec le résultat et la liste des scanners.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

openScanner()

Promise Chrome 125+

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

Ouvre un scanner pour un accès exclusif et renvoie une promesse qui se résout avec un objet OpenScannerResponse. Si un rappel est transmis à cette fonction, les données renvoyées lui sont transmises à la place.

Paramètres

• scannerId

  chaîne

  ID d'un scanner à ouvrir. Cette valeur est renvoyée par un appel précédent à getScannerList.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: OpenScannerResponse) => void

  • réponse

    OpenScannerResponse

Renvoie

• Promise<OpenScannerResponse>

  Renvoie une promesse qui se résout avec le résultat.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

readScanData()

Promise Chrome 125+

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

Lit le prochain fragment de données d'image disponible à partir d'un handle de job actif et renvoie une promesse qui se résout avec un objet ReadScanDataResponse. Si un rappel est utilisé, l'objet lui est transmis à la place.

**Remarque** : Un résultat de réponse peut être SUCCESS avec un membre data de longueur nulle. Cela signifie que le scanner est toujours en cours d'exécution, mais qu'il n'a pas encore de données supplémentaires prêtes. L'appelant doit patienter un court instant, puis réessayer.

Une fois le job d'analyse terminé, la réponse aura la valeur de résultat EOF. Cette réponse peut contenir un membre data final non nul.

Paramètres

• job

  chaîne

  Handle de job actif précédemment renvoyé par startScan.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: ReadScanDataResponse) => void

  • réponse

    ReadScanDataResponse

Renvoie

• Promise<ReadScanDataResponse>

  Renvoie une promesse qui se résout avec le résultat.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

scan()

Promise

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

Effectue une numérisation de document et renvoie une promesse qui se résout avec un objet ScanResults. Si un rappel est transmis à cette fonction, les données renvoyées lui sont transmises à la place.

Paramètres

• options

  ScanOptions

  Objet contenant les paramètres d'analyse.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (result: ScanResults) => void

  • résultat

    ScanResults

Renvoie

• Promise<ScanResults>

  Chrome 96 ou version ultérieure

  Renvoie une promesse qui se résout avec les résultats de l'analyse.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setOptions()

Promise Chrome 125+

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

Définit les options du scanner spécifié et renvoie une promesse qui se résout avec un objet SetOptionsResponse contenant le résultat de la tentative de définition de chaque valeur dans l'ordre de l'objet OptionSetting transmis. Si un rappel est utilisé, l'objet lui est transmis à la place.

Paramètres

• scannerHandle

  chaîne

  Handle du scanner sur lequel définir les options. Il doit s'agir d'une valeur précédemment renvoyée par un appel à openScanner.

• options

  OptionSetting[]

  Liste d'objets OptionSetting à appliquer au scanner.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: SetOptionsResponse) => void

  • réponse

    SetOptionsResponse

Renvoie

• Promise<SetOptionsResponse>

  Renvoie une promesse qui se résout avec le résultat.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

startScan()

Promise Chrome 125+

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

Lance une numérisation sur le scanner spécifié et renvoie une promesse qui se résout avec un StartScanResponse. Si un rappel est utilisé, l'objet lui est transmis à la place. Si l'appel aboutit, la réponse inclut un handle de job qui peut être utilisé dans les appels suivants pour lire les données d'analyse ou annuler une analyse.

Paramètres

• scannerHandle

  chaîne

  Le handle d'un scanner ouvert. Il doit s'agir d'une valeur précédemment renvoyée par un appel à openScanner.

• options

  StartScanOptions

  Un objet StartScanOptions indiquant les options à utiliser pour l'analyse. La propriété StartScanOptions.format doit correspondre à l'une des entrées renvoyées dans le ScannerInfo du scanner.

• callback

  function facultatif

  Le paramètre callback se présente comme suit :

  (response: StartScanResponse) => void

  • réponse

    StartScanResponse

Renvoie

• Promise<StartScanResponse>

  Renvoie une promesse qui se résout avec le résultat.

  Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.