chrome.downloads

Descripción

Usa la API de chrome.downloads para iniciar, supervisar, manipular y buscar descargas de manera programática.

Permisos

downloads

Debes declarar el permiso "downloads" en el manifiesto de la extensión para usar esta API.

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

Ejemplos

Puedes encontrar ejemplos sencillos del uso de la API de chrome.downloads en el directorio examples/api/downloads. Para ver otros ejemplos y obtener ayuda para ver el código fuente, consulta Samples.

Tipos

BooleanDelta

Propiedades

  • actual

    booleano opcional

  • anterior

    booleano opcional

DangerType

archivo

El nombre del archivo de descarga es sospechoso.

url

Se sabe que la URL de descarga es maliciosa.

contenido

Se sabe que el archivo descargado es malicioso.

poco comunes

La URL de descarga no se descarga con frecuencia y podría ser peligrosa.

host

La descarga proviene de un host que se sabe que distribuye archivos binarios maliciosos y es probable que sea peligrosa.

no deseado

La descarga puede ser no deseada o insegura. Por ejemplo, podría cambiar la configuración del navegador o de la computadora.

seguro

La descarga no representa ningún peligro conocido para la computadora del usuario.

aceptada

El usuario aceptó la descarga peligrosa.

Enum

"file"

"url"

"content"

"uncommon"

"host"

"no deseado"

"safe"

"accepted"

"allowlistedByPolicy"

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

DoubleDelta

Propiedades

  • actual

    número opcional

  • anterior

    número opcional

DownloadDelta

Propiedades

  • canResume

    BooleanDelta opcional

    Cambio en canResume, si corresponde

  • peligro

    StringDelta opcional

    Cambio en danger, si corresponde

  • endTime

    StringDelta opcional

    Cambio en endTime, si corresponde

  • error

    StringDelta opcional

    Cambio en error, si corresponde

  • existe

    BooleanDelta opcional

    Cambio en exists, si corresponde

  • fileSize

    DoubleDelta opcional

    Cambio en fileSize, si corresponde

  • filename

    StringDelta opcional

    Cambio en filename, si corresponde

  • finalUrl

    StringDelta opcional

    Chrome 54 y versiones posteriores

    Cambio en finalUrl, si corresponde

  • id

    número

    Es el id del DownloadItem que cambió.

  • mimo

    StringDelta opcional

    Cambio en mime, si corresponde

  • detenido

    BooleanDelta opcional

    Cambio en paused, si corresponde

  • startTime

    StringDelta opcional

    Cambio en startTime, si corresponde

  • state

    StringDelta opcional

    Cambio en state, si corresponde

  • totalBytes

    DoubleDelta opcional

    Cambio en totalBytes, si corresponde

  • url

    StringDelta opcional

    Cambio en url, si corresponde

DownloadItem

Propiedades

  • byExtensionId

    cadena opcional

    Es el identificador de la extensión que inició esta descarga, si una extensión la inició. No cambia una vez que se configura.

  • byExtensionName

    cadena opcional

    Nombre localizado de la extensión que inició esta descarga, si una extensión la inició. Puede cambiar si la extensión cambia su nombre o si el usuario cambia su configuración regional.

  • bytesReceived

    número

    Cantidad de bytes recibidos hasta el momento del host, sin considerar la compresión de archivos.

  • canResume

    booleano

    Es verdadero si la descarga está en progreso y pausada, o bien si se interrumpió y se puede reanudar desde el punto en que se interrumpió.

  • peligro

    DangerType

    Indicación de si se cree que esta descarga es segura o se sabe que es sospechosa.

  • endTime

    cadena opcional

    Fecha y hora en que finalizó la descarga en formato ISO 8601. Se puede pasar directamente al constructor de Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

  • error

    InterruptReason opcional

    Indica por qué se interrumpió la descarga. Varios tipos de errores HTTP se pueden agrupar en uno de los errores que comienzan con SERVER_. Los errores relacionados con la red comienzan con NETWORK_, los errores relacionados con el proceso de escritura del archivo en el sistema de archivos comienzan con FILE_ y las interrupciones iniciadas por el usuario comienzan con USER_.

  • estimatedEndTime

    cadena opcional

    Es la hora estimada en la que se completará la descarga en formato ISO 8601. Se puede pasar directamente al constructor de Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

  • existe

    booleano

    Indica si el archivo descargado aún existe. Es posible que esta información no esté actualizada, ya que Chrome no supervisa automáticamente la eliminación de archivos. Llama a search() para activar la verificación de la existencia del archivo. Cuando se complete la verificación de existencia, si se borró el archivo, se activará un evento onChanged. Ten en cuenta que search() no espera a que finalice la verificación de existencia antes de devolver un valor, por lo que los resultados de search() pueden no reflejar con precisión el sistema de archivos. Además, se puede llamar a search() con la frecuencia que sea necesaria, pero no se verificará la existencia del archivo con una frecuencia mayor a una vez cada 10 segundos.

  • fileSize

    número

    Cantidad de bytes en todo el archivo después de la descompresión, o -1 si se desconoce.

  • filename

    string

    Es la ruta de acceso local absoluta.

  • finalUrl

    string

    Chrome 54 y versiones posteriores

    Es la URL absoluta desde la que se realiza esta descarga, después de todos los redireccionamientos.

  • id

    número

    Es un identificador que persiste en las sesiones del navegador.

  • Incógnito

    booleano

    Es falso si esta descarga se registra en el historial y verdadero si no se registra.

  • mimo

    string

    Es el tipo de MIME del archivo.

  • detenido

    booleano

    Es verdadero si la descarga dejó de leer datos del host, pero mantuvo la conexión abierta.

  • referente

    string

    Es una URL absoluta.

  • startTime

    string

    Fecha y hora en que comenzó la descarga en formato ISO 8601. Se puede pasar directamente al constructor de Date: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • state

    Estado

    Indica si la descarga está en curso, se interrumpió o se completó.

  • totalBytes

    número

    Cantidad de bytes en todo el archivo, sin considerar la compresión, o -1 si se desconoce.

  • url

    string

    Es la URL absoluta desde la que se inició esta descarga, antes de cualquier redireccionamiento.

DownloadOptions

Propiedades

  • body

    cadena opcional

    Cuerpo de la entrada.

  • conflictAction

    FilenameConflictAction opcional

    Es la acción que se debe realizar si ya existe filename.

  • filename

    cadena opcional

    Es la ruta de acceso a un archivo, relativa al directorio de descargas, que contendrá el archivo descargado y que puede incluir subdirectorios. Las rutas de acceso absolutas, las rutas de acceso vacías y las rutas de acceso que contienen referencias inversas ".." causarán un error. onDeterminingFilename permite sugerir un nombre de archivo después de que se hayan determinado el tipo de MIME del archivo y un nombre de archivo tentativo.

  • encabezados

    HeaderNameValuePair[] opcional

    Son encabezados HTTP adicionales que se enviarán con la solicitud si la URL usa el protocolo HTTP(S). Cada encabezado se representa como un diccionario que contiene las claves name y value o binaryValue, restringidas a las permitidas por XMLHttpRequest.

  • method

    HttpMethod opcional

    Es el método HTTP que se usará si la URL usa el protocolo HTTP[S].

  • saveAs

    booleano opcional

    Usa un selector de archivos para permitir que el usuario seleccione un nombre de archivo, independientemente de si filename está configurado o ya existe.

  • url

    string

    Es la URL que se descargará.

DownloadQuery

Propiedades

  • bytesReceived

    número opcional

    Cantidad de bytes recibidos hasta el momento del host, sin considerar la compresión de archivos.

  • peligro

    DangerType opcional

    Indicación de si se cree que esta descarga es segura o se sabe que es sospechosa.

  • endTime

    cadena opcional

    Fecha y hora en que finalizó la descarga en formato ISO 8601.

  • endedAfter

    cadena opcional

    Limita los resultados a DownloadItem que finalizaron después de los ms proporcionados en formato ISO 8601.

  • endedBefore

    cadena opcional

    Limita los resultados a DownloadItem que finalizaron antes de los milisegundos determinados en formato ISO 8601.

  • error

    InterruptReason opcional

    Indica por qué se interrumpió una descarga.

  • existe

    booleano opcional

    Indica si existe el archivo descargado.

  • fileSize

    número opcional

    Cantidad de bytes en todo el archivo después de la descompresión, o -1 si se desconoce.

  • filename

    cadena opcional

    Es la ruta de acceso local absoluta.

  • filenameRegex

    cadena opcional

    Limita los resultados a DownloadItem cuyo filename coincide con la expresión regular proporcionada.

  • finalUrl

    cadena opcional

    Chrome 54 y versiones posteriores

    Es la URL absoluta desde la que se realiza esta descarga, después de todos los redireccionamientos.

  • finalUrlRegex

    cadena opcional

    Chrome 54 y versiones posteriores

    Limita los resultados a DownloadItem cuyo finalUrl coincide con la expresión regular proporcionada.

  • id

    número opcional

    Es el id del objeto DownloadItem que se consultará.

  • límite

    número opcional

    Es la cantidad máxima de DownloadItem coincidentes que se devuelven. La configuración predeterminada es 1,000. Establécelo en 0 para devolver todos los DownloadItem coincidentes. Consulta search para obtener información sobre cómo navegar por los resultados.

  • mimo

    cadena opcional

    Es el tipo de MIME del archivo.

  • orderBy

    string[] opcional

    Establece los elementos de este array en propiedades DownloadItem para ordenar los resultados de la búsqueda. Por ejemplo, si se configura orderBy=['startTime'], se ordena DownloadItem por su hora de inicio en orden ascendente. Para especificar el orden descendente, agrega un guion al principio: "-startTime".

  • detenido

    booleano opcional

    Es verdadero si la descarga dejó de leer datos del host, pero mantuvo la conexión abierta.

  • consulta

    string[] opcional

    Este array de términos de búsqueda limita los resultados a DownloadItem cuyo filename, url o finalUrl contengan todos los términos de búsqueda que no comiencen con un guion "-" y ninguno de los términos de búsqueda que comiencen con un guion.

  • startTime

    cadena opcional

    Fecha y hora en que comenzó la descarga en formato ISO 8601.

  • startedAfter

    cadena opcional

    Limita los resultados a los DownloadItem que comenzaron después de los milisegundos determinados en formato ISO 8601.

  • startedBefore

    cadena opcional

    Limita los resultados a DownloadItem que comenzaron antes de los milisegundos determinados en formato ISO 8601.

  • state

    Estado opcional

    Indica si la descarga está en curso, se interrumpió o se completó.

  • totalBytes

    número opcional

    Cantidad de bytes en todo el archivo, sin considerar la compresión, o -1 si se desconoce.

  • totalBytesGreater

    número opcional

    Limita los resultados a DownloadItem cuyo totalBytes es mayor que el número entero proporcionado.

  • totalBytesLess

    número opcional

    Limita los resultados a DownloadItem cuyo totalBytes es menor que el número entero proporcionado.

  • url

    cadena opcional

    Es la URL absoluta desde la que se inició esta descarga, antes de cualquier redireccionamiento.

  • urlRegex

    cadena opcional

    Limita los resultados a DownloadItem cuyo url coincide con la expresión regular proporcionada.

FilenameConflictAction

uniquify

Para evitar la duplicación, se cambia el filename para incluir un contador antes de la extensión del nombre de archivo.

reemplazar

El archivo existente se reemplazará por el nuevo.

instrucción

Se le mostrará al usuario un diálogo de selección de archivos.

Enum

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

Propiedades

  • conflictAction

    FilenameConflictAction opcional

    Es la acción que se debe realizar si ya existe filename.

  • filename

    string

    El nuevo destino DownloadItem.filename del DownloadItem, como una ruta de acceso relativa al directorio de descargas predeterminado del usuario, que posiblemente contenga subdirectorios. Se ignorarán las rutas absolutas, las rutas vacías y las rutas que contengan referencias anteriores "..". Se ignora filename si alguna extensión registró objetos de escucha de onDeterminingFilename.

GetFileIconOptions

Propiedades

  • tamaño

    número opcional

    Es el tamaño del ícono devuelto. El ícono será cuadrado con dimensiones de tamaño * tamaño píxeles. El tamaño predeterminado y más grande del ícono es de 32 x 32 píxeles. Los únicos tamaños admitidos son 16 y 32. Es un error especificar cualquier otro tamaño.

HeaderNameValuePair

Propiedades

  • nombre

    string

    Nombre del encabezado HTTP.

  • valor

    string

    Valor del encabezado 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

Actualmente, la descarga está recibiendo datos del servidor.

Interrumpida

Se produjo un error que interrumpió la conexión con el host de archivos.

completo

La descarga se completó correctamente.

Enum

"in_progress"

"interrupted"

"complete"

StringDelta

Propiedades

  • actual

    cadena opcional

  • anterior

    cadena opcional

UiOptions

Chrome 105 y versiones posteriores

Propiedades

  • habilitado

    booleano

    Habilita o inhabilita la IU de descarga.

Métodos

acceptDanger()

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

Solicitar al usuario que acepte una descarga peligrosa Solo se puede llamar desde un contexto visible (pestaña, ventana o ventana emergente de acción del navegador o página). No acepta automáticamente las descargas peligrosas. Si se acepta la descarga, se activará un evento onChanged. De lo contrario, no sucederá nada. Cuando todos los datos se recuperan en un archivo temporal y la descarga no es peligrosa o se aceptó el peligro, se cambia el nombre del archivo temporal al nombre de archivo de destino, state cambia a "complete" y se activa onChanged.

Parámetros

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

cancel()

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

Cancela una descarga. Cuando se ejecuta callback, se cancela, completa o interrumpe la descarga, o bien ya no existe.

Parámetros

  • downloadId

    número

    Es el ID de la descarga que se cancelará.

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

download()

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

Descarga una URL. Si la URL usa el protocolo HTTP(S), la solicitud incluirá todas las cookies configuradas actualmente para su nombre de host. Si se especifican filename y saveAs, se mostrará el diálogo Guardar como, con el filename especificado ya completado. Si la descarga se inició correctamente, se llamará a callback con el nuevo downloadId de DownloadItem. Si se produjo un error al iniciar la descarga, se llamará a callback con downloadId=undefined y runtime.lastError contendrá una cadena descriptiva. No se garantiza que las cadenas de error sigan siendo retrocompatibles entre las versiones. Las extensiones no deben analizarlo.

Parámetros

Muestra

  • Promise<number>

    Chrome 96 y versiones posteriores

erase()

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

Borra la DownloadItem coincidente del historial sin borrar el archivo descargado. Se activará un evento onErased para cada DownloadItem que coincida con query y, luego, se llamará a callback.

Parámetros

Muestra

  • Promise<number[]>

    Chrome 96 y versiones posteriores

getFileIcon()

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

Recupera un ícono para la descarga especificada. En el caso de las descargas nuevas, los íconos de archivo están disponibles después de que se recibe el evento onCreated. La imagen que devuelve esta función mientras se descarga puede ser diferente de la que se devuelve después de que se completa la descarga. La recuperación de íconos se realiza consultando el sistema operativo o el kit de herramientas subyacente, según la plataforma. Por lo tanto, el ícono que se muestra dependerá de varios factores, como el estado de la descarga, la plataforma, los tipos de archivo registrados y el tema visual. Si no se puede determinar el ícono de un archivo, runtime.lastError contendrá un mensaje de error.

Parámetros

  • downloadId

    número

    Es el identificador de la descarga.

  • opciones

    GetFileIconOptions opcional

Muestra

  • Promesa<cadena | undefined>

    Chrome 96 y versiones posteriores

open()

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

Abre el archivo descargado ahora si DownloadItem se completó; de lo contrario, muestra un error a través de runtime.lastError. Este método requiere el permiso "downloads.open" además del permiso "downloads". Se activa un evento onChanged cuando se abre el elemento por primera vez. Solo se puede llamar a este método en respuesta a un gesto del usuario.

Parámetros

  • downloadId

    número

    Es el identificador del archivo descargado.

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores

pause()

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

Pausa la descarga. Si la solicitud se realizó correctamente, la descarga estará en estado de pausa. De lo contrario, runtime.lastError contiene un mensaje de error. La solicitud fallará si la descarga no está activa.

Parámetros

  • downloadId

    número

    Es el ID de la descarga que se pausará.

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

removeFile()

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

Quita el archivo descargado si existe y el DownloadItem está completo. De lo contrario, devuelve un error a través de runtime.lastError.

Parámetros

  • downloadId

    número

Muestra

  • Promise<void>

    Chrome 96 y versiones posteriores

resume()

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

Reanuda una descarga pausada. Si la solicitud se realizó correctamente, la descarga estará en curso y no se pausará. De lo contrario, runtime.lastError contiene un mensaje de error. La solicitud fallará si la descarga no está activa.

Parámetros

  • downloadId

    número

    Es el ID de la descarga que se reanudará.

Muestra

  • Promise<void>

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

Busca DownloadItem. Establece query en el objeto vacío para obtener todos los DownloadItem. Para obtener un DownloadItem específico, establece solo el campo id. Para paginar una gran cantidad de elementos, establece orderBy: ['-startTime'], configura limit en la cantidad de elementos por página y establece startedAfter en el startTime del último elemento de la última página.

Parámetros

Muestra

setShelfEnabled()

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

En su lugar, usa setUiOptions.

Habilita o inhabilita la barra gris en la parte inferior de cada ventana asociada con el perfil del navegador actual. La biblioteca se inhabilitará mientras al menos una extensión la haya inhabilitado. Si habilitas la biblioteca cuando al menos otra extensión la haya inhabilitado, se devolverá un error a través de runtime.lastError. Requiere el permiso "downloads.shelf" además del permiso "downloads".

Parámetros

  • habilitado

    booleano

setUiOptions()

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

Cambia la IU de descarga de cada ventana asociada al perfil de navegador actual. Mientras al menos una extensión tenga el parámetro UiOptions.enabled establecido como falso, se ocultará la IU de descarga. Si se configura UiOptions.enabled como verdadero mientras al menos otra extensión lo inhabilitó, se mostrará un error a través de runtime.lastError. Requiere el permiso "downloads.ui" además del permiso "downloads".

Parámetros

  • opciones

    UiOptions

    Encapsula un cambio en la IU de descarga.

Muestra

  • Promise<void>

show()

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

Mostrar el archivo descargado en su carpeta en un administrador de archivos

Parámetros

  • downloadId

    número

    Es el identificador del archivo descargado.

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

Muestra la carpeta Descargas predeterminada en un administrador de archivos.

Eventos

onChanged

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

Cuando cambia alguna de las propiedades de un DownloadItem, excepto bytesReceived y estimatedEndTime, este evento se activa con downloadId y un objeto que contiene las propiedades que cambiaron.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (downloadDelta: DownloadDelta) => void

onCreated

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

Este evento se activa con el objeto DownloadItem cuando comienza una descarga.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (downloadItem: DownloadItem) => void

onDeterminingFilename

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

Durante el proceso de determinación del nombre de archivo, las extensiones tendrán la oportunidad de anular el DownloadItem.filename de destino. Cada extensión no puede registrar más de un objeto de escucha para este evento. Cada objeto de escucha debe llamar a suggest exactamente una vez, ya sea de forma síncrona o asíncrona. Si el objeto de escucha llama a suggest de forma asíncrona, debe devolver true. Si el objeto de escucha no llama a suggest de forma síncrona ni devuelve true, se llamará a suggest automáticamente. El DownloadItem no se completará hasta que todos los objetos de escucha llamen a suggest. Los objetos de escucha pueden llamar a suggest sin argumentos para permitir que la descarga use downloadItem.filename para su nombre de archivo o pasar un objeto suggestion a suggest para anular el nombre de archivo de destino. Si más de una extensión anula el nombre de archivo, gana la última extensión instalada cuyo objeto de escucha pasa un objeto suggestion a suggest. Para evitar confusiones sobre qué extensión ganará, los usuarios no deben instalar extensiones que puedan entrar en conflicto. Si download inicia la descarga y se conoce el nombre de archivo de destino antes de que se determinen el tipo de MIME y el nombre de archivo tentativo, pasa filename a download.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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

onErased

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

Se activa con downloadId cuando se borra una descarga del historial.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (downloadId: number) => void

    • downloadId

      número