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 148A mudança em
finalUrl, se houver. -
ID
número
O
iddoDownloadItemque 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 comNETWORK_, os relacionados ao processo de gravação do arquivo no sistema de arquivos começam comFILE_e as interrupções iniciadas pelo usuário começam comUSER_. -
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 eventoonChangedserá acionado. O métodosearch() não espera a conclusão da verificação de existência antes de retornar. Por isso, os resultados desearch() 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 148O 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
FilenameConflictAction opcional
A ação a ser realizada se
filenamejá 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.
onDeterminingFilenamepermite sugerir um nome de arquivo depois que o tipo MIME do arquivo e um nome de arquivo provisório forem determinados. -
cabeçalhos
HeaderNameValuePair[] opcional
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
nameevalueoubinaryValue, 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
filenameestar 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
DownloadItemque terminaram após os milissegundos informados no formato ISO 8601. -
endedBefore
string opcional
Limita os resultados a
DownloadItemque 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
DownloadItemcujofilenamecorresponde à expressão regular fornecida. -
finalUrl
string opcional
Chrome 54+ browser.* desde o Chrome 148O URL absoluto de onde o download está sendo feito, após todos os redirecionamentos.
-
finalUrlRegex
string opcional
Chrome 54+ browser.* desde o Chrome 148Limita os resultados a
DownloadItemcujofinalUrlcorresponde à expressão regular fornecida. -
ID
número optional
O
iddoDownloadItema ser consultado. -
limite
número optional
O número máximo de
DownloadItemcorrespondentes retornados. O valor padrão é 1.000. Defina como 0 para retornar todos osDownloadItemcorrespondentes. Consultesearchpara 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
DownloadItempara classificar os resultados da pesquisa. Por exemplo, definirorderBy=['startTime']classifica osDownloadItempelo 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
DownloadItemem quefilename,urloufinalUrlcontê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
DownloadItemque começaram após os milissegundos fornecidos no formato ISO 8601. -
startedBefore
string opcional
Limita os resultados a
DownloadItemque 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
DownloadItemem quetotalBytesé maior que o número inteiro fornecido. -
totalBytesLess
número optional
Limita os resultados a
DownloadItemem quetotalBytesé 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
DownloadItemcujourlcorresponde à 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
FilenameConflictAction opcional
A ação a ser realizada se
filenamejá existir. -
filename
string
O novo destino
DownloadItem.filenamedoDownloadItem, 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.filenameserá ignorado se houver listenersonDeterminingFilenameregistrados 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
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
-
downloadId
número
O identificador do
DownloadItem.
Retorna
-
Promessa<void>
Chrome 96+ browser.* desde o Chrome 148Retorna 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 148Retorna 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
-
opções
O que baixar e como.
Retorna
-
Promise<number>
Chrome 96+ browser.* desde o Chrome 148Retorna 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
-
consulta
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
-
downloadId
número
O identificador do download.
-
opções
GetFileIconOptions opcional
Retorna
-
Promise<string | undefined>
Chrome 96+ browser.* desde o Chrome 148Retorna 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 148Retorna 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 148Retorna uma promessa que é resolvida quando a solicitação de retomada é concluída.
search()
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
-
consulta
Retorna
-
Promise<DownloadItem[]>
Chrome 96+ browser.* desde o Chrome 148
setShelfEnabled()
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()
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) => void
-
downloadDelta
-
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) => void
-
downloadItem
-
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
-
callback
função
O parâmetro
callbacké semelhante a:(downloadItem: DownloadItem, suggest: function) => void
-
downloadItem
-
suggest
função
O parâmetro
suggesté semelhante a:(suggestion?: FilenameSuggestion) => void
-
sugestão
FilenameSuggestion opcional
-
-
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) => void
-
downloadId
número
-