chrome.documentScan (original) (raw)

Ir para o conteúdo principal

chrome.documentScan

Descrição

Use a API chrome.documentScan para descobrir e recuperar imagens de scanners de documentos anexados.

A API Document Scan foi projetada para permitir que apps e extensões vejam o conteúdo de documentos em papel em um scanner de documentos anexado.

Permissões

documentScan

Disponibilidade

Chrome 44 ou mais recente Somente no ChromeOS

A disponibilidade dos membros da API adicionados depois é mostrada com eles.

Conceitos e uso

Essa API aceita duas formas de digitalizar documentos. Se o caso de uso funcionar com qualquer scanner e não exigir controle da configuração, use o métodoscan(). Casos de uso mais complicados exigem uma combinação de métodos, que só são compatíveis com o Chrome 124 e versões mais recentes.

Leitura simples

Para casos de uso simples, ou seja, aqueles que podem funcionar com qualquer scanner e não exigem controle de configuração, chame scan(). Esse método usa um objetoScanOptions e retorna uma promessa que é resolvida com um objeto ScanResults. As funcionalidades dessa opção são limitadas ao número de verificações e aos tipos MIME que serão aceitos pelo caller. As verificações são retornadas como URLs para exibição em uma tag <img> de uma interface do usuário.

Verificação complexa

As verificações complexas são realizadas em três fases, conforme descrito nesta seção. Este resumo não descreve todos os argumentos de método ou todas as propriedades retornadas em uma resposta. Ele tem apenas o objetivo de fornecer um guia geral para escrever código do scanner.

Discovery

  1. Chame getScannerList(). Os scanners disponíveis são retornados em uma promessa que é resolvida com umGetScannerListResponse.
    • O objeto de resposta contém uma matriz de objetos ScannerInfo.
    • A matriz pode conter várias entradas para um único scanner se ele for compatível com vários protocolos ou métodos de conexão.
  2. Selecione um scanner na matriz retornada e salve o valor da propriedadescannerId.
    Use as propriedades de objetos ScannerInfo individuais para distinguir entre vários objetos do mesmo scanner. Objetos do mesmo scanner têm o mesmo valor para a propriedade deviceUuid.ScannerInfo também contém uma propriedade imageFormats com uma matriz de tipos de imagem aceitos.

Configuração do scanner

  1. Chame openScanner(), transmitindo o ID do scanner salvo. Ela retorna uma promessa que é resolvida com um OpenScannerResponse. O objeto de resposta contém:
    • Uma propriedade scannerHandle, que você precisará salvar.
    • Uma propriedade de opções que contém propriedades específicas do scanner, que você precisa definir. Consulte "Recuperar opções de scanner" para mais informações.
  2. (Opcional) Se você precisar que o usuário forneça valores para as opções do scanner, crie uma interface do usuário. Você vai precisar das opções de scanner fornecidas na etapa anterior e recuperar os grupos de opções fornecidos pelo scanner. Consulte Construir uma interface do usuário para mais informações.
  3. Construa uma matriz de objetos OptionSetting usando valores programáticos ou fornecidos pelo usuário. Consulte "Definir opções do scanner" para mais informações.
  4. Transmita a matriz de objetos OptionSetting parasetOptions() para definir opções para o scanner. Ela retorna uma promessa que é resolvida com umSetOptionsResponse. Esse objeto contém uma versão atualizada das opções do scanner recuperadas na etapa 1 da configuração do scanner.
    Como a mudança de uma opção pode alterar as restrições de outra, talvez seja necessário repetir essas etapas várias vezes.

Verificação

  1. Crie um objeto StartScanOptions e transmita-o para startScan(). Ele retorna uma promessa que é resolvida com um StartScanResponse. A propriedade job é um identificador que você vai usar para ler os dados de verificação ou cancelar a verificação.
  2. Transmita o handle do job para readScanData(). Ele retorna uma promessa que é resolvida com um objeto ReadScanDataResponse. Se os dados forem lidos com sucesso, a propriedade result será igual a SUCCESS e a propriedade dataconterá umArrayBuffercom parte da verificação. estimatedCompletion contém uma porcentagem estimada do total de dados entregues até o momento.
  3. Repita a etapa anterior até que a propriedade result seja igual a EOF ou um erro.

Quando o fim da verificação for alcançado, chamecloseScanner() com o identificador do scanner salvo na etapa 3. Ela retorna uma promessa que é resolvida com umCloseScannerResponse. ChamarcancelScan() a qualquer momento após a criação do job encerra a verificação.

Objetos de resposta

Todos os métodos retornam uma promessa que é resolvida com um objeto de resposta de algum tipo. A maioria deles contém uma propriedade result cujo valor é um membro de OperationResult. Algumas propriedades de objetos de resposta não contêm valores, a menos que o valor de result seja específico. Essas relações são descritas na referência de cada objeto de resposta.

Por exemplo, OpenScannerResponse.scannerHandle só terá um valor quando OpenScannerResponse.result for igual a SUCCESS.

Opções do scanner

As opções de scanner variam muito de acordo com o dispositivo. Por isso, não é possível refletir as opções do scanner diretamente na API documentScan. Para evitar isso, o OpenScannerResponse (recuperado usando openScanner()) e o SetOptionsResponse (o objeto de resposta para setOptions()) contêm uma propriedade options, que é um objeto com opções específicas do scanner. Cada opção é um mapeamento de chave-valor em que a chave é uma opção específica do dispositivo e o valor é uma instância de ScannerOption.

A estrutura geralmente é assim:

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

Por exemplo, imagine um scanner que retorna opções chamadas "source" e "resolution". A estrutura do objeto options retornado será semelhante ao exemplo a seguir. Para simplificar, apenas respostas parciais de ScannerOption são mostradas.

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

Construir uma interface do usuário

Embora não seja necessário para usar essa API, talvez você queira que um usuário escolha o valor de uma opção específica. Isso exige uma interface do usuário. Use oOpenScannerResponse (aberto poropenScanner()) para recuperar as opções do scanner conectado, conforme descrito na seção anterior.

Alguns scanners agrupam opções de maneiras específicas para cada dispositivo. Eles não afetam os comportamentos das opções, mas, como esses grupos podem ser mencionados na documentação do produto de um scanner, eles precisam ser mostrados ao usuário. É possível extrair esses grupos chamando getOptionGroups(). Isso retorna uma promessa que é resolvida com um objeto GetOptionGroupsResponse. A propriedade groupscontém uma matriz de grupos específica do scanner. Use as informações desses grupos para organizar as opções no OpenScannerResponse para exibição.

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

Conforme declarado em "Configuração do scanner", mudar uma opção pode alterar as restrições de outra. Por isso, setOptionsResponse (o objeto de resposta para setOptions()) contém outra propriedade options. Use isso para atualizar a interface do usuário. Repita conforme necessário até que todas as opções sejam definidas.

Definir opções do scanner

Defina as opções do scanner transmitindo uma matriz de objetosOptionSetting parasetOptions(). Por exemplo, consulte a seção Digitalizar uma página de tamanho carta.

Exemplos

Recuperar uma página como um blob

Este exemplo mostra uma maneira de recuperar uma página do scanner como um blob e demonstra o uso de startScan() e readScanData() usando o valor de OperationResult.

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" });
}

Digitalizar uma página de tamanho carta

Este exemplo mostra como selecionar, definir opções e abrir um scanner. Em seguida, ele recupera o conteúdo de uma única página e fecha o scanner. Esse processo demonstra o uso de getScannerList(), openScanner(), setOptions() ecloseScanner(). O conteúdo da página é recuperado chamando a função pageAsBlob() do exemplo anterior.

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);
}

Mostrar a configuração

Como afirmado em outro lugar, mostrar as opções de configuração de um scanner a um usuário exige chamar getOptionGroups(), além das opções de scanner retornadas de uma chamada para openScanner(). Assim, as opções podem ser mostradas aos usuários em grupos definidos pelo fabricante. Este exemplo mostra como fazer isso.

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");
      }
    }
  }
}

Tipos

CancelScanResponse

Chrome 125 ou mais recente

Propriedades

CloseScannerResponse

Chrome 125 ou mais recente

Propriedades

Configurability

Chrome 125 ou mais recente

Como uma opção pode ser mudada.

Enumeração

"NOT_CONFIGURABLE"
A opção é somente leitura.

"SOFTWARE_CONFIGURABLE"
A opção pode ser definida no software.

"HARDWARE_CONFIGURABLE"
A opção pode ser definida pelo usuário ao alternar ou pressionar um botão no scanner.

ConnectionType

Chrome 125 ou mais recente

Indica como o scanner está conectado ao computador.

Enumeração

"UNSPECIFIED"

"USB"

"NETWORK"

ConstraintType

Chrome 125 ou mais recente

O tipo de dados da restrição representada por um OptionConstraint.

Enumeração

"INT_RANGE"
A restrição em um intervalo de valores OptionType.INT. As propriedades min, max e quant de OptionConstraint serão long, e a propriedade list será desdefinida.

"FIXED_RANGE"
A restrição em um intervalo de valores OptionType.FIXED. As propriedades min, max e quant de OptionConstraint serão double, e a propriedade list será desdefinida.

"INT_LIST"
A restrição em uma lista específica de valores OptionType.INT. A propriedade OptionConstraint.list vai conter valores long, e as outras propriedades não serão definidas.

"FIXED_LIST"
A restrição em uma lista específica de valores OptionType.FIXED. A propriedade OptionConstraint.list vai conter valores double, e as outras propriedades não serão definidas.

"STRING_LIST"
A restrição em uma lista específica de valores OptionType.STRING. A propriedade OptionConstraint.list vai conter valores DOMString, e as outras propriedades não serão definidas.

DeviceFilter

Chrome 125 ou mais recente

Propriedades

GetOptionGroupsResponse

Chrome 125 ou mais recente

Propriedades

GetScannerListResponse

Chrome 125 ou mais recente

Propriedades

OpenScannerResponse

Chrome 125 ou mais recente

Propriedades

OperationResult

Chrome 125 ou mais recente

Um enum que indica o resultado de cada operação.

Enumeração

"UNKNOWN"
Ocorreu uma falha desconhecida ou genérica.

"SUCCESS"
A operação foi concluída.

"UNSUPPORTED"
A operação não é compatível.

"CANCELLED"
A operação foi cancelada.

"DEVICE_BUSY"
O dispositivo está ocupado.

"INVALID"
Os dados ou um argumento transmitido ao método não são válidos.

"WRONG_TYPE"
O valor fornecido é do tipo de dados errado para a opção subjacente.

"EOF"
Não há mais dados disponíveis.

"ADF_JAMMED"
O alimentador de documentos está obstruído.

"ADF_EMPTY"
O alimentador de documentos está vazio.

"COVER_OPEN"
A tampa do scanner de mesa está aberta.

"IO_ERROR"
Ocorreu um erro ao se comunicar com o dispositivo.

"ACCESS_DENIED"
O dispositivo exige autenticação.

"NO_MEMORY"
Não há memória suficiente disponível no Chromebook para concluir a operação.

"UNREACHABLE"
Não é possível acessar o dispositivo.

"MISSING"
O dispositivo está desconectado.

"INTERNAL_ERROR"
Ocorreu um erro em algum lugar que não seja o aplicativo de chamada.

OptionConstraint

Chrome 125 ou mais recente

Propriedades

OptionGroup

Chrome 125 ou mais recente

Propriedades

OptionSetting

Chrome 125 ou mais recente

Propriedades

OptionType

Chrome 125 ou mais recente

O tipo de dados de uma opção.

Enumeração

"UNKNOWN"
O tipo de dados da opção é desconhecido. A propriedade value será desdefinida.

"BOOL"
A propriedade value será uma das truefalse.

"INT"
Um número inteiro assinado de 32 bits. A propriedade value será "long" ou "long[]", dependendo de a opção aceitar mais de um valor.

"FIXED"
Um ponto flutuante de precisão dupla no intervalo -32768 a 32767,9999 com uma resolução de 1/65535. A propriedade value será double ou double[], dependendo se a opção aceita mais de um valor. Valores de ponto flutuante de precisão dupla que não podem ser representados exatamente serão arredondados para o intervalo e a precisão disponíveis.

"STRING"
Uma sequência de bytes, exceto NUL ('\0'). A propriedade value será uma DOMString.

"BUTTON"
Uma opção desse tipo não tem valor. Em vez disso, definir uma opção desse tipo causa um efeito colateral específico da opção no driver do scanner. Por exemplo, uma opção do tipo botão pode ser usada por um driver de scanner para selecionar valores padrão ou para dizer a um alimentador automático de documentos que avance para a próxima folha de papel.

"GROUP"
Opção de agrupamento. Nenhum valor. Isso é incluído para compatibilidade, mas normalmente não é retornado em valores ScannerOption. Use getOptionGroups() para recuperar a lista de grupos com as opções de participantes.

OptionUnit

Chrome 125 ou mais recente

Indica o tipo de dados de ScannerOption.unit.

Enumeração

"UNITLESS"
O valor é um número sem unidade. Por exemplo, pode ser um limite.

"PIXEL"
O valor é um número de pixels, por exemplo, dimensões de varredura.

"BIT"
O valor é o número de bits, por exemplo, a profundidade de cor.

"MM"
O valor é medido em milímetros, por exemplo, dimensões de varredura.

"DPI"
O valor é medido em pontos por polegada, por exemplo, resolução.

"PERCENT"
O valor é uma porcentagem, por exemplo, brilho.

"MICROSECOND"
O valor é medido em microssegundos, por exemplo, tempo de exposição.

ReadScanDataResponse

Chrome 125 ou mais recente

Propriedades

ScannerInfo

Chrome 125 ou mais recente

Propriedades

ScannerOption

Chrome 125 ou mais recente

Propriedades

ScanOptions

Propriedades

ScanResults

Propriedades

SetOptionResult

Chrome 125 ou mais recente

Propriedades

SetOptionsResponse

Chrome 125 ou mais recente

Propriedades

StartScanOptions

Chrome 125 ou mais recente

Propriedades

StartScanResponse

Chrome 125 ou mais recente

Propriedades

Métodos

cancelScan()

Chrome 125 ou mais recente

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

Cancela uma verificação iniciada e retorna uma promessa que é resolvida com um objeto CancelScanResponse. Se um callback for usado, o objeto será transmitido a ele.

Parâmetros

Retorna

closeScanner()

Chrome 125 ou mais recente

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

Fecha o scanner com o identificador transmitido e retorna uma promessa que é resolvida com um objeto CloseScannerResponse. Se um callback for usado, o objeto será transmitido a ele. Mesmo que a resposta não seja um sucesso, o identificador fornecido se torna inválido e não deve ser usado para outras operações.

Parâmetros

Retorna

getOptionGroups()

Chrome 125 ou mais recente

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

Recebe os nomes dos grupos e as opções de membros de um scanner aberto anteriormente por openScanner. Esse método retorna uma promessa que é resolvida com um objeto GetOptionGroupsResponse. Se um callback for transmitido a essa função, os dados retornados serão transmitidos a ele.

Parâmetros

Retorna

getScannerList()

Chrome 125 ou mais recente

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

Recebe a lista de scanners disponíveis e retorna uma promessa que é resolvida com um objeto GetScannerListResponse. Se um callback for transmitido a essa função, os dados retornados serão transmitidos a ele.

Parâmetros

Retorna

openScanner()

Chrome 125 ou mais recente

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

Abre um scanner para acesso exclusivo e retorna uma promessa que é resolvida com um objeto OpenScannerResponse. Se um callback for transmitido a essa função, os dados retornados serão transmitidos a ele.

Parâmetros

Retorna

readScanData()

Chrome 125 ou mais recente

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

Lê o próximo bloco de dados de imagem disponíveis de um identificador de job ativo e retorna uma promessa que é resolvida com um objeto ReadScanDataResponse. Se um callback for usado, o objeto será transmitido a ele.

**Observação**: é válido que um resultado de resposta seja SUCCESS com um membro data de comprimento zero. Isso significa que o scanner ainda está funcionando, mas ainda não tem dados adicionais prontos. A pessoa que está ligando precisa esperar um pouco e tentar de novo.

Quando o job de verificação for concluído, a resposta terá o valor do resultado EOF. Essa resposta pode conter um membro data final diferente de zero.

Parâmetros

Retorna

scan()

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

Realiza uma verificação de documento e retorna uma promessa que é resolvida com um objeto ScanResults. Se um callback for transmitido a essa função, os dados retornados serão transmitidos a ele.

Parâmetros

Retorna

setOptions()

Chrome 125 ou mais recente

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

Define opções no scanner especificado e retorna uma promessa que é resolvida com um objeto SetOptionsResponse contendo o resultado da tentativa de definir cada valor na ordem do objeto OptionSetting transmitido. Se um callback for usado, o objeto será transmitido a ele.

Parâmetros

Retorna

startScan()

Chrome 125 ou mais recente

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

Inicia uma verificação no scanner especificado e retorna uma promessa que é resolvida com um StartScanResponse. Se um callback for usado, o objeto será transmitido a ele. Se a chamada for bem-sucedida, a resposta vai incluir um identificador de job que pode ser usado em chamadas subsequentes para ler dados de verificação ou cancelar uma verificação.

Parâmetros

Retorna

Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.

Última atualização 2025-09-15 UTC.