browser.downloads

Descrição

Use a API chrome.downloads para iniciar, monitorar, manipular e pesquisar downloads de forma programática.

Permissões

downloads

É necessário declarar a permissão "downloads" no manifesto da extensão para usar essa API.

{
  "name": "My extension",
  ...
  "permissions": [
    "downloads"
  ],
}

Exemplos

Confira exemplos simples de uso da API browser.downloads no diretório examples/api/downloads. Para ver outros exemplos e receber ajuda para visualizar o código-fonte, consulte Exemplos.

Tipos

BooleanDelta

Propriedades

  • atual

    booleano opcional

  • anterior

    booleano opcional

DangerType

Enumeração

"file"
O nome do arquivo do download é suspeito.

"url"
O URL do download é conhecido como malicioso.

"content"
O arquivo baixado é conhecido por ser malicioso.

"uncommon"
O URL do download não é comum e pode ser perigoso.

"host"
O download veio de um host conhecido por distribuir binários maliciosos e provavelmente é perigoso.

"unwanted"
O download é potencialmente indesejado ou não seguro. Por exemplo, ele pode fazer mudanças nas configurações do navegador ou do computador.

"safe"
O download não apresenta perigo conhecido para o computador do usuário.

"accepted"
O usuário aceitou o download perigoso.

"allowlistedByPolicy"
Valores relacionados à empresa.

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

"forceSaveToGdrive"
Para uso pela extensão do navegador seguro para empresas. Quando necessário, o Chrome vai bloquear o download para o disco e baixar o arquivo diretamente no Google Drive.

"forceSaveToOnedrive"
Para uso pela extensão do navegador empresarial seguro. Quando necessário, o Chrome vai bloquear o download para o disco e baixar o arquivo diretamente no OneDrive.

DoubleDelta

Propriedades

  • atual

    número optional

  • anterior

    número optional

DownloadDelta

Propriedades

  • canResume

    BooleanDelta opcional

    A mudança em canResume, se houver.

  • perigo

    StringDelta opcional

    A mudança em danger, se houver.

  • endTime

    StringDelta opcional

    A mudança em endTime, se houver.

  • erro

    StringDelta opcional

    A mudança em error, se houver.

  • existe

    BooleanDelta opcional

    A mudança em exists, se houver.

  • fileSize

    DoubleDelta opcional

    A mudança em fileSize, se houver.

  • filename

    StringDelta opcional

    A mudança em filename, se houver.

  • finalUrl

    StringDelta opcional

    Chrome 54+ browser.* desde o Chrome 148

    A mudança em finalUrl, se houver.

  • ID

    número

    O id do DownloadItem que mudou.

  • mímica

    StringDelta opcional

    A mudança em mime, se houver.

  • pausado

    BooleanDelta opcional

    A mudança em paused, se houver.

  • startTime

    StringDelta opcional

    A mudança em startTime, se houver.

  • estado

    StringDelta opcional

    A mudança em state, se houver.

  • totalBytes

    DoubleDelta opcional

    A mudança em totalBytes, se houver.

  • url

    StringDelta opcional

    A mudança em url, se houver.

DownloadItem

Propriedades

  • byExtensionId

    string opcional

    O identificador da extensão que iniciou o download, se esse for o caso. Não muda depois de definido.

  • byExtensionName

    string opcional

    O nome localizado da extensão que iniciou o download, se for o caso. Pode mudar se a extensão mudar de nome ou se o usuário mudar de localidade.

  • bytesReceived

    número

    Número de bytes recebidos até o momento do host, sem considerar a compactação de arquivos.

  • canResume

    booleano

    Verdadeiro se o download estiver em andamento e pausado ou se for interrompido e puder ser retomado de onde parou.

  • perigo

    Indicação de que o download é considerado seguro ou suspeito.

  • endTime

    string opcional

    O horário em que o download terminou no formato ISO 8601. Pode ser transmitido diretamente para o construtor de data: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

  • erro

    InterruptReason opcional

    Por que o download foi interrompido. Vários tipos de erros de HTTP podem ser agrupados em um dos erros que começam com SERVER_. Os erros relacionados à rede começam com NETWORK_, os relacionados ao processo de gravação do arquivo no sistema de arquivos começam com FILE_ e as interrupções iniciadas pelo usuário começam com USER_.

  • estimatedEndTime

    string opcional

    Tempo estimado para a conclusão do download no formato ISO 8601. Pode ser transmitido diretamente para o construtor de data: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

  • existe

    booleano

    Se o arquivo baixado ainda existe. Essas informações podem estar desatualizadas porque o Chrome não monitora automaticamente a remoção de arquivos. Chame search() para acionar a verificação de existência do arquivo. Quando a verificação de existência for concluída, se o arquivo tiver sido excluído, um evento onChanged será acionado. O método search() não espera a conclusão da verificação de existência antes de retornar. Por isso, os resultados de search() podem não refletir com precisão o sistema de arquivos. Além disso, search() pode ser chamado quantas vezes forem necessárias, mas não vai verificar a existência do arquivo mais de uma vez a cada 10 segundos.

  • fileSize

    número

    Número de bytes em todo o arquivo após a descompactação ou -1 se for desconhecido.

  • filename

    string

    Caminho local absoluto.

  • finalUrl

    string

    Chrome 54+ browser.* desde o Chrome 148

    O URL absoluto de onde o download está sendo feito, após todos os redirecionamentos.

  • ID

    número

    Um identificador que é persistente entre as sessões do navegador.

  • incognito

    booleano

    Falso se o download estiver registrado no histórico, verdadeiro se não estiver.

  • mímica

    string

    O tipo MIME do arquivo.

  • pausado

    booleano

    Verdadeiro se o download parou de ler dados do host, mas manteve a conexão aberta.

  • referenciador

    string

    URL absoluto.

  • startTime

    string

    O horário em que o download começou no formato ISO 8601. Pode ser transmitido diretamente para o construtor de data: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • estado

    Indica se o download está em andamento, interrompido ou concluído.

  • totalBytes

    número

    Número de bytes no arquivo inteiro, sem considerar a compactação de arquivos, ou -1 se for desconhecido.

  • url

    string

    O URL absoluto de onde o download foi iniciado, antes de qualquer redirecionamento.

DownloadOptions

Propriedades

  • body

    string opcional

    Corpo da postagem.

  • conflictAction

    A ação a ser realizada se filename já existir.

  • filename

    string opcional

    Um caminho de arquivo relativo ao diretório de downloads para conter o arquivo baixado, possivelmente com subdiretórios. Caminhos absolutos, vazios e que contêm referências anteriores ".." vão causar um erro. onDeterminingFilename permite sugerir um nome de arquivo depois que o tipo MIME do arquivo e um nome de arquivo provisório forem determinados.

  • cabeçalhos

    Cabeçalhos HTTP extras a serem enviados com a solicitação se o URL usar o protocolo HTTP[s]. Cada cabeçalho é representado como um dicionário que contém as chaves name e value ou binaryValue, restritas às permitidas pelo XMLHttpRequest.

  • método

    HttpMethod opcional

    O método HTTP a ser usado se o URL usar o protocolo HTTP[S].

  • saveAs

    booleano opcional

    Use um seletor de arquivos para permitir que o usuário selecione um nome de arquivo, independentemente de filename estar definido ou já existir.

  • url

    string

    O URL para download.

DownloadQuery

Propriedades

  • bytesReceived

    número optional

    Número de bytes recebidos até o momento do host, sem considerar a compactação de arquivos.

  • perigo

    DangerType opcional

    Indicação de que o download é considerado seguro ou suspeito.

  • endTime

    string opcional

    O horário em que o download terminou no formato ISO 8601.

  • endedAfter

    string opcional

    Limita os resultados a DownloadItem que terminaram após os milissegundos informados no formato ISO 8601.

  • endedBefore

    string opcional

    Limita os resultados a DownloadItem que terminaram antes do milissegundo informado no formato ISO 8601.

  • erro

    InterruptReason opcional

    Por que um download foi interrompido.

  • existe

    booleano opcional

    Se o arquivo baixado existe.

  • fileSize

    número optional

    Número de bytes em todo o arquivo após a descompactação ou -1 se for desconhecido.

  • filename

    string opcional

    Caminho local absoluto.

  • filenameRegex

    string opcional

    Limita os resultados a DownloadItem cujo filename corresponde à expressão regular fornecida.

  • finalUrl

    string opcional

    Chrome 54+ browser.* desde o Chrome 148

    O URL absoluto de onde o download está sendo feito, após todos os redirecionamentos.

  • finalUrlRegex

    string opcional

    Chrome 54+ browser.* desde o Chrome 148

    Limita os resultados a DownloadItem cujo finalUrl corresponde à expressão regular fornecida.

  • ID

    número optional

    O id do DownloadItem a ser consultado.

  • limite

    número optional

    O número máximo de DownloadItem correspondentes retornados. O valor padrão é 1.000. Defina como 0 para retornar todos os DownloadItem correspondentes. Consulte search para saber como percorrer as páginas dos resultados.

  • mímica

    string opcional

    O tipo MIME do arquivo.

  • orderBy

    string[] opcional

    Defina os elementos dessa matriz como propriedades DownloadItem para classificar os resultados da pesquisa. Por exemplo, definir orderBy=['startTime'] classifica os DownloadItem pelo horário de início em ordem crescente. Para especificar a ordem decrescente, use um hífen como prefixo: "-startTime".

  • pausado

    booleano opcional

    Verdadeiro se o download parou de ler dados do host, mas manteve a conexão aberta.

  • consulta

    string[] opcional

    Essa matriz de termos de pesquisa limita os resultados a DownloadItem em que filename, url ou finalUrl contêm todos os termos de pesquisa que não começam com um traço "-" e nenhum dos termos de pesquisa que começam com um traço.

  • startTime

    string opcional

    O horário em que o download começou no formato ISO 8601.

  • startedAfter

    string opcional

    Limita os resultados a DownloadItem que começaram após os milissegundos fornecidos no formato ISO 8601.

  • startedBefore

    string opcional

    Limita os resultados a DownloadItem que começaram antes do milissegundo fornecido no formato ISO 8601.

  • estado

    Estado opcional

    Indica se o download está em andamento, interrompido ou concluído.

  • totalBytes

    número optional

    Número de bytes no arquivo inteiro, sem considerar a compactação de arquivos, ou -1 se for desconhecido.

  • totalBytesGreater

    número optional

    Limita os resultados a DownloadItem em que totalBytes é maior que o número inteiro fornecido.

  • totalBytesLess

    número optional

    Limita os resultados a DownloadItem em que totalBytes é menor que o número inteiro fornecido.

  • url

    string opcional

    O URL absoluto de onde o download foi iniciado, antes de qualquer redirecionamento.

  • urlRegex

    string opcional

    Limita os resultados a DownloadItem cujo url corresponde à expressão regular fornecida.

FilenameConflictAction

uniquify

Para evitar duplicação, o filename é alterado para incluir um contador antes da extensão do nome do arquivo.

substituir

O arquivo atual será substituído pelo novo.

comando

Uma caixa de diálogo de seleção de arquivos será mostrada ao usuário.

Enumeração

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

Propriedades

  • conflictAction

    A ação a ser realizada se filename já existir.

  • filename

    string

    O novo destino DownloadItem.filename do DownloadItem, como um caminho relativo ao diretório de downloads padrão do usuário, possivelmente contendo subdiretórios. Caminhos absolutos, vazios e que contêm referências anteriores ".." serão ignorados. filename será ignorado se houver listeners onDeterminingFilename registrados por alguma extensão.

GetFileIconOptions

Propriedades

  • tamanho

    número optional

    O tamanho do ícone retornado em pixels independentes de densidade (DIPs). Precisa ser 16 ou 32 (o padrão é 32). Em telas de alta DPI, a imagem retornada é dimensionada de acordo com o fator de escalonamento do dispositivo (por exemplo, 64 x 64 px para o tamanho 32 em uma tela de 2x). As chamadas de service workers em segundo plano usam a escala de 1x por padrão.

HeaderNameValuePair

Propriedades

  • nome

    string

    Nome do cabeçalho HTTP.

  • valor

    string

    Valor do cabeçalho HTTP.

HttpMethod

Enumeração

"GET"

"POST"

InterruptReason

Enumeração

"FILE_FAILED"

"FILE_ACCESS_DENIED"

"FILE_NO_SPACE"

"FILE_NAME_TOO_LONG"

"FILE_TOO_LARGE"

"FILE_VIRUS_INFECTED"

"FILE_TRANSIENT_ERROR"

"FILE_BLOCKED"

"FILE_SECURITY_CHECK_FAILED"

"FILE_TOO_SHORT"

"FILE_HASH_MISMATCH"

"FILE_SAME_AS_SOURCE"

"NETWORK_FAILED"

"NETWORK_TIMEOUT"

"NETWORK_DISCONNECTED"

"NETWORK_SERVER_DOWN"

"NETWORK_INVALID_REQUEST"

"SERVER_FAILED"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"SERVER_UNAUTHORIZED"

"SERVER_CERT_PROBLEM"

"SERVER_FORBIDDEN"

"SERVER_UNREACHABLE"

"SERVER_CONTENT_LENGTH_MISMATCH"

"SERVER_CROSS_ORIGIN_REDIRECT"

"USER_CANCELED"

"USER_SHUTDOWN"

"CRASH"

State

in_progress

O download está recebendo dados do servidor.

interrompido

Um erro interrompeu a conexão com o host do arquivo.

complete

O download foi concluído.

Enumeração

"in_progress"

"interrupted"

"complete"

StringDelta

Propriedades

  • atual

    string opcional

  • anterior

    string opcional

UiOptions

Chrome 105+ browser.* desde o Chrome 148

Propriedades

  • ativado

    booleano

    Ativar ou desativar a interface de download.

Métodos

acceptDanger()

browser.downloads.acceptDanger(
  downloadId: number,
)
: Promise<void>

Solicitar que o usuário aceite um download perigoso. Só pode ser chamado em um contexto visível (guia, janela ou pop-up de ação de página/navegador). Não aceita downloads perigosos automaticamente. Se o download for aceito, um evento onChanged será disparado. Caso contrário, nada vai acontecer. Quando todos os dados são buscados em um arquivo temporário e o download não é perigoso ou o perigo foi aceito, o arquivo temporário é renomeado para o nome de arquivo de destino, o state muda para "complete" e onChanged é acionado.

Parâmetros

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando a caixa de diálogo de perigo é fechada.

cancel()

browser.downloads.cancel(
  downloadId: number,
)
: Promise<void>

Cancelar um download. Quando callback é executado, o download é cancelado, concluído, interrompido ou não existe mais.

Parâmetros

  • downloadId

    número

    O ID do download a ser cancelado.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando o pedido de cancelamento é concluído.

download()

browser.downloads.download(
  options: DownloadOptions,
)
: Promise<number>

Fazer o download de um URL. Se o URL usar o protocolo HTTP[S], a solicitação vai incluir todos os cookies definidos para o nome do host. Se filename e saveAs forem especificados, a caixa de diálogo "Salvar como" será exibida, pré-preenchida com o filename especificado. Se o download for iniciado, callback será chamado com o downloadId do novo DownloadItem. Se houver um erro ao iniciar o download, callback será chamado com downloadId=undefined, e runtime.lastError vai conter uma string descritiva. Não há garantia de que as strings de erro vão permanecer compatíveis com versões anteriores entre as versões. As extensões não podem analisá-lo.

Parâmetros

Retorna

  • Promise<number>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida com o ID do novo DownloadItem.

erase()

browser.downloads.erase(
  query: DownloadQuery,
)
: Promise<number[]>

Apaga o DownloadItem correspondente do histórico sem excluir o arquivo baixado. Um evento onErased será disparado para cada DownloadItem que corresponder a query, e callback será chamado.

Parâmetros

Retorna

  • Promise<number[]>

    Chrome 96+ browser.* desde o Chrome 148

getFileIcon()

browser.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
)
: Promise<string | undefined>

Recupera um ícone para o download especificado. Para novos downloads, os ícones de arquivo ficam disponíveis depois que o nome do arquivo de destino do download é determinado (por exemplo, quando onChanged é acionado com uma mudança de filename). Tentar recuperar o ícone antes que o nome de arquivo seja determinado vai resultar em um erro por meio de runtime.lastError. A imagem retornada por essa função enquanto um download está em andamento pode ser diferente da imagem retornada após a conclusão do download. A recuperação de ícones é feita consultando o sistema operacional ou o kit de ferramentas subjacente, dependendo da plataforma. Portanto, o ícone retornado depende de vários fatores, incluindo o estado do download, a plataforma, os tipos de arquivo registrados e o tema visual. Se não for possível determinar um ícone de arquivo, runtime.lastError vai conter uma mensagem de erro.

Parâmetros

Retorna

  • Promise<string | undefined>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida com um URL para uma imagem que representa o download.

open()

browser.downloads.open(
  downloadId: number,
)
: Promise<void>

Abre o arquivo baixado se o DownloadItem estiver concluído. Caso contrário, retorna um erro por meio de runtime.lastError. Esse método requer a permissão "downloads.open", além da permissão "downloads". Um evento onChanged é acionado quando o item é aberto pela primeira vez. Esse método só pode ser chamado em resposta a uma interação inicial.

Parâmetros

  • downloadId

    número

    O identificador do arquivo baixado.

Retorna

  • Promessa<void>

    Chrome 123+ browser.* desde o Chrome 148

pause()

browser.downloads.pause(
  downloadId: number,
)
: Promise<void>

Pausar o download. Se a solicitação foi bem-sucedida, o download está em um estado pausado. Caso contrário, runtime.lastError vai conter uma mensagem de erro. A solicitação vai falhar se o download não estiver ativo.

Parâmetros

  • downloadId

    número

    O ID do download que será pausado.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando a solicitação de pausa é concluída.

removeFile()

browser.downloads.removeFile(
  downloadId: number,
)
: Promise<void>

Remova o arquivo baixado, se ele existir, e o DownloadItem estiver concluído. Caso contrário, retorne um erro por meio de runtime.lastError.

Parâmetros

  • downloadId

    número

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

resume()

browser.downloads.resume(
  downloadId: number,
)
: Promise<void>

Retomar um download pausado. Se a solicitação foi bem-sucedida, o download está em andamento e não está pausado. Caso contrário, runtime.lastError vai conter uma mensagem de erro. A solicitação vai falhar se o download não estiver ativo.

Parâmetros

  • downloadId

    número

    O ID do download a ser retomado.

Retorna

  • Promessa<void>

    Chrome 96+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida quando a solicitação de retomada é concluída.

browser.downloads.search(
  query: DownloadQuery,
)
: Promise<DownloadItem[]>

Encontre DownloadItem. Defina query como o objeto vazio para receber todos os DownloadItem. Para receber um DownloadItem específico, defina apenas o campo id. Para paginar um grande número de itens, defina orderBy: ['-startTime'], defina limit como o número de itens por página e defina startedAfter como o startTime do último item da última página.

Parâmetros

Retorna

  • Promise<DownloadItem[]>

    Chrome 96+ browser.* desde o Chrome 148

setShelfEnabled()

Descontinuado desde o Chrome 117
browser.downloads.setShelfEnabled(
  enabled: boolean,
)
: void

Use setUiOptions.

Ativa ou desativa a estante cinza na parte de baixo de cada janela associada ao perfil do navegador atual. A estante será desativada se pelo menos uma extensão tiver feito isso. Ativar a estante enquanto pelo menos uma outra extensão a desativou vai retornar um erro por meio de runtime.lastError. Requer a permissão "downloads.shelf", além da permissão "downloads".

Parâmetros

  • ativado

    booleano

setUiOptions()

Chrome 105+ browser.* desde o Chrome 148
browser.downloads.setUiOptions(
  options: UiOptions,
)
: Promise<void>

Muda a interface de download de todas as janelas associadas ao perfil atual do navegador. Se pelo menos uma extensão definir UiOptions.enabled como "false", a interface de download será ocultada. Definir UiOptions.enabled como verdadeiro enquanto pelo menos uma outra extensão o desativou vai retornar um erro por meio de runtime.lastError. Requer a permissão "downloads.ui", além da permissão "downloads".

Parâmetros

  • opções

    Encapsula uma mudança na interface de download.

Retorna

  • Promessa<void>

    Retorna uma promessa que é resolvida quando a atualização da interface é concluída.

show()

browser.downloads.show(
  downloadId: number,
)
: void

Mostra o arquivo baixado na pasta dele em um gerenciador de arquivos.

Parâmetros

  • downloadId

    número

    O identificador do arquivo baixado.

showDefaultFolder()

browser.downloads.showDefaultFolder(): void

Mostra a pasta "Downloads" padrão em um gerenciador de arquivos.

Eventos

onChanged

browser.downloads.onChanged.addListener(
  callback: function,
)

Quando qualquer uma das propriedades de um DownloadItem muda, exceto bytesReceived e estimatedEndTime, esse evento é acionado com o downloadId e um objeto que contém as propriedades que mudaram.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a:

    (downloadDelta: DownloadDelta) =& gt;void

onCreated

browser.downloads.onCreated.addListener(
  callback: function,
)

Este evento é disparado com o objeto DownloadItem quando um download começa.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a:

    (downloadItem: DownloadItem) =& gt;void

onDeterminingFilename

browser.downloads.onDeterminingFilename.addListener(
  callback: function,
)

Durante o processo de determinação do nome de arquivo, as extensões terão a oportunidade de substituir o DownloadItem.filename de destino. Cada extensão não pode registrar mais de um listener para esse evento. Cada listener precisa chamar suggest exatamente uma vez, de forma síncrona ou assíncrona. Se o listener chamar suggest de forma assíncrona, ele precisará retornar true. Se o listener não chamar suggest de forma síncrona nem retornar true, suggest será chamado automaticamente. O DownloadItem só será concluído quando todos os listeners tiverem chamado suggest. Os listeners podem chamar suggest sem argumentos para permitir que o download use downloadItem.filename como nome de arquivo ou transmitir um objeto suggestion para suggest para substituir o nome do arquivo de destino. Se mais de uma extensão modificar o nome do arquivo, a última extensão instalada cujo listener transmitir um objeto suggestion para suggest vai prevalecer. Para evitar confusão sobre qual extensão vai prevalecer, os usuários não devem instalar extensões que possam entrar em conflito. Se o download for iniciado por download e o nome do arquivo de destino for conhecido antes que o tipo MIME e o nome do arquivo provisório sejam determinados, transmita filename para download.

Parâmetros

onErased

browser.downloads.onErased.addListener(
  callback: function,
)

É disparado com o downloadId quando um download é apagado do histórico.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a:

    (downloadId: number) =& gt;void

    • downloadId

      número