Описание
Используйте API chrome.downloads для программного запуска, мониторинга, управления и поиска загрузок.
Разрешения
downloads Для использования этого API необходимо указать разрешение "downloads" в манифесте расширения .
{
"name": "My extension",
...
"permissions": [
"downloads"
],
}
Примеры
Простые примеры использования API chrome.downloads можно найти в каталоге examples/api/downloads . Другие примеры и помощь в просмотре исходного кода см. в разделе Samples .
Типы
BooleanDelta
Характеристики
- текущий
логический необязательный
- предыдущий
логический необязательный
DangerType
Перечисление
"файл" "url" "содержание" «необычный» "хозяин" «нежелательный» "безопасный" "принял" "allowlistedByPolicy" "asyncScanning" "asyncLocalPasswordScanning" "passwordProtected" "blockedTooLarge" "sensitiveContentWarning" "sensitiveContentBlock" "deepScannedFailed" "deepScannedSafe" "deepScannedOpenedDangerous" "promptForScanning" "promptForLocalPasswordScanning" "accountCompromise" "blockedScanFailed" "forceSaveToGdrive"
Название загружаемого файла вызывает подозрения.
Известно, что URL-адрес для скачивания является вредоносным.
Известно, что загруженный файл является вредоносным.
Ссылка для скачивания используется редко и может быть опасной.
Загрузка произошла с хостинга, известного распространением вредоносных бинарных файлов, и, вероятно, представляет опасность.
Загрузка потенциально нежелательна или небезопасна. Например, она может внести изменения в настройки браузера или компьютера.
Загрузка не представляет никакой известной опасности для компьютера пользователя.
Пользователь дал согласие на загрузку опасного файла.
Ценности, связанные с предприятием.
Для использования расширением 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
Характеристики
- включено
логический
Включить или отключить интерфейс загрузки.
Методы
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, который разрешается после завершения запроса на возобновление работы.
search()
chrome.downloads.search(
query: DownloadQuery,
): Promise<DownloadItem[]>
Найдите DownloadItem . Установите query к пустому объекту, чтобы получить все DownloadItem . Чтобы получить конкретный DownloadItem , укажите только поле id . Для постраничного просмотра большого количества элементов установите orderBy: ['-startTime'] , установите limit равным количеству элементов на странице и установите startedAfter равным startTime последнего элемента с последней страницы.
Параметры
- запрос
Возвраты
Promise< DownloadItem []>
Chrome 96+
setShelfEnabled()
chrome.downloads.setShelfEnabled(
enabled: boolean,
): void
Вместо этого используйте setUiOptions .
Включить или отключить серую панель внизу каждого окна, связанного с текущим профилем браузера. Панель будет отключена, пока хотя бы одно расширение её отключило. Включение панели, когда хотя бы одно другое расширение её отключило, приведёт к ошибке через runtime.lastError . Для этого требуется разрешение "downloads.shelf" в дополнение к разрешению "downloads" .
Параметры
- включено
логический
setUiOptions()
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 при начале загрузки.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(downloadItem: DownloadItem) => void
- 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
- downloadItem
- предлагать
функция
Параметр
suggestвыглядит следующим образом:(suggestion?: FilenameSuggestion) => void
- предположение
FilenameSuggestion (необязательно)
onErased
chrome.downloads.onErased.addListener(
callback: function,
)
Событие срабатывает с идентификатором downloadId , когда загрузка удаляется из истории.
Параметры
- перезвонить
функция
Параметр
callbackвыглядит следующим образом:(downloadId: number) => void
- downloadId
число