chrome.downloads

Deskripsi

Gunakan chrome.downloads API untuk memulai, memantau, memanipulasi, dan menelusuri download secara terprogram.

Izin

downloads

Anda harus mendeklarasikan izin "downloads" di manifes ekstensi untuk menggunakan API ini.

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

Contoh

Anda dapat menemukan contoh sederhana penggunaan chrome.downloads API di direktori examples/api/downloads. Untuk contoh lain dan bantuan dalam melihat kode sumber, lihat Contoh.

Jenis

BooleanDelta

Properti

  • current

    boolean opsional

  • sebelumnya

    boolean opsional

DangerType

file

Nama file download mencurigakan.

url

URL download diketahui berbahaya.

konten

File yang didownload diketahui berbahaya.

tidak umum

URL download tidak biasa didownload dan berpotensi membahayakan.

host

Download berasal dari host yang diketahui mendistribusikan biner berbahaya dan kemungkinan berbahaya.

tidak diinginkan

File yang didownload mungkin tidak diinginkan atau tidak aman. Misalnya, software ini dapat membuat perubahan pada setelan browser atau komputer.

aman

Download tidak menimbulkan bahaya yang diketahui pada komputer pengguna.

diterima

Pengguna telah menyetujui download berbahaya.

Enum

"file"

"url"

"content"

"tidak umum"

"host"

"tidak diinginkan"

"aman"

"accepted"

"allowlistedByPolicy"

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

DoubleDelta

Properti

  • current

    nomor opsional

  • sebelumnya

    nomor opsional

DownloadDelta

Properti

  • canResume

    BooleanDelta opsional

    Perubahan pada canResume, jika ada.

  • bahaya

    StringDelta opsional

    Perubahan pada danger, jika ada.

  • endTime

    StringDelta opsional

    Perubahan pada endTime, jika ada.

  • error

    StringDelta opsional

    Perubahan pada error, jika ada.

  • ada

    BooleanDelta opsional

    Perubahan pada exists, jika ada.

  • fileSize

    DoubleDelta opsional

    Perubahan pada fileSize, jika ada.

  • filename

    StringDelta opsional

    Perubahan pada filename, jika ada.

  • finalUrl

    StringDelta opsional

    Chrome 54+

    Perubahan pada finalUrl, jika ada.

  • id

    angka

    id dari DownloadItem yang berubah.

  • pantomim

    StringDelta opsional

    Perubahan pada mime, jika ada.

  • dijeda

    BooleanDelta opsional

    Perubahan pada paused, jika ada.

  • startTime

    StringDelta opsional

    Perubahan pada startTime, jika ada.

  • dengan status tersembunyi akhir

    StringDelta opsional

    Perubahan pada state, jika ada.

  • totalBytes

    DoubleDelta opsional

    Perubahan pada totalBytes, jika ada.

  • url

    StringDelta opsional

    Perubahan pada url, jika ada.

DownloadItem

Properti

  • byExtensionId

    string opsional

    ID untuk ekstensi yang memulai download ini jika download ini dimulai oleh ekstensi. Tidak berubah setelah ditetapkan.

  • byExtensionName

    string opsional

    Nama ekstensi yang dilokalkan yang memulai download ini jika download ini dimulai oleh ekstensi. Dapat berubah jika ekstensi mengubah namanya atau jika pengguna mengubah lokalitasnya.

  • bytesReceived

    angka

    Jumlah byte yang diterima sejauh ini dari host, tanpa mempertimbangkan kompresi file.

  • canResume

    boolean

    Benar jika download sedang berlangsung dan dijeda, atau jika download terhenti dan dapat dilanjutkan mulai dari tempat download terhenti.

  • bahaya

    DangerType

    Indikasi apakah download ini dianggap aman atau diketahui mencurigakan.

  • endTime

    string opsional

    Waktu saat download berakhir dalam format ISO 8601. Dapat diteruskan langsung ke konstruktor Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

  • error

    InterruptReason opsional

    Alasan download terganggu. Beberapa jenis error HTTP dapat dikelompokkan dalam salah satu error yang diawali dengan SERVER_. Error terkait jaringan dimulai dengan NETWORK_, error terkait proses penulisan file ke sistem file dimulai dengan FILE_, dan gangguan yang dimulai oleh pengguna dimulai dengan USER_.

  • estimatedEndTime

    string opsional

    Perkiraan waktu saat download akan selesai dalam format ISO 8601. Dapat diteruskan langsung ke konstruktor Date: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

  • ada

    boolean

    Apakah file yang didownload masih ada. Informasi ini mungkin sudah tidak berlaku karena Chrome tidak otomatis memantau penghapusan file. Panggil search() untuk memicu pemeriksaan keberadaan file. Saat pemeriksaan keberadaan selesai, jika file telah dihapus, peristiwa onChanged akan dipicu. Perhatikan bahwa search() tidak menunggu hingga pemeriksaan keberadaan selesai sebelum ditampilkan, sehingga hasil dari search() mungkin tidak mencerminkan sistem file secara akurat. Selain itu, search() dapat dipanggil sesering yang diperlukan, tetapi tidak akan memeriksa keberadaan file lebih sering daripada sekali setiap 10 detik.

  • fileSize

    angka

    Jumlah byte dalam seluruh file setelah dekompresi, atau -1 jika tidak diketahui.

  • filename

    string

    Jalur lokal absolut.

  • finalUrl

    string

    Chrome 54+

    URL absolut tempat download ini dilakukan, setelah semua pengalihan.

  • id

    angka

    ID yang persisten di seluruh sesi browser.

  • samaran

    boolean

    False jika download ini dicatat dalam histori, true jika tidak dicatat.

  • pantomim

    string

    Jenis MIME file.

  • dijeda

    boolean

    Benar (True) jika download telah berhenti membaca data dari host, tetapi koneksi tetap terbuka.

  • perujuk

    string

    URL absolut.

  • startTime

    string

    Waktu saat download dimulai dalam format ISO 8601. Dapat diteruskan langsung ke konstruktor Date: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • dengan status tersembunyi akhir

    Status

    Menunjukkan apakah download sedang berlangsung, terganggu, atau selesai.

  • totalBytes

    angka

    Jumlah byte dalam seluruh file, tanpa mempertimbangkan kompresi file, atau -1 jika tidak diketahui.

  • url

    string

    URL absolut yang memulai download ini, sebelum pengalihan apa pun.

DownloadOptions

Properti

  • body

    string opsional

    Isi postingan.

  • conflictAction

    FilenameConflictAction opsional

    Tindakan yang akan diambil jika filename sudah ada.

  • filename

    string opsional

    Jalur file relatif ke direktori Download untuk berisi file yang didownload, yang mungkin berisi subdirektori. Jalur absolut, jalur kosong, dan jalur yang berisi referensi kembali ".." akan menyebabkan error. onDeterminingFilename memungkinkan menyarankan nama file setelah jenis MIME file dan nama file sementara ditentukan.

  • headers

    HeaderNameValuePair[] opsional

    Header HTTP tambahan yang akan dikirim dengan permintaan jika URL menggunakan protokol HTTP[s]. Setiap header direpresentasikan sebagai kamus yang berisi kunci name dan value atau binaryValue, yang dibatasi untuk yang diizinkan oleh XMLHttpRequest.

  • method

    HttpMethod opsional

    Metode HTTP yang akan digunakan jika URL menggunakan protokol HTTP[S].

  • saveAs

    boolean opsional

    Gunakan pemilih file untuk mengizinkan pengguna memilih nama file, terlepas dari apakah filename disetel atau sudah ada.

  • url

    string

    URL yang akan didownload.

DownloadQuery

Properti

  • bytesReceived

    nomor opsional

    Jumlah byte yang diterima sejauh ini dari host, tanpa mempertimbangkan kompresi file.

  • bahaya

    DangerType opsional

    Indikasi apakah download ini dianggap aman atau diketahui mencurigakan.

  • endTime

    string opsional

    Waktu saat download berakhir dalam format ISO 8601.

  • endedAfter

    string opsional

    Membatasi hasil ke DownloadItem yang berakhir setelah ms tertentu dalam format ISO 8601

  • endedBefore

    string opsional

    Membatasi hasil ke DownloadItem yang berakhir sebelum ms tertentu dalam format ISO 8601.

  • error

    InterruptReason opsional

    Alasan download terganggu.

  • ada

    boolean opsional

    Apakah file yang didownload ada;

  • fileSize

    nomor opsional

    Jumlah byte dalam seluruh file setelah dekompresi, atau -1 jika tidak diketahui.

  • filename

    string opsional

    Jalur lokal absolut.

  • filenameRegex

    string opsional

    Membatasi hasil ke DownloadItem yang filename-nya cocok dengan ekspresi reguler yang diberikan.

  • finalUrl

    string opsional

    Chrome 54+

    URL absolut tempat download ini dilakukan, setelah semua pengalihan.

  • finalUrlRegex

    string opsional

    Chrome 54+

    Membatasi hasil ke DownloadItem yang finalUrl-nya cocok dengan ekspresi reguler yang diberikan.

  • id

    nomor opsional

    id DownloadItem yang akan dikueri.

  • batas

    nomor opsional

    Jumlah maksimum DownloadItem yang cocok yang ditampilkan. Default-nya adalah 1.000. Setel ke 0 untuk menampilkan semua DownloadItem yang cocok. Lihat search untuk mengetahui cara melihat hasil per halaman.

  • pantomim

    string opsional

    Jenis MIME file.

  • orderBy

    string[] opsional

    Tetapkan elemen array ini ke properti DownloadItem untuk mengurutkan hasil penelusuran. Misalnya, menyetel orderBy=['startTime'] akan mengurutkan DownloadItem berdasarkan waktu mulai dalam urutan menaik. Untuk menentukan urutan menurun, beri awalan dengan tanda hubung: '-startTime'.

  • dijeda

    boolean opsional

    Benar (True) jika download telah berhenti membaca data dari host, tetapi koneksi tetap terbuka.

  • kueri

    string[] opsional

    Array istilah penelusuran ini membatasi hasil ke DownloadItem yang filename atau url atau finalUrl-nya berisi semua istilah penelusuran yang tidak diawali dengan tanda hubung '-' dan tidak ada istilah penelusuran yang diawali dengan tanda hubung.

  • startTime

    string opsional

    Waktu saat download dimulai dalam format ISO 8601.

  • startedAfter

    string opsional

    Membatasi hasil ke DownloadItem yang dimulai setelah ms tertentu dalam format ISO 8601.

  • startedBefore

    string opsional

    Membatasi hasil ke DownloadItem yang dimulai sebelum ms tertentu dalam format ISO 8601.

  • dengan status tersembunyi akhir

    Negara bagian opsional

    Menunjukkan apakah download sedang berlangsung, terganggu, atau selesai.

  • totalBytes

    nomor opsional

    Jumlah byte dalam seluruh file, tanpa mempertimbangkan kompresi file, atau -1 jika tidak diketahui.

  • totalBytesGreater

    nomor opsional

    Membatasi hasil ke DownloadItem yang totalBytes-nya lebih besar dari bilangan bulat yang diberikan.

  • totalBytesLess

    nomor opsional

    Membatasi hasil ke DownloadItem yang totalBytes-nya kurang dari bilangan bulat yang diberikan.

  • url

    string opsional

    URL absolut yang memulai download ini, sebelum pengalihan apa pun.

  • urlRegex

    string opsional

    Membatasi hasil ke DownloadItem yang url-nya cocok dengan ekspresi reguler yang diberikan.

FilenameConflictAction

membuat unik

Untuk menghindari duplikasi, filename diubah untuk menyertakan penghitung sebelum ekstensi nama file.

timpa

File yang ada akan ditimpa dengan file baru.

perintah

Pengguna akan diminta dengan dialog pemilih file.

Enum

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

Properti

  • conflictAction

    FilenameConflictAction opsional

    Tindakan yang akan diambil jika filename sudah ada.

  • filename

    string

    Target baru DownloadItem.filename DownloadItem, sebagai jalur relatif terhadap direktori Download default pengguna, yang mungkin berisi subdirektori. Jalur absolut, jalur kosong, dan jalur yang berisi referensi kembali ".." akan diabaikan. filename diabaikan jika ada pemroses onDeterminingFilename yang didaftarkan oleh ekstensi mana pun.

GetFileIconOptions

Properti

  • ukuran

    nomor opsional

    Ukuran ikon yang ditampilkan. Ikon akan berbentuk persegi dengan dimensi ukuran * ukuran piksel. Ukuran default dan terbesar untuk ikon adalah 32x32 piksel. Satu-satunya ukuran yang didukung adalah 16 dan 32. Menentukan ukuran lain adalah error.

HeaderNameValuePair

Properti

  • nama

    string

    Nama header HTTP.

  • nilai

    string

    Nilai header 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

Download saat ini menerima data dari server.

terganggu

Terjadi error yang mengganggu koneksi dengan host file.

selesai

Download berhasil diselesaikan.

Enum

"in_progress"

"terganggu"

"selesai"

StringDelta

Properti

  • current

    string opsional

  • sebelumnya

    string opsional

UiOptions

Chrome 105+

Properti

  • diaktifkan

    boolean

    Aktifkan atau nonaktifkan UI download.

Metode

acceptDanger()

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

Minta pengguna untuk menerima download berbahaya. Hanya dapat dipanggil dari konteks yang terlihat (tab, jendela, atau pop-up tindakan browser/halaman). Tidak otomatis menyetujui download berbahaya. Jika download diterima, peristiwa onChanged akan diaktifkan, jika tidak, tidak akan terjadi apa-apa. Setelah semua data diambil ke dalam file sementara dan download tidak berbahaya atau bahaya telah diterima, file sementara akan diganti namanya menjadi nama file target, state berubah menjadi 'complete', dan onChanged diaktifkan.

Parameter

Hasil

  • Promise<void>

    Chrome 96+

cancel()

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

Membatalkan download. Saat callback dijalankan, download dibatalkan, selesai, terganggu, atau tidak ada lagi.

Parameter

  • downloadId

    angka

    ID download yang akan dibatalkan.

Hasil

  • Promise<void>

    Chrome 96+

download()

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

Mendownload URL. Jika URL menggunakan protokol HTTP[S], permintaan akan menyertakan semua cookie yang saat ini ditetapkan untuk nama host-nya. Jika filename dan saveAs ditentukan, dialog Simpan Sebagai akan ditampilkan, yang sudah diisi sebelumnya dengan filename yang ditentukan. Jika download berhasil dimulai, callback akan dipanggil dengan downloadId DownloadItem baru. Jika terjadi error saat memulai download, callback akan dipanggil dengan downloadId=undefined dan runtime.lastError akan berisi string deskriptif. String error tidak dijamin tetap kompatibel dengan versi sebelumnya di antara rilis. Ekstensi tidak boleh memparsingnya.

Parameter

Hasil

  • Promise<number>

    Chrome 96+

erase()

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

Menghapus DownloadItem yang cocok dari histori tanpa menghapus file yang didownload. Peristiwa onErased akan diaktifkan untuk setiap DownloadItem yang cocok dengan query, lalu callback akan dipanggil.

Parameter

Hasil

  • Promise<number[]>

    Chrome 96+

getFileIcon()

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

Mengambil ikon untuk download yang ditentukan. Untuk download baru, ikon file tersedia setelah peristiwa onCreated diterima. Gambar yang ditampilkan oleh fungsi ini saat download sedang berlangsung mungkin berbeda dengan gambar yang ditampilkan setelah download selesai. Pengambilan ikon dilakukan dengan membuat kueri sistem operasi atau toolkit yang mendasarinya, bergantung pada platform. Oleh karena itu, ikon yang ditampilkan akan bergantung pada sejumlah faktor, termasuk status download, platform, jenis file terdaftar, dan tema visual. Jika ikon file tidak dapat ditentukan, runtime.lastError akan berisi pesan error.

Parameter

Hasil

  • Promise<string | undefined>

    Chrome 96+

open()

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

Membuka file yang didownload sekarang jika DownloadItem selesai; jika tidak, menampilkan error melalui runtime.lastError. Metode ini memerlukan izin "downloads.open" selain izin "downloads". Peristiwa onChanged diaktifkan saat item dibuka untuk pertama kalinya. Metode ini hanya dapat dipanggil sebagai respons terhadap gestur pengguna.

Parameter

  • downloadId

    angka

    ID untuk file yang didownload.

Hasil

  • Promise<void>

    Chrome 123+

pause()

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

Jeda download. Jika permintaan berhasil, download akan berada dalam status dijeda. Jika tidak, runtime.lastError akan berisi pesan error. Permintaan akan gagal jika download tidak aktif.

Parameter

  • downloadId

    angka

    ID download yang akan dijeda.

Hasil

  • Promise<void>

    Chrome 96+

removeFile()

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

Hapus file yang didownload jika ada dan DownloadItem selesai; jika tidak, tampilkan error melalui runtime.lastError.

Parameter

  • downloadId

    angka

Hasil

  • Promise<void>

    Chrome 96+

resume()

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

Melanjutkan download yang dijeda. Jika permintaan berhasil, download sedang berlangsung dan tidak dijeda. Jika tidak, runtime.lastError akan berisi pesan error. Permintaan akan gagal jika download tidak aktif.

Parameter

  • downloadId

    angka

    ID download yang akan dilanjutkan.

Hasil

  • Promise<void>

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

Temukan DownloadItem. Tetapkan query ke objek kosong untuk mendapatkan semua DownloadItem. Untuk mendapatkan DownloadItem tertentu, tetapkan hanya kolom id. Untuk melihat-lihat sejumlah besar item, tetapkan orderBy: ['-startTime'], tetapkan limit ke jumlah item per halaman, dan tetapkan startedAfter ke startTime item terakhir dari halaman terakhir.

Parameter

Hasil

setShelfEnabled()

Tidak digunakan lagi sejak Chrome 117
chrome.downloads.setShelfEnabled(
  enabled: boolean,
): void

Sebagai gantinya, gunakan setUiOptions.

Aktifkan atau nonaktifkan panel abu-abu di bagian bawah setiap jendela yang terkait dengan profil browser saat ini. Galeri akan dinonaktifkan selama setidaknya satu ekstensi telah menonaktifkannya. Mengaktifkan panel saat setidaknya satu ekstensi lain telah menonaktifkannya akan menampilkan error melalui runtime.lastError. Memerlukan izin "downloads.shelf" selain izin "downloads".

Parameter

  • diaktifkan

    boolean

setUiOptions()

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

Mengubah UI download setiap jendela yang terkait dengan profil browser saat ini. Selama setidaknya satu ekstensi telah menyetel UiOptions.enabled ke salah (false), UI download akan disembunyikan. Menetapkan UiOptions.enabled ke benar (true) saat setidaknya satu ekstensi lain menonaktifkannya akan menampilkan error melalui runtime.lastError. Memerlukan izin "downloads.ui" selain izin "downloads".

Parameter

  • opsi

    UiOptions

    Mengenkapsulasi perubahan pada UI download.

Hasil

  • Promise<void>

show()

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

Tampilkan file yang didownload di foldernya di file manager.

Parameter

  • downloadId

    angka

    ID untuk file yang didownload.

showDefaultFolder()

chrome.downloads.showDefaultFolder(): void

Tampilkan folder Download default di pengelola file.

Acara

onChanged

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

Saat properti DownloadItem berubah, kecuali bytesReceived dan estimatedEndTime, peristiwa ini akan diaktifkan dengan downloadId dan objek yang berisi properti yang berubah.

Parameter

onCreated

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

Peristiwa ini dipicu dengan objek DownloadItem saat download dimulai.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (downloadItem: DownloadItem) => void

onDeterminingFilename

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

Selama proses penentuan nama file, ekstensi akan diberi kesempatan untuk mengganti DownloadItem.filename target. Setiap ekstensi hanya dapat mendaftarkan satu pemroses untuk peristiwa ini. Setiap pemroses harus memanggil suggest tepat satu kali, baik secara sinkron maupun asinkron. Jika pemroses memanggil suggest secara asinkron, pemroses harus menampilkan true. Jika pemroses tidak memanggil suggest secara serentak maupun menampilkan true, maka suggest akan dipanggil secara otomatis. DownloadItem tidak akan selesai hingga semua pemroses memanggil suggest. Listener dapat memanggil suggest tanpa argumen apa pun agar download dapat menggunakan downloadItem.filename untuk nama filenya, atau meneruskan objek suggestion ke suggest untuk mengganti nama file target. Jika lebih dari satu ekstensi menggantikan nama file, ekstensi terakhir yang diinstal yang pemroses peristiwanya meneruskan objek suggestion ke suggest akan menang. Untuk menghindari kebingungan mengenai ekstensi mana yang akan menang, pengguna tidak boleh menginstal ekstensi yang dapat menimbulkan konflik. Jika download dimulai oleh download dan nama file target diketahui sebelum jenis MIME dan nama file sementara ditentukan, teruskan filename ke download.

Parameter

onErased

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

Diaktifkan dengan downloadId saat download dihapus dari histori.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (downloadId: number) => void

    • downloadId

      angka