chrome.downloads

Descrição

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

Permissões

downloads

Você precisa declarar a permissão "downloads" no manifesto da extensão para usar essa API.

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

Exemplos

Você encontra exemplos simples de uso da API chrome.downloads no diretório examples/api/downloads. Para outros exemplos e ajuda para ver o código-fonte, consulte Exemplos.

Tipos

BooleanDelta

Propriedades

  • atual

    booleano opcional

  • anterior

    booleano opcional

DangerType

arquivo

O nome do arquivo do download é suspeito.

url

O URL do download é conhecido por ser malicioso.

conteúdo

O arquivo baixado é conhecido por ser malicioso.

incomum

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.

indesejado

O download pode ser indesejado ou perigoso. Por exemplo, ele pode fazer mudanças nas configurações do navegador ou do computador.

seguro

O download não apresenta nenhum risco conhecido para o computador do usuário.

aceito

O usuário aceitou o download perigoso.

Enumeração

"file"

"url"

"content"

"incomum"

"host"

"indesejado"

"seguro"

"accepted"

"allowlistedByPolicy"

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

DoubleDelta

Propriedades

  • atual

    number optional

  • anterior

    number 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 ou mais recente

    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 ele tiver sido iniciado por uma extensão. Não muda depois de definido.

  • byExtensionName

    string opcional

    O nome localizado da extensão que iniciou o download, se ele tiver sido iniciado por uma extensão. Pode mudar se a extensão mudar de nome ou se o usuário mudar a 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

    DangerType

    Indicação de se 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 HTTP podem ser agrupados em um dos erros que começam com SERVER_. Os erros relacionados à rede começam com NETWORK_, os erros 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 da 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. search() não aguarda a conclusão da verificação de existência antes de retornar. Portanto, os resultados de search() podem não refletir com precisão o sistema de arquivos. Além disso, search() pode ser chamado com a frequência necessária, mas não vai verificar a existência do arquivo com mais frequência do que 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 desconhecido.

  • filename

    string

    Caminho local absoluto.

  • finalUrl

    string

    Chrome 54 ou mais recente

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

  • ID

    número

    Um identificador persistente em todas as sessões do navegador.

  • navegação anônima

    booleano

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

  • 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

    Estado

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

  • totalBytes

    número

    Número de bytes em todo o arquivo, sem considerar a compactação, ou -1 se 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 filename já existir.

  • filename

    string opcional

    Um caminho de arquivo relativo ao diretório "Downloads" para conter o arquivo baixado, possivelmente com subdiretórios. Caminhos absolutos, vazios e que contêm referências anteriores ".." causam um erro. O onDeterminingFilename permite sugerir um nome de arquivo depois que o tipo MIME e um nome provisório são 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 name e value ou binaryValue, restritas àquelas permitidas por XMLHttpRequest.

  • method

    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, independente de filename estar definido ou já existir.

  • url

    string

    O URL para download.

DownloadQuery

Propriedades

  • bytesReceived

    number optional

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

  • perigo

    DangerType opcional

    Indicação de se 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 depois do ms especificado no formato ISO 8601.

  • endedBefore

    string opcional

    Limita os resultados a DownloadItem que terminaram antes do ms especificado no formato ISO 8601.

  • erro

    InterruptReason opcional

    Por que um download foi interrompido.

  • existe

    booleano opcional

    Se o arquivo baixado existe;

  • fileSize

    number optional

    Número de bytes em todo o arquivo após a descompactação ou -1 se 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 ou mais recente

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

  • finalUrlRegex

    string opcional

    Chrome 54 ou mais recente

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

  • ID

    number optional

    O id do DownloadItem a ser consultado.

  • limite

    number 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 navegar pelos 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, adicione 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 cujo filename, url ou finalUrl contêm todos os termos de pesquisa que não começam com um traço "-" e nenhum dos termos 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 depois do ms especificado no formato ISO 8601.

  • startedBefore

    string opcional

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

  • estado

    Estado opcional

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

  • totalBytes

    number optional

    Número de bytes em todo o arquivo, sem considerar a compactação, ou -1 se desconhecido.

  • totalBytesGreater

    number optional

    Limita os resultados a DownloadItem cujo totalBytes é maior que o número inteiro especificado.

  • totalBytesLess

    number optional

    Limita os resultados a DownloadItem cujo totalBytes é menor que o número inteiro especificado.

  • 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.

prompt

Uma caixa de diálogo de seleção de arquivos vai aparecer para o usuário.

Enumeração

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

Propriedades

  • conflictAction

    FilenameConflictAction opcional

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

  • filename

    string

    O novo DownloadItem.filename de destino 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 extensões.

GetFileIconOptions

Propriedades

  • tamanho

    number optional

    O tamanho do ícone retornado. O ícone será quadrado com dimensões de tamanho * tamanho pixels. O tamanho padrão e maior do ícone é 32x32 pixels. Os únicos tamanhos aceitos são 16 e 32. É um erro especificar qualquer outro tamanho.

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.

concluído

O download foi concluído.

Enumeração

"in_progress"

"interrupted"

"concluído"

StringDelta

Propriedades

  • atual

    string opcional

  • anterior

    string opcional

UiOptions

Chrome 105 ou mais recente

Propriedades

  • ativado

    booleano

    Ative ou desative a interface de download.

Métodos

acceptDanger()

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

Peça que o usuário aceite um download perigoso. Só pode ser chamado de um contexto visível (guia, janela ou pop-up de ação de página/navegador). Não aceita automaticamente downloads perigosos. 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 o onChanged é acionado.

Parâmetros

Retorna

  • Promise<void>

    Chrome 96+

cancel()

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

Cancelar um download. Quando o 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

  • Promise<void>

    Chrome 96+

download()

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

Baixar 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, preenchida previamente com o filename especificado. Se o download for iniciado, callback será chamado com o novo DownloadItem's downloadId. 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 manter a compatibilidade com versões anteriores entre os lançamentos. As extensões não podem analisá-lo.

Parâmetros

Retorna

  • Promise<number>

    Chrome 96+

erase()

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

Apagar DownloadItem correspondentes do histórico sem excluir o arquivo baixado. Um evento onErased será disparado para cada DownloadItem que corresponder a query. Em seguida, callback será chamado.

Parâmetros

Retorna

  • Promise<number[]>

    Chrome 96+

getFileIcon()

chrome.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 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 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+

open()

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

Abre o arquivo baixado agora se o DownloadItem estiver concluído. Caso contrário, retorna um erro por runtime.lastError. Esse método exige as permissões "downloads.open" e "downloads". Um evento onChanged é acionado 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

    número

    O identificador do arquivo baixado.

Retorna

  • Promise<void>

    Chrome 123+

pause()

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

Pause o download. Se a solicitação for bem-sucedida, o download vai estar em 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 a ser pausado.

Retorna

  • Promise<void>

    Chrome 96+

removeFile()

chrome.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 usando runtime.lastError.

Parâmetros

  • downloadId

    número

Retorna

  • Promise<void>

    Chrome 96+

resume()

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

Retomar um download pausado. Se a solicitação for bem-sucedida, o download vai estar em andamento e sem pausa. 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

  • Promise<void>

    Chrome 96+ 
chrome.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'], limit como o número de itens por página e startedAfter como o startTime do último item da última página.

Parâmetros

Retorna

setShelfEnabled()

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

Use setUiOptions.

Ative ou desative a barra cinza na parte de baixo de todas as janelas associadas ao perfil atual do navegador. A seção vai ficar desativada enquanto pelo menos uma extensão tiver feito isso. Ativar a barra enquanto pelo menos outra extensão a desativou vai retornar um erro por runtime.lastError. Requer a permissão "downloads.shelf", além da "downloads".

Parâmetros

  • ativado

    booleano

setUiOptions()

Chrome 105 ou mais recente 
chrome.downloads.setUiOptions(
  options: UiOptions,
): Promise<void>

Muda 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 "false", a interface de download vai ficar oculta. Definir UiOptions.enabled como "true" enquanto pelo menos outra extensão o desativou vai retornar um erro por runtime.lastError. Requer a permissão "downloads.ui", além da "downloads".

Parâmetros

  • opções

    UiOptions

    Encapsular uma mudança na interface de download.

Retorna

  • Promise<void>

show()

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

Mostrar o arquivo baixado na pasta em um gerenciador de arquivos.

Parâmetros

  • downloadId

    número

    O identificador do arquivo baixado.

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

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 um DownloadItem, exceto bytesReceived e estimatedEndTime, muda, esse evento é disparado com o 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

onCreated

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (downloadItem: DownloadItem) => void

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 maneira 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 não será concluído até que todos os listeners tenham 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 e substituir o nome de 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 vai vencer. Para evitar confusão sobre qual extensão vai ganhar, 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 provisório, transmita filename para download.

Parâmetros

onErased

chrome.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 tem esta aparência: 

    (downloadId: number) => void

    • downloadId

      número