chrome.downloads (original) (raw)

Перейти к основному контенту

Описание

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

Разрешения

downloads

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

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

Примеры

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

Типы

BooleanDelta

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

DangerType

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

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

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

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

"необычный"
URL-адрес загрузки обычно не загружается и может быть опасен.

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

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

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

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

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

"асинхронное сканирование"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

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

DoubleDelta

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

DownloadDelta

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

DownloadItem

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

DownloadOptions

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

DownloadQuery

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

FilenameConflictAction

uniquify

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

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

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

быстрый

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

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

"уникифицировать"

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

"быстрый"

FilenameSuggestion

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

GetFileIconOptions

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

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

HttpMethod

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

InterruptReason

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

"FILE_FAILED"

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

"FILE_NO_SPACE"

"FILE_NAME_TOO_LONG"

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

"FILE_VIRUS_INFECTED"

"FILE_TRANSIENT_ERROR"

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

"FILE_SECURITY_CHECK_FAILED"

"ФАЙЛ_СЛИШКОМ_КОРОТКИЙ"

"FILE_HASH_MISMATCH"

"FILE_SAME_AS_SOURCE"

"NETWORK_FAILED"

"NETWORK_TIMEOUT"

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

"СЕТЕВОЙ_СЕРВЕР_ОТКЛЮЧЕН"

"NETWORK_INVALID_REQUEST"

"СЕРВЕР_ОШИБСЯ"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"СЕРВЕР_НЕАВТОРИЗОВАН"

"SERVER_CERT_PROBLEM"

"SERVER_FORBIDDEN"

"СЕРВЕР_НЕДОСТУПЕН"

"SERVER_CONTENT_LENGTH_MISMATCH"

"SERVER_CROSS_ORIGIN_REDIRECT"

"USER_CANCELED"

"USER_SHUTDOWN"

"КРУШЕНИЕ"

State

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

В настоящее время загрузка получает данные с сервера.

прерванный

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

полный

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

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

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

"прерванный"

"полный"

StringDelta

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

UiOptions

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

Методы

acceptDanger()

chrome.downloads.acceptDanger(
  downloadId: number,
): Promise

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

Параметры

Возврат

cancel()

chrome.downloads.cancel(
  downloadId: number,
): Promise

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

Параметры

Возврат

download()

chrome.downloads.download(
  options: DownloadOptions,
): Promise

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

Параметры

Возврат

erase()

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

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

Параметры

Возврат

getFileIcon()

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

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

Параметры

Возврат

open()

chrome.downloads.open(
  downloadId: number,
): Promise

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

Параметры

Возврат

pause()

chrome.downloads.pause(
  downloadId: number,
): Promise

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

Параметры

Возврат

removeFile()

chrome.downloads.removeFile(
  downloadId: number,
): Promise

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

Параметры

Возврат

resume()

chrome.downloads.resume(
  downloadId: number,
): Promise

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

Параметры

Возврат

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.downloads.setUiOptions(
  options: UiOptions,
): Promise

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

Параметры

Возврат

show()

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

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

Параметры

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

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

События

onChanged

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

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

Параметры

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 .

Параметры

onErased

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

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

Параметры

Если не указано иное, контент на этой странице предоставляется по лицензии Creative Commons "С указанием авторства 4.0", а примеры кода – по лицензии Apache 2.0. Подробнее об этом написано в правилах сайта. Java – это зарегистрированный товарный знак корпорации Oracle и ее аффилированных лиц.

Последнее обновление: 2025-11-10 UTC.