Essa permissão aciona um aviso
Descrição
Use a API chrome.downloads
para iniciar, monitorar, manipular e pesquisar downloads de forma programática.
Permissões
downloads
Manifesto
É necessário declarar a permissão "downloads"
no manifesto de extensões para usar essa API.
{
"name": "My extension",
...
"permissions": [
"downloads"
],
...
}
Exemplos
Confira exemplos simples de como usar a API chrome.downloads
em examples/api/downloads
diretório. Para ver outros exemplos e receber ajuda para visualizar o código-fonte, consulte Amostras.
Tipos
BooleanDelta
Propriedades
-
atual
booleano opcional
-
anterior
booleano opcional
DangerType
arquivo
O nome de arquivo do download é suspeito.
url
O URL do download é conhecido por ser malicioso.
conteúdo
O arquivo transferido por download é conhecido por ser malicioso.
incomuns
O URL do download não é transferido com frequência e pode ser perigoso.
host
O download veio de um host conhecido por distribuir binários maliciosos e provavelmente é perigoso.
indesejados
O download é potencialmente indesejado ou não seguro. Por exemplo: ele pode fazer alterações nas configurações do navegador ou do computador.
seguro
O download não apresenta perigo conhecido para o computador do usuário.
aceito
O usuário aceitou o download perigoso.
Enumeração
"asyncScanning"
"asyncLocalPasswordScanning"
(link em inglês)
DoubleDelta
Propriedades
-
atual
número opcional
-
anterior
número opcional
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 ou superiorA mudança em
finalUrl
, se houver. -
id
number
O
id
deDownloadItem
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 este download, caso ele tenha sido iniciado por uma extensão. Não muda depois de definido.
-
byExtensionName
string opcional
O nome localizado da extensão que iniciou este download, caso ele tenha sido iniciado por uma extensão. Pode mudar se a extensão mudar o nome ou se o usuário mudar a localidade.
-
bytesReceived
number
Número de bytes recebidos até o momento do host, sem considerar a compactação do arquivo.
-
canResume
booleano
Verdadeiro se o download estiver em andamento e pausado ou se for interrompido e puder ser retomado a partir do ponto em que foi interrompido.
-
perigo
indicação se o download é considerado seguro ou suspeito.
-
endTime
string opcional
A hora 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 HTTP podem ser agrupados em um dos erros que começam com
SERVER_
. Os erros relacionados à rede começam comNETWORK_
, os erros 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 em que o download será concluído 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 transferido por download 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 da existência do arquivo. Quando a verificação da existência for concluída e o arquivo tiver sido excluído, um eventoonChanged
será disparado. Observe quesearch
() 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 for necessário, mas não verificará a existência do arquivo com mais frequência do que uma vez a cada 10 segundos. -
fileSize
number
Número de bytes em todo o arquivo pós-descompactação, ou -1 se for desconhecido.
-
filename
string
Caminho local absoluto.
-
finalUrl
string
Chrome 54 ou superiorO URL absoluto de origem do download, depois de todos os redirecionamentos.
-
id
number
Um identificador permanente nas sessões do navegador.
-
navegação anônima
booleano
Falso se o download for gravado no histórico. Verdadeiro se não for gravado.
-
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
A hora 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á progredindo, interrompido ou concluído.
-
totalBytes
number
Número de bytes em todo o arquivo, sem considerar a compactação do arquivo, ou -1 se for desconhecido.
-
url
string
O URL absoluto de origem do download, antes de qualquer redirecionamento.
DownloadOptions
Propriedades
-
body
string opcional
Corpo da postagem.
-
conflictAction
FilenameConflictAction opcional
A ação a ser tomada se o
filename
já existir. -
filename
string opcional
Um caminho de arquivo relativo ao diretório Downloads para conter o arquivo baixado, possivelmente contendo subdiretórios. Caminhos absolutos, caminhos vazios e caminhos que contêm referências anteriores ".." causará um erro. O
onDeterminingFilename
permite sugerir um nome de arquivo após a determinação do tipo MIME e de um nome de arquivo provisório. -
cabeçalhos
HeaderNameValuePair[] opcional
Cabeçalhos HTTP extras para enviar 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
evalue
oubinaryValue
, restritas àquelas permitidas por XMLHttpRequest. -
method
HttpMethod opcional
O método HTTP a ser usado se o URL utiliza 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 do download.
DownloadQuery
Propriedades
-
bytesReceived
número opcional
Número de bytes recebidos até o momento do host, sem considerar a compactação do arquivo.
-
perigo
DangerType opcional
indicação se o download é considerado seguro ou suspeito.
-
endTime
string opcional
A hora em que o download terminou no formato ISO 8601.
-
endedAfter
string opcional
Limita os resultados a
DownloadItem
que terminam após o ms fornecido no formato ISO 8601 -
endedBefore
string opcional
Limita os resultados a
DownloadItem
que terminaram antes do ms fornecido no formato ISO 8601. -
erro
InterruptReason opcional
O motivo pelo qual um download foi interrompido.
-
existe
booleano opcional
Se o arquivo baixado existe;
-
fileSize
número opcional
Número de bytes em todo o arquivo pós-descompactação, ou -1 se for desconhecido.
-
filename
string opcional
Caminho local absoluto.
-
filenameRegex
string opcional
Limita os resultados a
DownloadItem
em quefilename
corresponde à expressão regular especificada. -
finalUrl
string opcional
Chrome 54 ou superiorO URL absoluto de origem do download, depois de todos os redirecionamentos.
-
finalUrlRegex
string opcional
Chrome 54 ou superiorLimita os resultados a
DownloadItem
em quefinalUrl
corresponde à expressão regular especificada. -
id
número opcional
O
id
doDownloadItem
a ser consultado. -
limite
número opcional
O número máximo de
DownloadItem
correspondentes retornados. O valor padrão é 1000. Defina como 0 para retornar todas asDownloadItem
correspondentes. Consultesearch
para saber como navegar pelos resultados. -
mímica
string opcional
O tipo MIME do arquivo.
-
orderBy
string[] opcional
Defina os elementos dessa matriz como as propriedades
DownloadItem
para classificar os resultados da pesquisa. Por exemplo, definirorderBy=['startTime']
classifica asDownloadItem
pelo horário de início em ordem crescente. Para especificar a ordem decrescente, prefixe com um hífen: "-startTime". -
pausado
booleano opcional
Verdadeiro se o download parou de ler dados do host, mas manteve a conexão aberta.
-
consulta
string[] opcional
Esta matriz de termos de pesquisa limita os resultados a
DownloadItem
cujofilename
,url
oufinalUrl
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 travessão. -
startTime
string opcional
A hora em que o download começou no formato ISO 8601.
-
startedAfter
string opcional
Limita os resultados a
DownloadItem
que começaram após o ms fornecido no formato ISO 8601. -
startedBefore
string opcional
Limita os resultados a
DownloadItem
iniciados antes do ms fornecido no formato ISO 8601. -
estado
Estado opcional
Indica se o download está progredindo, interrompido ou concluído.
-
totalBytes
número opcional
Número de bytes em todo o arquivo, sem considerar a compactação do arquivo, ou -1 se for desconhecido.
-
totalBytesGreater
número opcional
Limita os resultados a
DownloadItem
em quetotalBytes
é maior que o número inteiro fornecido. -
totalBytesLess
número opcional
Limita os resultados a
DownloadItem
em quetotalBytes
é menor que o número inteiro fornecido. -
url
string opcional
O URL absoluto de origem do download, antes de qualquer redirecionamento.
-
urlRegex
string opcional
Limita os resultados a
DownloadItem
em queurl
corresponde à expressão regular especificada.
FilenameConflictAction
Uniquify
Para evitar a duplicação, o filename
é modificado para incluir um contador antes da extensão do nome de arquivo.
substituir
O arquivo atual será substituído pelo novo.
prompt
O usuário verá uma caixa de diálogo seletora de arquivo.
Enumeração
FilenameSuggestion
Propriedades
-
conflictAction
FilenameConflictAction opcional
A ação a ser tomada se o
filename
já existir. -
filename
string
O novo destino do
DownloadItem
DownloadItem.filename
, como um caminho relativo ao diretório "Downloads" padrão do usuário, possivelmente contendo subdiretórios. Caminhos absolutos, caminhos vazios e caminhos que contêm referências anteriores ".." serão ignorados.filename
será ignorado se houver algum listeneronDeterminingFilename
registrado por qualquer extensão.
GetFileIconOptions
Propriedades
-
tamanho
número opcional
O tamanho do ícone retornado. O ícone será quadrado com dimensões de tamanho * tamanho em pixels. O tamanho padrão e maior do ícone é 32 x 32 pixels. Os únicos tamanhos compatíveis são 16 e 32. Especificar qualquer outro tamanho é um erro.
HeaderNameValuePair
Propriedades
-
nome
string
Nome do cabeçalho HTTP.
-
valor
string
Valor do cabeçalho HTTP.
HttpMethod
Enumeração
InterruptReason
Enumeração
State
in_progress
No momento, 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
StringDelta
Propriedades
-
atual
string opcional
-
anterior
string opcional
UiOptions
Propriedades
-
ativado
booleano
Ativar ou desativar a interface de download.
Métodos
acceptDanger()
chrome.downloads.acceptDanger(
downloadId: number,
callback?: function,
)
Pedir que o usuário aceite um download perigoso. Só podem ser chamadas a partir de um contexto visível (guia, janela ou pop-up de ação da página/navegador). Não aceita downloads perigosos automaticamente. Se o download for aceito, um evento onChanged
será disparado. Caso contrário, nada 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 com o nome de destino, o state
muda para "complete", e a onChanged
é acionada.
Parâmetros
-
downloadId
number
O identificador de
DownloadItem
. -
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
cancel()
chrome.downloads.cancel(
downloadId: number,
callback?: function,
)
Cancelar um download. Quando callback
for executado, o download será cancelado, concluído, interrompido ou não existe mais.
Parâmetros
-
downloadId
number
O ID do download a ser cancelado.
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
download()
chrome.downloads.download(
options: DownloadOptions,
callback?: function,
)
Faça o download de um URL. Se o URL usar o protocolo HTTP[S], a solicitação incluirá todos os cookies atualmente 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 tiver começado, callback
será chamado com o novo downloadId
do DownloadItem
. Se ocorrer um erro ao iniciar o download, callback
será chamado com downloadId=undefined
, e runtime.lastError
terá 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 fazer download e como.
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(downloadId: number) => void
-
downloadId
number
-
Retorna
-
Promise<number>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
erase()
chrome.downloads.erase(
query: DownloadQuery,
callback?: function,
)
Apague a correspondência DownloadItem
do histórico sem excluir o arquivo transferido. Um evento onErased
será disparado para cada DownloadItem
que corresponder a query
. Em seguida, callback
será chamado.
Parâmetros
-
consulta
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(erasedIds: number[]) => void
-
erasedIds
número[]
-
Retorna
-
Promise<number[]>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getFileIcon()
chrome.downloads.getFileIcon(
downloadId: number,
options?: GetFileIconOptions,
callback?: function,
)
Recupera um ícone para o download especificado. Para novos downloads, os ícones de arquivo ficam disponíveis depois que o evento onCreated
é recebido. 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 com uma consulta ao sistema operacional ou kit de ferramentas subjacente, dependendo da plataforma. O ícone retornado dependerá, portanto, 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 identificar um ícone de arquivo, o runtime.lastError
vai mostrar uma mensagem de erro.
Parâmetros
-
downloadId
number
O identificador do download.
-
opções
GetFileIconOptions opcional
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(iconURL?: string) => void
-
iconURL
string opcional
-
Retorna
-
Promise<string | indefinido>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
open()
chrome.downloads.open(
downloadId: number,
callback?: function,
)
Abre o arquivo transferido agora se o DownloadItem
estiver concluído. caso contrário, retorna um erro por runtime.lastError
. Esse método exige a permissão "downloads.open"
, além da "downloads"
. Um evento onChanged
é disparado quando o item é aberto pela primeira vez. Esse método só pode ser chamado em resposta a um gesto do usuário.
Parâmetros
-
downloadId
number
O identificador do arquivo baixado.
-
callback
função opcional
Chrome 123 ou versões mais recentesO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 123 ou versões mais recentesAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
pause()
chrome.downloads.pause(
downloadId: number,
callback?: function,
)
Pause o download. Se a solicitação for bem-sucedida, o download estará em estado pausado. Caso contrário, runtime.lastError
vai mostrar uma mensagem de erro. A solicitação falhará se o download não estiver ativo.
Parâmetros
-
downloadId
number
O ID do download a ser pausado.
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
removeFile()
chrome.downloads.removeFile(
downloadId: number,
callback?: function,
)
Remova o arquivo salvo se ele existir e a DownloadItem
estiver concluída. Caso contrário, retornará um erro por meio de runtime.lastError
.
Parâmetros
-
downloadId
number
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
resume()
chrome.downloads.resume(
downloadId: number,
callback?: function,
)
Retome um download pausado. Se a solicitação tiver sido bem-sucedida, o download estará em andamento e será retomado. Caso contrário, runtime.lastError
vai mostrar uma mensagem de erro. A solicitação falhará se o download não estiver ativo.
Parâmetros
-
downloadId
number
O ID do download a ser retomado.
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
search()
chrome.downloads.search(
query: DownloadQuery,
callback?: function,
)
Encontre DownloadItem
. Defina query
como o objeto vazio para acessar todas as DownloadItem
. Para acessar um DownloadItem
específico, defina apenas o campo id
. Para percorrer um grande número de itens, defina orderBy: ['-startTime']
, limit
como o número de itens por página e startedAfter
como o startTime
do último item da última página.
Parâmetros
-
consulta
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(results: DownloadItem[]) => void
-
resultados
-
Retorna
-
Promise<DownloadItem[]>
Chrome 96 ou versão mais recenteAs promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setShelfEnabled()
chrome.downloads.setShelfEnabled(
enabled: boolean,
)
Use setUiOptions
.
Ative ou desative a estante cinza na parte inferior de cada janela associada ao perfil atual do navegador. A estante ficará desativada enquanto pelo menos uma extensão a tiver desativado. Ativar a estante enquanto pelo menos uma outra extensão estiver desativada retornará um erro por runtime.lastError
. Requer a permissão "downloads.shelf"
, além da permissão "downloads"
.
Parâmetros
-
ativado
booleano
setUiOptions()
chrome.downloads.setUiOptions(
options: UiOptions,
callback?: function,
)
Altere a interface de download de todas as janelas associadas ao perfil atual do navegador. Enquanto pelo menos uma extensão tiver definido UiOptions.enabled
como falso, a interface de download ficará oculta. Se UiOptions.enabled
for definido como verdadeiro enquanto pelo menos uma outra extensão estiver desativada, um erro será retornado por runtime.lastError
. Requer a permissão "downloads.ui"
, além da permissão "downloads"
.
Parâmetros
-
opções
Encapsular uma alteração na interface de download.
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
show()
chrome.downloads.show(
downloadId: number,
)
Mostre o arquivo baixado em sua pasta em um gerenciador de arquivos.
Parâmetros
-
downloadId
number
O identificador do arquivo baixado.
showDefaultFolder()
chrome.downloads.showDefaultFolder()
Mostrar a pasta "Downloads" padrão em um gerenciador de arquivos.
Eventos
onChanged
chrome.downloads.onChanged.addListener(
callback: function,
)
Quando qualquer uma das propriedades de DownloadItem
, exceto bytesReceived
e estimatedEndTime
, é alterada, esse evento é disparado com a downloadId
e um objeto que contém as propriedades alteradas.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(downloadDelta: DownloadDelta) => void
-
downloadDelta
-
onCreated
chrome.downloads.onCreated.addListener(
callback: function,
)
Este evento é disparado com o objeto DownloadItem
quando um download é iniciado.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(downloadItem: DownloadItem) => void
-
downloadItem
-
onDeterminingFilename
chrome.downloads.onDeterminingFilename.addListener(
callback: function,
)
Durante o processo de determinação do nome do 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, será necessário retornar true
. Se o listener não chamar suggest
de forma síncrona nem retornar true
, suggest
será chamado automaticamente. O DownloadItem
não será concluído até que todos os listeners chamem suggest
. Os listeners podem chamar suggest
sem nenhum argumento 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 substituir o nome do arquivo, a última extensão instalada cujo listener transmitir um objeto suggestion
para suggest
vencerá. Para evitar confusão sobre qual extensão será a vencedora, 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 da determinação do tipo MIME e do nome de arquivo provisório, transmita filename
para download
.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(downloadItem: DownloadItem, suggest: function) => void
-
downloadItem
-
suggest
função
O parâmetro
suggest
tem esta aparência:(suggestion?: FilenameSuggestion) => void
-
sugestão
FilenameSuggestion opcional
-
-
onErased
chrome.downloads.onErased.addListener(
callback: function,
)
Ativa com o downloadId
quando um download é apagado do histórico.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(downloadId: number) => void
-
downloadId
number
-