chrome.downloads

Описание

Используйте API chrome.downloads для программного запуска, мониторинга, управления и поиска загрузок.

Разрешения

downloads

Для использования этого API необходимо указать разрешение "downloads" в манифесте расширения .

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

Примеры

Простые примеры использования API chrome.downloads можно найти в каталоге examples/api/downloads . Другие примеры и помощь в просмотре исходного кода см. в разделе Samples .

Типы

BooleanDelta

Характеристики

  • текущий

    логический необязательный

  • предыдущий

    логический необязательный

DangerType

Перечисление

"файл"
Название загружаемого файла вызывает подозрения.

"url"
Известно, что URL-адрес для скачивания является вредоносным.

"содержание"
Известно, что загруженный файл является вредоносным.

«необычный»
Ссылка для скачивания используется редко и может быть опасной.

"хозяин"
Загрузка произошла с хостинга, известного распространением вредоносных бинарных файлов, и, вероятно, представляет опасность.

«нежелательный»
Загрузка потенциально нежелательна или небезопасна. Например, она может внести изменения в настройки браузера или компьютера.

"безопасный"
Загрузка не представляет никакой известной опасности для компьютера пользователя.

"принял"
Пользователь дал согласие на загрузку опасного файла.

"allowlistedByPolicy"
Ценности, связанные с предприятием.

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

"forceSaveToGdrive"
Для использования расширением Secure Enterprise Browser. При необходимости Chrome заблокирует загрузку на диск и загрузит файл непосредственно в Google Диск.

DoubleDelta

Характеристики

  • текущий

    число необязательно

  • предыдущий

    число необязательно

DownloadDelta

Характеристики

  • canResume

    BooleanDelta optional

    Изменения в canResume , если таковые имеются.

  • Опасность

    StringDelta optional

    Изменение уровня danger , если таковое имелось.

  • endTime

    StringDelta optional

    Изменение endTime , если таковое имелось.

  • ошибка

    StringDelta optional

    Изменение error , если таковое имеется.

  • существует

    BooleanDelta optional

    Изменение exists , если таковое имеется.

  • размер файла

    DoubleDelta опционально

    Изменение fileSize , если таковое имелось.

  • имя файла

    StringDelta optional

    Изменение filename , если таковое имелось.

  • finalUrl

    StringDelta optional

    Chrome 54+

    Изменение параметра finalUrl , если таковое имелось.

  • идентификатор

    число

    id объекта DownloadItem , который изменился.

  • мим

    StringDelta optional

    Изменения в mime , если таковые имеются.

  • пауза

    BooleanDelta optional

    Изменения paused , если таковые имеются.

  • startTime

    StringDelta optional

    Изменение startTime , если таковое имелось.

  • состояние

    StringDelta optional

    Изменение state , если таковое имелось.

  • totalBytes

    DoubleDelta опционально

    Изменение totalBytes , если таковое имеется.

  • url

    StringDelta optional

    Изменение url , если таковое имелось.

DownloadItem

Характеристики

  • byExtensionId

    строка необязательный

    Идентификатор расширения, инициировавшего эту загрузку, если загрузка была инициирована расширением. После установки не изменяется.

  • byExtensionName

    строка необязательный

    Локализованное название расширения, инициировавшего загрузку, если загрузка была инициирована расширением. Может измениться, если расширение изменит свое название или если пользователь изменит свои языковые настройки.

  • байтыПолучено

    число

    Количество байтов, полученных от хоста на данный момент, без учета сжатия файла.

  • canResume

    логический

    Возвращает true, если загрузка находится в процессе и приостановлена, или если она прервана и может быть возобновлена ​​с того места, где была прервана.

  • Опасность

    Указывает, считается ли данная загрузка безопасной или заведомо подозрительной.

  • endTime

    строка необязательный

    Время завершения загрузки в формате ISO 8601. Может быть передано непосредственно в конструктор Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

  • ошибка

    InterruptReason ( необязательно)

    Причина прерывания загрузки. Несколько типов HTTP-ошибок могут быть сгруппированы под одной из ошибок, начинающихся с SERVER_ . Ошибки, связанные с сетью, начинаются с NETWORK_ , ошибки, связанные с процессом записи файла в файловую систему, начинаются с FILE_ , а прерывания, инициированные пользователем, начинаются с USER_ .

  • estimatedEndTime

    строка необязательный

    Примерное время завершения загрузки в формате ISO 8601. Может быть передано непосредственно в конструктор Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

  • существует

    логический

    Проверьте, существует ли загруженный файл. Эта информация может быть устаревшей, поскольку Chrome не отслеживает удаление файлов автоматически. Вызовите search (), чтобы запустить проверку существования файла. После завершения проверки существования, если файл был удален, сработает событие onChanged . Обратите внимание, что search () не ждет завершения проверки существования перед возвратом, поэтому результаты search () могут неточно отражать состояние файловой системы. Кроме того, функцию search () можно вызывать так часто, как это необходимо, но проверка существования файла будет выполняться не чаще одного раза в 10 секунд.

  • размер файла

    число

    Количество байтов во всем файле после декомпрессии или -1, если значение неизвестно.

  • имя файла

    нить

    Абсолютно местная тропа.

  • finalUrl

    нить

    Chrome 54+

    Абсолютный URL-адрес, с которого осуществляется загрузка, с учетом всех перенаправлений.

  • идентификатор

    число

    Идентификатор, сохраняющийся между сеансами работы браузера.

  • инкогнито

    логический

    Значение "false", если эта загрузка записана в историю, значение "true", если она не записана.

  • мим

    нить

    MIME-тип файла.

  • пауза

    логический

    Возвращает true, если процесс загрузки прекратил чтение данных с хоста, но соединение осталось открытым.

  • реферер

    нить

    Абсолютный URL.

  • startTime

    нить

    Время начала загрузки в формате ISO 8601. Может быть передано непосредственно в конструктор Date: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • состояние

    Указывает, идёт ли загрузка, прервана или завершена.

  • totalBytes

    число

    Количество байтов во всем файле без учета сжатия файла или -1, если значение неизвестно.

  • url

    нить

    Абсолютный URL-адрес, с которого началась загрузка, до каких-либо перенаправлений.

DownloadOptions

Характеристики

  • тело

    строка необязательный

    Тело после публикации.

  • конфликтДействие

    FilenameConflictAction (необязательно)

    Действие, которое следует предпринять, если filename уже существует.

  • имя файла

    строка необязательный

    Путь к файлу относительно каталога «Загрузки», содержащий загруженный файл, может включать подкаталоги. Абсолютные пути, пустые пути и пути, содержащие обратные ссылки "." приведут к ошибке. onDeterminingFilename позволяет предложить имя файла после определения MIME-типа файла и предварительного имени файла.

  • заголовки

    HeaderNameValuePair [] optional

    Дополнительные HTTP-заголовки для отправки вместе с запросом, если URL использует протокол HTTP[s]. Каждый заголовок представлен в виде словаря, содержащего ключи name и либо value , либо binaryValue , ограниченного теми, которые разрешены XMLHttpRequest.

  • метод

    HttpMethod (необязательный параметр)

    Метод HTTP, используемый, если URL использует протокол HTTP[S].

  • сохранить как

    логический необязательный

    Используйте средство выбора файла, чтобы пользователь мог выбрать имя файла независимо от того, задано ли это имя или filename уже существует.

  • url

    нить

    URL для скачивания.

DownloadQuery

Характеристики

  • байтыПолучено

    число необязательно

    Количество байтов, полученных от хоста на данный момент, без учета сжатия файла.

  • Опасность

    DangerType ( необязательно)

    Указывает, считается ли данная загрузка безопасной или заведомо подозрительной.

  • endTime

    строка необязательный

    Момент завершения загрузки в формате ISO 8601.

  • закончилось после

    строка необязательный

    Ограничивает результаты только DownloadItem , завершившейся по истечении заданного времени в формате ISO 8601.

  • закончилось до

    строка необязательный

    Ограничивает результаты поиска только DownloadItem , завершившимися до истечения указанного времени в формате ISO 8601.

  • ошибка

    InterruptReason ( необязательно)

    Почему произошла ошибка при загрузке.

  • существует

    логический необязательный

    Существует ли загруженный файл;

  • размер файла

    число необязательно

    Количество байтов во всем файле после декомпрессии или -1, если значение неизвестно.

  • имя файла

    строка необязательный

    Абсолютно местная тропа.

  • filenameRegex

    строка необязательный

    Ограничивает результаты только теми объектами DownloadItem , filename которых соответствуют заданному регулярному выражению.

  • finalUrl

    строка необязательный

    Chrome 54+

    Абсолютный URL-адрес, с которого осуществляется загрузка, с учетом всех перенаправлений.

  • finalUrlRegex

    строка необязательный

    Chrome 54+

    Ограничивает результаты только теми объектами DownloadItem , чей finalUrl соответствует заданному регулярному выражению.

  • идентификатор

    число необязательно

    id объекта DownloadItem для запроса.

  • лимит

    число необязательно

    Максимальное количество возвращаемых совпадений DownloadItem . По умолчанию — 1000. Установите значение 0, чтобы вернуть все совпадающие DownloadItem . См. search , как пролистывать результаты.

  • мим

    строка необязательный

    MIME-тип файла.

  • orderBy

    строка[] необязательный

    Для сортировки результатов поиска присваивайте элементам этого массива свойства типа DownloadItem . Например, параметр orderBy=['startTime'] сортирует элементы DownloadItem по времени начала в порядке возрастания. Чтобы указать порядок убывания, добавьте дефис: '-startTime'.

  • пауза

    логический необязательный

    Возвращает true, если процесс загрузки прекратил чтение данных с хоста, но соединение осталось открытым.

  • запрос

    строка[] необязательный

    Этот набор поисковых запросов ограничивает результаты поиска только теми файлами DownloadItem , filename , url или finalUrl которых содержат все поисковые запросы, не начинающиеся с дефиса '-', и ни одного из поисковых запросов, начинающихся с дефиса.

  • startTime

    строка необязательный

    Время начала загрузки в формате ISO 8601.

  • началосьПосле

    строка необязательный

    Ограничивает результаты только DownloadItem , начавшейся после указанного времени в формате ISO 8601.

  • началось до

    строка необязательный

    Ограничивает результаты поиска только DownloadItem , запуск которых был произведен до указанного времени в формате ISO 8601.

  • состояние

    Указать необязательно

    Указывает, идёт ли загрузка, прервана или завершена.

  • totalBytes

    число необязательно

    Количество байтов во всем файле без учета сжатия файла или -1, если значение неизвестно.

  • totalBytesGreater

    число необязательно

    Ограничивает результаты только теми объектами DownloadItem , у которых totalBytes превышает заданное целое число.

  • totalBytesLess

    число необязательно

    Ограничивает результаты только теми объектами DownloadItem , у которых totalBytes меньше заданного целого числа.

  • url

    строка необязательный

    Абсолютный URL-адрес, с которого началась загрузка, до каких-либо перенаправлений.

  • urlRegex

    строка необязательный

    Ограничивает результаты только теми объектами DownloadItem , url которых соответствует заданному регулярному выражению.

FilenameConflictAction

уникальный

Во избежание дублирования filename изменяется таким образом, чтобы перед расширением файла добавлялся счетчик.

перезаписать

Существующий файл будет перезаписан новым файлом.

быстрый

Пользователю будет предложено открыть диалоговое окно выбора файла.

Перечисление

"уникализировать"

"перезапись"

"быстрый"

FilenameSuggestion

Характеристики

  • конфликтДействие

    FilenameConflictAction (необязательно)

    Действие, которое следует предпринять, если filename уже существует.

  • имя файла

    нить

    Новый целевой объект DownloadItem — это DownloadItem.filename , путь к которому указывается относительно папки «Загрузки» пользователя по умолчанию и может содержать подкаталоги. Абсолютные пути, пустые пути и пути, содержащие обратные ссылки "." будут игнорироваться. filename игнорируется, если для каких-либо расширений зарегистрированы обработчики событий onDeterminingFilename .

GetFileIconOptions

Характеристики

  • размер

    число необязательно

    Размер возвращаемого значка. Значок будет квадратным с размерами size * size пикселей. Максимальный размер значка по умолчанию — 32x32 пикселя. Поддерживаются только размеры 16 и 32. Указание любого другого размера является ошибкой.

HeaderNameValuePair

Характеристики

  • имя

    нить

    Название HTTP-заголовка.

  • ценить

    нить

    Значение заголовка HTTP.

HttpMethod

Перечисление

"ПОЛУЧАТЬ"

"ПОЧТА"

InterruptReason

Перечисление

"FILE_FAILED"

"ДОСТУП К ФАЙЛУ ЗАПРЕЩЕН"

"FILE_NO_SPACE"

"FILE_NAME_TOO_LONG"

"ФАЙЛ_СЛИШКОМ_БОЛЬШОЙ"

"ФАЙЛ_ЗАРАЖЕН_ВИРУСОМ"

"FILE_TRANSIENT_ERROR"

"ФАЙЛ_ЗАБЛОКИРОВАН"

"FILE_SECURITY_CHECK_FAILED"

"Слишком короткий файл"

"FILE_HASH_MISMATCH"

"FILE_SAME_AS_SOURCE"

"Сбой сети"

"NETWORK_TIMEOUT"

"СЕТЬ ОТКЛЮЧЕНА"

"Сетевой сервер недоступен"

"NETWORK_INVALID_REQUEST"

"SERVER_FAILED"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"SERVER_UNAUTHORIZED"

"ПРОБЛЕМА СЕРВЕРНОГО СЕРТИФИКАТА"

"SERVER_FORBIDDEN"

"Сервер недоступен"

"SERVER_CONTENT_LENGTH_MISMATCH"

"SERVER_CROSS_ORIGIN_REDIRECT"

"USER_CANCELED"

"USER_SHUTDOWN"

"КРУШЕНИЕ"

State

в ходе выполнения

В данный момент происходит загрузка данных с сервера.

прерванный

Произошла ошибка, прервавшая соединение с файловым хостом.

полный

Загрузка успешно завершена.

Перечисление

"в ходе выполнения"

«прерванный»

"полный"

StringDelta

Характеристики

  • текущий

    строка необязательный

  • предыдущий

    строка необязательный

UiOptions

Chrome 105+

Характеристики

  • включено

    логический

    Включить или отключить интерфейс загрузки.

Методы

acceptDanger()

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

Предлагается пользователю принять опасную загрузку. Может быть вызвана только из видимого контекста (вкладка, окно или всплывающее окно действия страницы/браузера). Не принимает опасные загрузки автоматически. Если загрузка принята, срабатывает событие onChanged , в противном случае ничего не происходит. Когда все данные загружены во временный файл и загрузка либо не опасна, либо опасность принята, временный файл переименовывается в целевое имя файла, state изменяется на «завершено», и срабатывает событие onChanged .

Параметры

  • downloadId

    число

    Идентификатор элемента DownloadItem ).

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает Promise, который разрешается при закрытии диалогового окна с предупреждением об опасности.

cancel()

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

Отмена загрузки. При выполнении callback загрузка отменяется, завершается, прерывается или перестает существовать.

Параметры

  • downloadId

    число

    Идентификатор загрузки, которую нужно отменить.

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает Promise, который разрешается после завершения запроса на отмену.

download()

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

Загрузите URL-адрес. Если URL-адрес использует протокол HTTP[S], то запрос будет включать все файлы cookie, установленные в данный момент для его имени хоста. Если указаны и filename , и saveAs , то будет отображено диалоговое окно «Сохранить как», предварительно заполненное указанным filename . Если загрузка началась успешно, будет вызвана callback с downloadId нового DownloadItem . Если при начале загрузки произошла ошибка, то будет вызвана callback с downloadId=undefined , а runtime.lastError будет содержать описательную строку. Обратная совместимость строк ошибок между версиями не гарантируется. Расширения не должны их анализировать.

Параметры

Возвраты

  • Обещание<число>

    Chrome 96+

    Возвращает промис, который разрешается с идентификатором нового DownloadItem .

erase()

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

Удалите соответствующий DownloadItem из истории, не удаляя загруженный файл. Для каждого DownloadItem , соответствующего query , будет срабатывать событие onErased , после чего будет вызвана callback .

Параметры

Возвраты

  • Обещание<число[]>

    Chrome 96+

getFileIcon()

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

Получает значок для указанного загружаемого файла. Для новых загрузок значки файлов становятся доступны после получения события onCreated . Изображение, возвращаемое этой функцией во время загрузки, может отличаться от изображения, возвращаемого после завершения загрузки. Получение значка осуществляется путем запроса к базовой операционной системе или инструментарию в зависимости от платформы. Таким образом, возвращаемый значок будет зависеть от ряда факторов, включая состояние загрузки, платформу, зарегистрированные типы файлов и визуальную тему. Если значок файла определить не удается, runtime.lastError будет содержать сообщение об ошибке.

Параметры

  • downloadId

    число

    Идентификатор для загрузки.

  • параметры

    GetFileIconOptions ( необязательный параметр)

Возвраты

  • Promise<string | undefined>

    Chrome 96+

    Возвращает промис, который разрешается с URL-адресом изображения, представляющего собой объект для загрузки.

open()

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

Если DownloadItem завершена, метод открывает загруженный файл; в противном случае возвращает ошибку через runtime.lastError . Для этого метода требуется разрешение "downloads.open" в дополнение к разрешению "downloads" . Событие onChanged срабатывает при первом открытии элемента. Этот метод может быть вызван только в ответ на действие пользователя.

Параметры

  • downloadId

    число

    Идентификатор загруженного файла.

Возвраты

  • Обещание<пустота>

    Chrome 123+

pause()

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

Приостановите загрузку. Если запрос был успешным, загрузка находится в приостановленном состоянии. В противном случае runtime.lastError содержит сообщение об ошибке. Запрос завершится неудачей, если загрузка неактивна.

Параметры

  • downloadId

    число

    Идентификатор загрузки, которую нужно приостановить.

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает промис, который разрешается после завершения запроса на приостановку.

removeFile()

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

Удалите загруженный файл, если он существует и DownloadItem завершен; в противном случае верните ошибку через runtime.lastError .

Параметры

  • downloadId

    число

Возвраты

  • Обещание<пустота>

    Chrome 96+

resume()

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

Возобновить приостановленную загрузку. Если запрос был успешным, загрузка продолжается и не приостановлена. В противном случае runtime.lastError содержит сообщение об ошибке. Запрос завершится неудачей, если загрузка неактивна.

Параметры

  • downloadId

    число

    Идентификатор загрузки, которую необходимо возобновить.

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает Promise, который разрешается после завершения запроса на возобновление работы.

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

Найдите DownloadItem . Установите query к пустому объекту, чтобы получить все DownloadItem . Чтобы получить конкретный DownloadItem , укажите только поле id . Для постраничного просмотра большого количества элементов установите orderBy: ['-startTime'] , установите limit равным количеству элементов на странице и установите startedAfter равным startTime последнего элемента с последней страницы.

Параметры

Возвраты

setShelfEnabled()

Устарело с версии Chrome 117.
chrome.downloads.setShelfEnabled(
  enabled: boolean,
)
: void

Вместо этого используйте setUiOptions .

Включить или отключить серую панель внизу каждого окна, связанного с текущим профилем браузера. Панель будет отключена, пока хотя бы одно расширение её отключило. Включение панели, когда хотя бы одно другое расширение её отключило, приведёт к ошибке через runtime.lastError . Для этого требуется разрешение "downloads.shelf" в дополнение к разрешению "downloads" .

Параметры

  • включено

    логический

setUiOptions()

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

Изменяет интерфейс загрузки для каждого окна, связанного с текущим профилем браузера. Пока хотя бы одно расширение установило параметр UiOptions.enabled в значение false, интерфейс загрузки будет скрыт. Установка UiOptions.enabled в значение true, если хотя бы одно другое расширение отключило его, приведет к ошибке через runtime.lastError . Требуется разрешение "downloads.ui" в дополнение к разрешению "downloads" .

Параметры

  • параметры

    Оформите изменение в пользовательском интерфейсе загрузки.

Возвраты

  • Обещание<пустота>

    Возвращает Promise, который разрешается после завершения обновления пользовательского интерфейса.

show()

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

Отобразить загруженный файл в папке в файловом менеджере.

Параметры

  • downloadId

    число

    Идентификатор загруженного файла.

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

Отобразить папку «Загрузки» по умолчанию в файловом менеджере.

События

onChanged

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

При изменении любого из свойств объекта DownloadItem , кроме bytesReceived и estimatedEndTime , срабатывает это событие с идентификатором downloadId и объектом, содержащим измененные свойства.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит следующим образом:

    (downloadDelta: DownloadDelta) => void

onCreated

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

Это событие срабатывает с объектом DownloadItem при начале загрузки.

Параметры

onDeterminingFilename

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

В процессе определения имени файла расширениям будет предоставлена ​​возможность переопределить целевое имя файла DownloadItem.filename . Каждое расширение не может зарегистрировать более одного обработчика для этого события. Каждый обработчик должен вызвать suggest ровно один раз, синхронно или асинхронно. Если обработчик вызывает suggest асинхронно, он должен вернуть true . Если обработчик не вызывает suggest синхронно и не возвращает true , то suggest будет вызван автоматически. DownloadItem не завершится, пока все обработчики не вызовут suggest . Обработчики могут вызывать suggest без аргументов, чтобы разрешить загрузке использовать downloadItem.filename в качестве имени файла, или передать объект suggestion в suggest , чтобы переопределить целевое имя файла. Если более одного расширения переопределяет имя файла, то побеждает последнее установленное расширение, обработчик которого передает объект suggestion в suggest . Во избежание путаницы относительно того, какое расширение будет иметь приоритет, пользователям не следует устанавливать расширения, которые могут конфликтовать. Если загрузка инициируется функцией download , и имя целевого файла известно до того, как будут определены MIME-тип и предварительное имя файла, передайте filename download .

Параметры

  • перезвонить

    функция

    Параметр callback выглядит следующим образом:

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

onErased

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

Событие срабатывает с идентификатором downloadId , когда загрузка удаляется из истории.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит следующим образом:

    (downloadId: number) => void

    • downloadId

      число