chrome.downloads

Descrizione

Utilizza l'API chrome.downloads per avviare, monitorare, manipolare e cercare i download in modo programmatico.

Autorizzazioni

downloads

Per utilizzare questa API, devi dichiarare l'autorizzazione "downloads" nel manifest dell'estensione.

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

Esempi

Puoi trovare semplici esempi di utilizzo dell'API chrome.downloads nella directory examples/api/downloads. Per altri esempi e per assistenza nella visualizzazione del codice sorgente, vedi Esempi.

Tipi

BooleanDelta

Proprietà

  • attuale

    booleano facoltativo

  • indietro

    booleano facoltativo

DangerType

file

Il nome file del download è sospetto.

url

L'URL del download è noto per essere dannoso.

contenuti

È noto che il file scaricato è dannoso.

insolito

L'URL del download non viene scaricato spesso e potrebbe essere pericoloso.

host

Il download proviene da un host noto per distribuire file binari dannosi ed è probabilmente pericoloso.

indesiderato

Il download è potenzialmente indesiderato o non sicuro. Ad esempio, potrebbe apportare modifiche alle impostazioni del browser o del computer.

sicurezza

Il download non presenta pericoli noti per il computer dell'utente.

accettato

L'utente ha accettato il download pericoloso.

Enum

"file"

"url"

"content"

"non comune"

"host"

"indesiderato"

"safe"

"accepted"

"allowlistedByPolicy"

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

DoubleDelta

Proprietà

  • attuale

    number (facoltativo)

  • indietro

    number (facoltativo)

DownloadDelta

Proprietà

  • canResume

    BooleanDelta facoltativo

    La variazione di canResume, se presente.

  • pericolo

    StringDelta facoltativo

    La variazione di danger, se presente.

  • endTime

    StringDelta facoltativo

    La variazione di endTime, se presente.

  • errore

    StringDelta facoltativo

    La variazione di error, se presente.

  • esiste

    BooleanDelta facoltativo

    La variazione di exists, se presente.

  • fileSize

    DoubleDelta facoltativo

    La variazione di fileSize, se presente.

  • nome file

    StringDelta facoltativo

    La variazione di filename, se presente.

  • finalUrl

    StringDelta facoltativo

    Chrome 54 o versioni successive

    La variazione di finalUrl, se presente.

  • id

    numero

    Il id del DownloadItem che è stato modificato.

  • mimo

    StringDelta facoltativo

    La variazione di mime, se presente.

  • in pausa

    BooleanDelta facoltativo

    La variazione di paused, se presente.

  • startTime

    StringDelta facoltativo

    La variazione di startTime, se presente.

  • stato

    StringDelta facoltativo

    La variazione di state, se presente.

  • totalBytes

    DoubleDelta facoltativo

    La variazione di totalBytes, se presente.

  • url

    StringDelta facoltativo

    La variazione di url, se presente.

DownloadItem

Proprietà

  • byExtensionId

    stringa facoltativa

    L'identificatore dell'estensione che ha avviato questo download, se è stato avviato da un'estensione. Non cambia una volta impostato.

  • byExtensionName

    stringa facoltativa

    Il nome localizzato dell'estensione che ha avviato questo download, se il download è stato avviato da un'estensione. Potrebbe cambiare se l'estensione cambia nome o se l'utente cambia le impostazioni internazionali.

  • bytesReceived

    numero

    Numero di byte ricevuti finora dall'host, senza considerare la compressione dei file.

  • canResume

    booleano

    True se il download è in corso e in pausa oppure se è stato interrotto e può essere ripreso dal punto in cui è stato interrotto.

  • pericolo

    DangerType

    Indica se il download è considerato sicuro o sospetto.

  • endTime

    stringa facoltativa

    L'ora in cui è terminato il download in formato ISO 8601. Può essere passato direttamente al costruttore Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

  • errore

    InterruptReason facoltativo

    Motivi dell'interruzione del download. Diversi tipi di errori HTTP possono essere raggruppati in uno degli errori che iniziano con SERVER_. Gli errori relativi alla rete iniziano con NETWORK_, quelli relativi al processo di scrittura del file nel file system iniziano con FILE_ e le interruzioni avviate dall'utente iniziano con USER_.

  • estimatedEndTime

    stringa facoltativa

    Ora stimata di completamento del download nel formato ISO 8601. Può essere passato direttamente al costruttore Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

  • esiste

    booleano

    Indica se il file scaricato esiste ancora. Queste informazioni potrebbero non essere aggiornate perché Chrome non monitora automaticamente la rimozione dei file. Chiama search() per attivare il controllo dell'esistenza del file. Al termine del controllo dell'esistenza, se il file è stato eliminato, viene attivato un evento onChanged. Tieni presente che search() non attende il completamento del controllo dell'esistenza prima di restituire un valore, pertanto i risultati di search() potrebbero non riflettere con precisione il file system. Inoltre, search() può essere chiamato tutte le volte che è necessario, ma non controllerà l'esistenza del file più di una volta ogni 10 secondi.

  • fileSize

    numero

    Numero di byte nell'intero file dopo la decompressione o -1 se sconosciuto.

  • nome file

    stringa

    Percorso locale assoluto.

  • finalUrl

    stringa

    Chrome 54 o versioni successive

    L'URL assoluto da cui viene eseguito il download, dopo tutti i reindirizzamenti.

  • id

    numero

    Un identificatore persistente tra le sessioni del browser.

  • in incognito

    booleano

    Falso se questo download è registrato nella cronologia, vero se non è registrato.

  • mimo

    stringa

    Il tipo MIME del file.

  • in pausa

    booleano

    True se il download ha interrotto la lettura dei dati dall'host, ma ha mantenuto aperta la connessione.

  • referrer

    stringa

    URL assoluto.

  • startTime

    stringa

    L'ora di inizio del download nel formato ISO 8601. Può essere passato direttamente al costruttore Date: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • stato

    Stato

    Indica se il download è in corso, interrotto o completato.

  • totalBytes

    numero

    Numero di byte nell'intero file, senza considerare la compressione del file o -1 se sconosciuto.

  • url

    stringa

    L'URL assoluto da cui è stato avviato questo download, prima di eventuali reindirizzamenti.

DownloadOptions

Proprietà

  • corpo

    stringa facoltativa

    Corpo del post.

  • conflictAction

    FilenameConflictAction facoltativo

    L'azione da eseguire se filename esiste già.

  • nome file

    stringa facoltativa

    Un percorso del file relativo alla directory Download per contenere il file scaricato, che potrebbe contenere sottodirectory. I percorsi assoluti, i percorsi vuoti e i percorsi contenenti riferimenti inversi ".." causeranno un errore. onDeterminingFilename consente di suggerire un nome file dopo aver determinato il tipo MIME del file e un nome file provvisorio.

  • intestazioni

    HeaderNameValuePair[] facoltativo

    Intestazioni HTTP aggiuntive da inviare con la richiesta se l'URL utilizza il protocollo HTTP[s]. Ogni intestazione è rappresentata come un dizionario contenente le chiavi name e value o binaryValue, limitate a quelle consentite da XMLHttpRequest.

  • method

    HttpMethod (facoltativo)

    Il metodo HTTP da utilizzare se l'URL utilizza il protocollo HTTP[S].

  • saveAs

    booleano facoltativo

    Utilizza un selettore di file per consentire all'utente di selezionare un nome file indipendentemente dal fatto che filename sia impostato o esista già.

  • url

    stringa

    L'URL da scaricare.

DownloadQuery

Proprietà

  • bytesReceived

    number (facoltativo)

    Numero di byte ricevuti finora dall'host, senza considerare la compressione dei file.

  • pericolo

    DangerType facoltativo

    Indica se il download è considerato sicuro o sospetto.

  • endTime

    stringa facoltativa

    L'ora in cui è terminato il download in formato ISO 8601.

  • endedAfter

    stringa facoltativa

    Limita i risultati a DownloadItem che sono terminati dopo i millisecondi specificati nel formato ISO 8601

  • endedBefore

    stringa facoltativa

    Limita i risultati a DownloadItem che sono terminati prima del valore ms specificato nel formato ISO 8601.

  • errore

    InterruptReason facoltativo

    Motivo dell'interruzione di un download.

  • esiste

    booleano facoltativo

    Indica se il file scaricato esiste.

  • fileSize

    number (facoltativo)

    Numero di byte nell'intero file dopo la decompressione o -1 se sconosciuto.

  • nome file

    stringa facoltativa

    Percorso locale assoluto.

  • filenameRegex

    stringa facoltativa

    Limita i risultati a DownloadItem il cui filename corrisponde all'espressione regolare specificata.

  • finalUrl

    stringa facoltativa

    Chrome 54 o versioni successive

    L'URL assoluto da cui viene eseguito il download, dopo tutti i reindirizzamenti.

  • finalUrlRegex

    stringa facoltativa

    Chrome 54 o versioni successive

    Limita i risultati a DownloadItem il cui finalUrl corrisponde all'espressione regolare specificata.

  • id

    number (facoltativo)

    Il id di DownloadItem da interrogare.

  • limite

    number (facoltativo)

    Il numero massimo di DownloadItem corrispondenti restituiti. Il valore predefinito è 1000. Imposta il valore su 0 per restituire tutti i DownloadItem corrispondenti. Consulta la sezione search per scoprire come sfogliare i risultati.

  • mimo

    stringa facoltativa

    Il tipo MIME del file.

  • orderBy

    string[] facoltativo

    Imposta gli elementi di questo array sulle proprietà DownloadItem per ordinare i risultati di ricerca. Ad esempio, l'impostazione orderBy=['startTime'] ordina DownloadItem in base all'ora di inizio in ordine crescente. Per specificare l'ordine decrescente, aggiungi un trattino come prefisso: "-startTime".

  • in pausa

    booleano facoltativo

    True se il download ha interrotto la lettura dei dati dall'host, ma ha mantenuto aperta la connessione.

  • query

    string[] facoltativo

    Questo array di termini di ricerca limita i risultati a DownloadItem il cui filename o url o finalUrl contengono tutti i termini di ricerca che non iniziano con un trattino "-" e nessuno dei termini di ricerca che iniziano con un trattino.

  • startTime

    stringa facoltativa

    L'ora di inizio del download nel formato ISO 8601.

  • startedAfter

    stringa facoltativa

    Limita i risultati a DownloadItem iniziati dopo i millisecondi specificati nel formato ISO 8601.

  • startedBefore

    stringa facoltativa

    Limita i risultati a DownloadItem iniziati prima del valore ms specificato nel formato ISO 8601.

  • stato

    Stato facoltativo

    Indica se il download è in corso, interrotto o completato.

  • totalBytes

    number (facoltativo)

    Numero di byte nell'intero file, senza considerare la compressione del file o -1 se sconosciuto.

  • totalBytesGreater

    number (facoltativo)

    Limita i risultati a DownloadItem il cui totalBytes è maggiore dell'intero specificato.

  • totalBytesLess

    number (facoltativo)

    Limita i risultati a DownloadItem il cui totalBytes è inferiore all'intero specificato.

  • url

    stringa facoltativa

    L'URL assoluto da cui è stato avviato questo download, prima di eventuali reindirizzamenti.

  • urlRegex

    stringa facoltativa

    Limita i risultati a DownloadItem il cui url corrisponde all'espressione regolare specificata.

FilenameConflictAction

rendere unico

Per evitare duplicati, il filename viene modificato in modo da includere un contatore prima dell'estensione del nome file.

sovrascrivere

Il file esistente verrà sovrascritto con il nuovo file.

richiesta

All'utente verrà mostrata una finestra di dialogo di selezione dei file.

Enum

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

Proprietà

  • conflictAction

    FilenameConflictAction facoltativo

    L'azione da eseguire se filename esiste già.

  • nome file

    stringa

    Il nuovo target DownloadItem.filename di DownloadItem, come percorso relativo alla directory Download predefinita dell'utente, che potrebbe contenere sottodirectory. I percorsi assoluti, i percorsi vuoti e i percorsi contenenti riferimenti indiretti ".." verranno ignorati. filename viene ignorato se sono presenti listener onDeterminingFilename registrati da estensioni.

GetFileIconOptions

Proprietà

  • dimensioni

    number (facoltativo)

    Le dimensioni dell'icona restituita. L'icona sarà quadrata con dimensioni pari a size * size pixel. La dimensione predefinita e massima dell'icona è 32 x 32 pixel. Le uniche dimensioni supportate sono 16 e 32. È un errore specificare qualsiasi altra dimensione.

HeaderNameValuePair

Proprietà

  • nome

    stringa

    Nome dell'intestazione HTTP.

  • valore

    stringa

    Valore dell'intestazione HTTP.

HttpMethod

Enum

"GET"

"POST"

InterruptReason

Enum

"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

Il download sta attualmente ricevendo dati dal server.

interrotto

Un errore ha interrotto la connessione con l'host del file.

completato

Il download è stato completato correttamente.

Enum

"in_progress"

"interrupted"

"complete"

StringDelta

Proprietà

  • attuale

    stringa facoltativa

  • indietro

    stringa facoltativa

UiOptions

Chrome 105+

Proprietà

  • attivato

    booleano

    Attiva o disattiva l'interfaccia utente di download.

Metodi

acceptDanger()

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

Chiedere all'utente di accettare un download pericoloso. Può essere chiamato solo da un contesto visibile (scheda, finestra o popup di azione della pagina/del browser). Non accetta automaticamente i download pericolosi. Se il download viene accettato, viene attivato un evento onChanged, altrimenti non succede nulla. Quando tutti i dati vengono recuperati in un file temporaneo e il download non è pericoloso o il pericolo è stato accettato, il file temporaneo viene rinominato con il nome del file di destinazione, lo stato state diventa "completato" e viene attivato l'evento onChanged.

Parametri

Resi

  • Promise<void>

    Chrome 96+

cancel()

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

Annullare un download. Quando viene eseguito callback, il download viene annullato, completato, interrotto o non esiste più.

Parametri

  • downloadId

    numero

    L'ID del download da annullare.

Resi

  • Promise<void>

    Chrome 96+

download()

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

Scarica un URL. Se l'URL utilizza il protocollo HTTP[S], la richiesta includerà tutti i cookie attualmente impostati per il relativo nome host. Se vengono specificati sia filename che saveAs, viene visualizzata la finestra di dialogo Salva con nome, precompilata con il valore filename specificato. Se il download è stato avviato correttamente, callback verrà chiamato con il nuovo downloadId di DownloadItem. Se si è verificato un errore durante l'avvio del download, verrà chiamato callback con downloadId=undefined e runtime.lastError conterrà una stringa descrittiva. Non è garantita la compatibilità retroattiva delle stringhe di errore tra le release. Le estensioni non devono analizzarlo.

Parametri

Resi

  • Promise<number>

    Chrome 96+

erase()

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

Cancella la corrispondenza DownloadItem dalla cronologia senza eliminare il file scaricato. Viene attivato un evento onErased per ogni DownloadItem che corrisponde a query, quindi viene chiamato callback.

Parametri

Resi

  • Promise<number[]>

    Chrome 96+

getFileIcon()

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

Recupera un'icona per il download specificato. Per i nuovi download, le icone dei file sono disponibili dopo la ricezione dell'evento onCreated. L'immagine restituita da questa funzione durante il download potrebbe essere diversa da quella restituita al termine del download. Il recupero delle icone viene eseguito interrogando il sistema operativo o il toolkit sottostante a seconda della piattaforma. L'icona restituita dipenderà quindi da una serie di fattori, tra cui lo stato del download, la piattaforma, i tipi di file registrati e il tema visivo. Se non è possibile determinare l'icona di un file, runtime.lastError conterrà un messaggio di errore.

Parametri

  • downloadId

    numero

    L'identificatore del download.

  • opzioni

    GetFileIconOptions facoltativo

Resi

  • Promise<string | undefined>

    Chrome 96+

open()

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

Apre il file scaricato ora se DownloadItem è completato; altrimenti restituisce un errore tramite runtime.lastError. Questo metodo richiede l'autorizzazione "downloads.open" oltre all'autorizzazione "downloads". Un evento onChanged viene attivato quando l'elemento viene aperto per la prima volta. Questo metodo può essere chiamato solo in risposta a un gesto dell'utente.

Parametri

  • downloadId

    numero

    L'identificatore del file scaricato.

Resi

  • Promise<void>

    Chrome 123+

pause()

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

Metti in pausa il download. Se la richiesta è andata a buon fine, il download è in stato di pausa. In caso contrario, runtime.lastError contiene un messaggio di errore. La richiesta non andrà a buon fine se il download non è attivo.

Parametri

  • downloadId

    numero

    L'ID del download da mettere in pausa.

Resi

  • Promise<void>

    Chrome 96+

removeFile()

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

Rimuovi il file scaricato se esiste e DownloadItem è completo; in caso contrario, restituisci un errore tramite runtime.lastError.

Parametri

  • downloadId

    numero

Resi

  • Promise<void>

    Chrome 96+

resume()

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

Riprendere un download in pausa. Se la richiesta è andata a buon fine, il download è in corso e non è in pausa. In caso contrario, runtime.lastError contiene un messaggio di errore. La richiesta non andrà a buon fine se il download non è attivo.

Parametri

  • downloadId

    numero

    L'ID del download da riprendere.

Resi

  • Promise<void>

    Chrome 96+ 
chrome.downloads.search(
  query: DownloadQuery,
): Promise<DownloadItem[]>

Trova DownloadItem. Imposta query sull'oggetto vuoto per ottenere tutti i DownloadItem. Per ottenere un DownloadItem specifico, imposta solo il campo id. Per scorrere un numero elevato di elementi, imposta orderBy: ['-startTime'], limit sul numero di elementi per pagina e startedAfter su startTime dell'ultimo elemento dell'ultima pagina.

Parametri

Resi

setShelfEnabled()

Ritirato a partire da Chrome 117
chrome.downloads.setShelfEnabled(
  enabled: boolean,
): void

Utilizza setUiOptions.

Attiva o disattiva la barra grigia nella parte inferiore di ogni finestra associata al profilo del browser corrente. La mensola verrà disattivata finché almeno un'estensione non la riattiva. Se attivi la barra mentre almeno un'altra estensione l'ha disattivata, verrà restituito un errore tramite runtime.lastError. Richiede l'autorizzazione "downloads.shelf" oltre all'autorizzazione "downloads".

Parametri

  • attivato

    booleano

setUiOptions()

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

Modifica l'interfaccia utente di download di ogni finestra associata al profilo del browser corrente. Finché almeno un'estensione ha impostato UiOptions.enabled su false, l'interfaccia utente di download verrà nascosta. Se UiOptions.enabled è impostato su true mentre almeno un'altra estensione lo ha disattivato, verrà restituito un errore tramite runtime.lastError. Richiede l'autorizzazione "downloads.ui" oltre all'autorizzazione "downloads".

Parametri

  • opzioni

    UiOptions

    Incapsula una modifica all'UI di download.

Resi

  • Promise<void>

show()

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

Mostra il file scaricato nella relativa cartella in un gestore di file.

Parametri

  • downloadId

    numero

    L'identificatore del file scaricato.

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

Mostra la cartella Download predefinita in un file manager.

Eventi

onChanged

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

Quando una delle proprietà di un DownloadItem, ad eccezione di bytesReceived e estimatedEndTime, cambia, questo evento viene attivato con downloadId e un oggetto contenente le proprietà modificate.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (downloadDelta: DownloadDelta) => void

onCreated

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

Questo evento viene attivato con l'oggetto DownloadItem all'inizio di un download.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (downloadItem: DownloadItem) => void

onDeterminingFilename

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

Durante la procedura di determinazione del nome file, le estensioni avranno la possibilità di ignorare il DownloadItem.filename di destinazione. Ogni estensione può registrare non più di un ascoltatore per questo evento. Ogni listener deve chiamare suggest esattamente una volta, in modo sincrono o asincrono. Se il listener chiama suggest in modo asincrono, deve restituire true. Se il listener non chiama suggest in modo sincrono né restituisce true, suggest verrà chiamato automaticamente. La DownloadItem non verrà completata finché tutti gli ascoltatori non avranno chiamato il numero suggest. Gli ascoltatori possono chiamare suggest senza argomenti per consentire al download di utilizzare downloadItem.filename per il nome file oppure passare un oggetto suggestion a suggest per ignorare il nome file di destinazione. Se più di un'estensione esegue l'override del nome file, vince l'ultima estensione installata il cui listener passa un oggetto suggestion a suggest. Per evitare confusione su quale estensione avrà la precedenza, gli utenti non devono installare estensioni che potrebbero entrare in conflitto. Se il download viene avviato da download e il nome del file di destinazione è noto prima che siano stati determinati il tipo MIME e il nome del file provvisorio, passa filename a download.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (downloadItem: DownloadItem, suggest: function) => void

onErased

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

Viene attivato con downloadId quando un download viene cancellato dalla cronologia.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (downloadId: number) => void

    • downloadId

      numero