chrome.downloads

refresh date: 2026-09-25 robots: noindex

این اجازه هشداری را فعال می‌کند

شرح

از chrome.downloads API برای شروع، نظارت، دستکاری و جستجوی بارگیری‌ها به‌صورت برنامه‌ریزی‌شده استفاده کنید.

اجازه‌ها

downloads

مانیفست

برای استفاده از این میانای برنامه‌سازی کاربردی، باید اجازه "downloads" را در مانیفست افزونه اعلام کنید.

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

مثال‌ها

می‌توانید نمونه‌های ساده‌ای از استفاده از chrome.downloads API را در فهرست examples/api/downloads پیدا کنید. برای مثال‌های دیگر و راهنمایی در مشاهده کد منبع، نمونه‌ها را ببینید.

انواع

BooleanDelta

مشخصات

  • کنونی

    مقدار منطقی اختیاری

  • قبلی

    مقدار منطقی اختیاری

DangerType

شمارشی

«فایل»
نام فایل بارگیری مشکوک است.

«url»
نشانی وب بارگیری به‌عنوان مخرب شناخته شده است.

«محتوا»
فایل بارگیری‌شده به‌عنوان فایل مخرب شناخته شده است.

«غیرمعمول»
نشانی وب بارگیری معمولاً بارگیری نمی‌شود و می‌تواند خطرناک باشد.

«میزبان»
بارگیری از میزبانی انجام شده است که به‌دلیل توزیع دودویی‌های مخرب شناخته شده است و احتمالاً خطرناک است.

«unwanted»
بارگیری احتمالاً ناخواسته یا ناامن است. مثلاً می‌تواند تنظیمات مرورگر یا رایانه را تغییر دهد.

«safe»
بارگیری هیچ خطر شناخته‌شده‌ای برای رایانه کاربر ندارد.

«پذیرفته‌شده»
کاربر بارگیری خطرناک را پذیرفته است.

«allowlistedByPolicy»
مقادیر مربوط به Enterprise.

"asyncScanning"

"asyncLocalPasswordScanning"

«passwordProtected»

"blockedTooLarge"

"sensitiveContentWarning"

«sensitiveContentBlock»

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

«accountCompromise»

«blockedScanFailed»

«forceSaveToGdrive»
برای استفاده توسط افزونه «مرورگر سازمانی ایمن». درصورت نیاز، Chrome بارگیری در دیسک را مسدود می‌کند و فایل را مستقیماً در Google Drive بارگیری می‌کند.

«forceSaveToOnedrive»
برای استفاده توسط افزونه «مرورگر سازمانی امن». درصورت نیاز، Chrome بارگیری در دیسک را مسدود می‌کند و فایل را مستقیماً در OneDrive بارگیری می‌کند.

DoubleDelta

مشخصات

  • کنونی

    شماره اختیاری

  • قبلی

    شماره اختیاری

DownloadDelta

مشخصات

  • canResume

    BooleanDelta اختیاری

    تغییر در canResume، درصورت وجود.

  • خطر

    StringDelta اختیاری

    تغییر در danger، درصورت وجود.

  • endTime

    StringDelta اختیاری

    تغییر در endTime، درصورت وجود.

  • خطا

    StringDelta اختیاری

    تغییر در error، درصورت وجود.

  • وجود دارد

    BooleanDelta اختیاری

    تغییر در exists، درصورت وجود.

  • fileSize

    DoubleDelta اختیاری

    تغییر در fileSize، درصورت وجود.

  • filename

    StringDelta اختیاری

    تغییر در filename، درصورت وجود.

  • finalUrl

    StringDelta اختیاری

    Chrome 54 و نسخه‌های بالاتر

    تغییر در finalUrl، درصورت وجود.

  • id

    شماره

    id مربوط به DownloadItem که تغییر کرده است.

  • تقلید

    StringDelta اختیاری

    تغییر در mime، درصورت وجود.

  • موقتاً متوقف‌شده

    BooleanDelta اختیاری

    تغییر در paused، درصورت وجود.

  • startTime

    StringDelta اختیاری

    تغییر در startTime، درصورت وجود.

  • ایالت

    StringDelta اختیاری

    تغییر در state، درصورت وجود.

  • totalBytes

    DoubleDelta اختیاری

    تغییر در totalBytes، درصورت وجود.

  • نشانی وب

    StringDelta اختیاری

    تغییر در url، درصورت وجود.

DownloadItem

مشخصات

  • byExtensionId

    رشته اختیاری

    شناسه افزونه‌ای که این بارگیری را آغاز کرده است، اگر این بارگیری توسط افزونه‌ای آغاز شده باشد. پس‌از تنظیم شدن تغییر نمی‌کند.

  • byExtensionName

    رشته اختیاری

    نام بومی‌سازی‌شده افزونه‌ای که این بارگیری را آغاز کرده است، اگر این بارگیری توسط افزونه‌ای آغاز شده باشد. اگر افزونه نامش را تغییر دهد یا اگر کاربر زبانش را تغییر دهد، ممکن است تغییر کند.

  • bytesReceived

    شماره

    تعداد بایت‌های دریافتی تاکنون از میزبان، بدون درنظر گرفتن فشرده‌سازی فایل.

  • canResume

    بولی

    اگر بارگیری درحال انجام و متوقف شده باشد، یا اگر قطع شده باشد و بتوان آن را از جایی که قطع شده ازسر گرفت، درست است.

  • خطر

    DangerType

    نشان می‌دهد که آیا این بارگیری امن است یا مشکوک شناخته شده است.

  • 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() ممکن است هر چند وقت یک‌بار که لازم باشد فراخوانده شود، اما وجود فایل را بیشتر از یک‌بار در هر ۱۰ ثانیه بررسی نخواهد کرد.

  • fileSize

    شماره

    تعداد بایت‌ها در کل فایل پس‌از فشرده‌سازی، یا -۱ اگر ناشناس باشد.

  • filename

    رشته

    مسیر محلی مطلق.

  • finalUrl

    رشته

    Chrome نسخه ۵۴ به بالا

    نشانی وب مطلق که این بارگیری از آن انجام می‌شود، پس‌از همه بازهدایت‌ها.

  • id

    شماره

    شناسه‌ای که در جلسه‌های مرورگر پایدار است.

  • ناشناس

    بولی

    اگر این بارگیری در سابقه ثبت شده باشد، «نادرست» است و اگر ثبت نشده باشد، «درست» است.

  • تقلید

    رشته

    نوع MIME فایل.

  • موقتاً متوقف‌شده

    بولی

    اگر بارگیری خواندن داده‌ها از میزبان را متوقف کرده باشد، اما اتصال را باز نگه داشته باشد، True است.

  • ارجاع‌دهنده

    رشته

    نشانی وب مطلق.

  • startTime

    رشته

    زمان شروع بارگیری در قالب ISO 8601. ممکن است مستقیماً به سازنده Date منتقل شود: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • ایالت

    ایالت

    نشان می‌دهد که بارگیری درحال پیشرفت است، متوقف شده است، یا تکمیل شده است.

  • totalBytes

    شماره

    تعداد بایت‌ها در کل فایل، بدون درنظر گرفتن فشرده‌سازی فایل، یا ۱- اگر ناشناخته باشد.

  • نشانی وب

    رشته

    نشانی وب مطلق که این بارگیری از آن شروع شده است، قبل‌از هرگونه هدایت مجدد.

DownloadOptions

مشخصات

  • بدن

    رشته اختیاری

    متن اصلی پست.

  • conflictAction

    FilenameConflictAction اختیاری

    اقدامی که باید انجام شود اگر filename ازقبل وجود داشته باشد.

  • filename

    رشته اختیاری

    مسیر فایل نسبت به فهرست راهنمای «بارگیری‌ها» برای نگهداری فایل بارگیری‌شده، احتمالاً حاوی زیرفهرست‌های راهنما. مسیرهای مطلق، مسیرهای خالی، و مسیرهای حاوی ارجاع‌های برگشتی «..» باعث ایجاد خطا می‌شوند. onDeterminingFilename امکان پیشنهاد نام فایل را پس‌از تعیین نوع MIME فایل و نام فایل آزمایشی فراهم می‌کند.

  • سرایندها

    HeaderNameValuePair[] اختیاری

    سرصفحه‌های HTTP اضافی برای ارسال با درخواست، اگر نشانی وب از پروتکل HTTP[s] استفاده می‌کند. هر سرایند به‌صورت فرهنگ لغت حاوی کلیدهای name و value یا binaryValue نشان داده می‌شود که به موارد مجاز توسط XMLHttpRequest محدود می‌شود.

  • روش

    HttpMethod اختیاری

    روش HTTP برای استفاده درصورتی‌که نشانی وب از پروتکل HTTP[S] استفاده کند.

  • saveAs

    بولی اختیاری

    از انتخابگر فایل استفاده کنید تا به کاربر اجازه دهید نام فایلی را انتخاب کند، صرف‌نظر از اینکه filename تنظیم شده است یا ازقبل وجود دارد.

  • نشانی وب

    رشته

    نشانی وب برای بارگیری.

DownloadQuery

مشخصات

  • bytesReceived

    شماره اختیاری

    تعداد بایت‌های دریافتی از میزبان تا این لحظه، بدون درنظر گرفتن فشرده‌سازی فایل.

  • خطر

    DangerType اختیاری

    نشان می‌دهد که آیا این بارگیری امن است یا مشکوک شناخته شده است.

  • endTime

    رشته اختیاری

    زمان پایان بارگیری در قالب ISO 8601.

  • endedAfter

    رشته اختیاری

    نتایج را به DownloadItem که پس‌از میلی‌ثانیه داده‌شده در قالب ISO 8601 پایان یافته است محدود می‌کند

  • endedBefore

    رشته اختیاری

    نتایج را به DownloadItem که قبل‌از میلی‌ثانیه داده‌شده در قالب ISO 8601 پایان یافته است محدود می‌کند.

  • خطا

    InterruptReason اختیاری

    چرا بارگیری قطع شد.

  • وجود دارد

    بولی اختیاری

    فایل بارگیری‌شده وجود دارد یا نه؛

  • fileSize

    عدد اختیاری

    تعداد بایت‌ها در کل فایل پس‌از خارج کردن از حالت فشرده، یا ۱- اگر ناشناخته باشد.

  • filename

    رشته اختیاری

    مسیر محلی مطلق.

  • filenameRegex

    رشته اختیاری

    نتایج را به DownloadItem محدود می‌کند که filename آن‌ها با عبارت باقاعده داده‌شده مطابقت دارد.

  • finalUrl

    رشته اختیاری

    Chrome 54 و نسخه‌های بالاتر

    نشانی وب مطلق که این بارگیری از آن انجام می‌شود، پس‌از همه تغییر مسیرها.

  • finalUrlRegex

    رشته اختیاری

    Chrome 54 و نسخه‌های بالاتر

    نتایج را به DownloadItem محدود می‌کند که finalUrl آن‌ها با عبارت باقاعده داده‌شده مطابقت دارد.

  • id

    عدد اختیاری

    id DownloadItem برای پُرسمان.

  • حد

    شماره اختیاری

    حداکثر تعداد DownloadItem منطبق برگردانده شد. پیش‌فرض ۱۰۰۰ است. برای برگرداندن همه DownloadItem منطبق، روی ۰ تنظیم کنید. برای آشنایی با نحوه ورق زدن نتایج، search را ببینید.

  • تقلید

    رشته اختیاری

    نوع MIME فایل.

  • orderBy

    رشته[] اختیاری

    عناصر این آرایه را روی ویژگی‌های DownloadItem تنظیم کنید تا نتایج جستجو را مرتب کنید. برای مثال، تنظیم orderBy=['startTime'] باعث می‌شود DownloadItem براساس زمان شروعشان به‌ترتیب صعودی مرتب شوند. برای مشخص کردن ترتیب نزولی، پیشوند را با خط تیره اضافه کنید: «-startTime».

  • موقتاً متوقف‌شده

    مقدار منطقی اختیاری

    اگر بارگیری خواندن داده‌ها از میزبان را متوقف کرده باشد، اما اتصال را باز نگه داشته باشد، True است.

  • پُرسمان

    رشته[] اختیاری

    این آرایه از عبارت‌های جستجو نتایج را به DownloadItem محدود می‌کند که filename یا url یا finalUrl آن حاوی همه عبارت‌های جستجویی است که با خط تیره «-» شروع نمی‌شوند و هیچ‌کدام از عبارت‌های جستجویی که با خط تیره شروع می‌شوند را ندارد.

  • startTime

    رشته اختیاری

    زمان شروع بارگیری در قالب ISO 8601.

  • startedAfter

    رشته اختیاری

    نتایج را به DownloadItem که پس‌از میلی‌ثانیه داده‌شده در قالب ISO 8601 شروع شده است محدود می‌کند.

  • startedBefore

    رشته اختیاری

    نتایج را به DownloadItem محدود می‌کند که قبل‌از میلی‌ثانیه داده‌شده در قالب ISO 8601 شروع شده است.

  • ایالت

    استان اختیاری

    نشان می‌دهد که بارگیری درحال پیشرفت است، متوقف شده است، یا تکمیل شده است.

  • totalBytes

    عدد اختیاری

    تعداد بایت‌های کل فایل، بدون درنظر گرفتن فشرده‌سازی فایل، یا -۱ اگر ناشناس باشد.

  • totalBytesGreater

    شماره اختیاری

    نتایج را به DownloadItem محدود می‌کند که totalBytes آن بزرگ‌تر از عدد صحیح داده‌شده است.

  • totalBytesLess

    عدد اختیاری

    نتایج را به DownloadItem محدود می‌کند که totalBytes آن‌ها کمتر از عدد صحیح داده‌شده است.

  • نشانی وب

    رشته اختیاری

    نشانی وب مطلق که این بارگیری از آن شروع شده است، قبل‌از هرگونه تغییر مسیر.

  • urlRegex

    رشته اختیاری

    نتایج را به DownloadItem که url آن با عبارت باقاعده داده‌شده مطابقت دارد محدود می‌کند.

FilenameConflictAction

منحصربه‌فرد کردن

برای جلوگیری از تکرار، filename تغییر می‌کند تا شمارنده‌ای قبل‌از پسوند نام فایل اضافه شود.

رونویسی کردن

فایل موجود با فایل جدید جایگزین خواهد شد.

prompt

کادر گفتگوی انتخاب فایل به کاربر نشان داده می‌شود.

شمارشی

«یکتاسازی»

«رونویسی»

«پیام‌واره»

FilenameSuggestion

مشخصات

  • conflictAction

    FilenameConflictAction اختیاری

    کنش موردنظر درصورتی‌که filename ازقبل وجود داشته باشد.

  • filename

    رشته

    DownloadItem.filename هدف جدید DownloadItem، به‌عنوان مسیری مرتبط با فهرست راهنمای «بارگیری‌های» پیش‌فرض کاربر، که احتمالاً حاوی زیرفهرست‌های راهنما است. مسیرهای مطلق، مسیرهای خالی، و مسیرهای حاوی ارجاع‌های برگشتی «..» نادیده گرفته خواهند شد. اگر هرگونه شنونده onDeterminingFilename ثبت‌شده توسط هر افزونه‌ای وجود داشته باشد، filename نادیده گرفته می‌شود.

GetFileIconOptions

مشخصات

  • اندازه

    عدد اختیاری

    اندازه نماد برگردانده‌شده در پیکسل‌های مستقل از تراکم (DIP). باید ۱۶ یا ۳۲ باشد (پیش‌فرض ۳۲ است). در نمایشگرهای با DPI بالا، تصویر برگردانده‌شده با ضریب مقیاس دستگاه مقیاس‌بندی می‌شود (برای مثال، ۶۴×۶۴ پیکسل برای اندازه ۳۲ در نمایشگر 2x). تماس‌های کارگران خدمات پس‌زمینه به‌طور پیش‌فرض در مقیاس ۱ برابر است.

HeaderNameValuePair

مشخصات

  • نام

    رشته

    نام سرایند HTTP.

  • مقدار

    رشته

    مقدار سرایند HTTP.

HttpMethod

شمارشی

«دریافت»

"POST"

InterruptReason

شمارشی

"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

درحال‌حاضر بارگیری درحال دریافت داده از سرور است.

قطع‌شده

خطایی اتصال با میزبان فایل را قطع کرد.

انجام شد

بارگیری باموفقیت تکمیل شد.

شمارشی

«در_جریان»

«interrupted»

«تکمیل»

StringDelta

مشخصات

  • کنونی

    رشته اختیاری

  • قبلی

    رشته اختیاری

UiOptions

Chrome نسخه ۱۰۵ و بالاتر

مشخصات

  • فعال شد

    بولی

    واسط کاربر بارگیری را فعال یا غیرفعال می‌کند.

روش‌ها

acceptDanger()

قول 
chrome.downloads.acceptDanger(
  downloadId: number,
  callback?: function,
): Promise<void>

کاربر را به پذیرفتن بارگیری خطرناک ترغیب کند. فقط از بافت قابل‌مشاهده (برگه، پنجره، یا بالاپر کنش صفحه/مرورگر) می‌توان آن را فراخوانی کرد. بارگیری‌های خطرناک را به‌طور خودکار نمی‌پذیرد. اگر بارگیری پذیرفته شود، رویداد onChanged راه‌اندازی می‌شود، درغیراین‌صورت اتفاقی نمی‌افتد. وقتی همه داده‌ها در فایل موقتی واکشی شد و بارگیری خطرناک نبود یا خطر پذیرفته شد، نام فایل موقت به نام فایل هدف تغییر می‌کند، state به «کامل» تغییر می‌کند، و onChanged فعال می‌شود.

پارامترها

  • downloadId

    شماره

    شناسه DownloadItem.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ و بالاتر

    «وعده‌ای» را برمی‌گرداند که وقتی کادر گفتگوی پیام‌واره خطر بسته می‌شود، برآورده می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

cancel()

قول 
chrome.downloads.cancel(
  downloadId: number,
  callback?: function,
): Promise<void>

لغو بارگیری. وقتی callback اجرا می‌شود، بارگیری لغو، تکمیل، یا قطع می‌شود یا دیگر وجود ندارد.

پارامترها

  • downloadId

    شماره

    شناسه بارگیری برای لغو.

  • بازخوانی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ به بالا

    «وعده‌ای» را برمی‌گرداند که وقتی درخواست لغو تکمیل شد، برآورده می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

download()

قول 
chrome.downloads.download(
  options: DownloadOptions,
  callback?: function,
): Promise<number>

بارگیری نشانی وب. اگر نشانی وب از پروتکل HTTP[S] استفاده کند، درخواست شامل همه کوکی‌هایی خواهد بود که درحال‌حاضر برای نام میزبان آن تنظیم شده است. اگر هم filename و هم saveAs مشخص شده باشد، کادر گفتگوی «ذخیره به‌عنوان» نمایش داده می‌شود و با filename مشخص‌شده ازپیش تکمیل می‌شود. اگر بارگیری باموفقیت شروع شد، callback با downloadId DownloadItem جدید فراخوانده می‌شود. اگر خطایی در شروع بارگیری وجود داشته باشد، callback با downloadId=undefined فراخوانی می‌شود و runtime.lastError حاوی یک رشته توصیفی خواهد بود. تضمینی وجود ندارد که رشته‌های خطا بین نسخه‌های پخش‌شده سازگار با نسخه قدیمی باقی بمانند. افزونه‌ها نباید آن را تجزیه کنند.

پارامترها

  • گزینه‌ها

    DownloadOptions

    چه چیزی را و چگونه بارگیری کنید.

  • بازخوانی

    تابع اختیاری

    پارامتر callback به‌این‌صورت است: 

    (downloadId: number) => void

    • downloadId

      شماره

بازگشتی‌ها

  • Promise<number>

    Chrome نسخه ۹۶ به بالا

    «وعده‌ای» برمی‌گرداند که با شناسه DownloadItem جدید حل‌وفصل می‌شود.

    وعده‌ها فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شوند، پلاتفرم‌های دیگر باید از «بازخوان‌ها» استفاده کنند.

erase()

وعده 
chrome.downloads.erase(
  query: DownloadQuery,
  callback?: function,
): Promise<number[]>

DownloadItem منطبق را بدون حذف فایل بارگیری‌شده از سابقه پاک کنید. یک رویداد onErased برای هر DownloadItem که با query مطابقت داشته باشد اجرا می‌شود، سپس callback فراخوانی می‌شود.

پارامترها

  • پُرسمان

    DownloadQuery

  • بازخوانی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (erasedIds: number[]) => void

    • erasedIds

      عدد[]

بازگشتی‌ها

  • Promise<number[]>

    Chrome نسخه ۹۶ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getFileIcon()

قول 
chrome.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
  callback?: function,
): Promise<string | undefined>

نمادی برای بارگیری مشخص‌شده بازیابی کنید. برای بارگیری‌های جدید، نمادهای فایل پس‌از تعیین نام فایل مقصد بارگیری دردسترس قرار می‌گیرند (برای مثال، وقتی onChanged با تغییر filename راه‌اندازی می‌شود). تلاش برای بازیابی نماد قبل‌از تعیین نام فایل منجر به خطا ازطریق runtime.lastError می‌شود. تصویری که این تابع درحین انجام بارگیری برمی‌گرداند ممکن است با تصویری که پس‌از تکمیل بارگیری برمی‌گرداند متفاوت باشد. بازیابی نماد با پُرسمان کردن سیستم‌عامل زیرین یا ابزارک بسته به پلاتفرم انجام می‌شود. بنابراین نمادی که برگردانده می‌شود به عوامل متعددی ازجمله وضعیت بارگیری، پلاتفرم، انواع فایل ثبت‌شده، و زمینه تصویری بستگی دارد. اگر نماد فایل قابل‌تشخیص نباشد، runtime.lastError حاوی پیام خطا خواهد بود.

پارامترها

  • downloadId

    شماره

    شناسه بارگیری.

  • گزینه‌ها

    GetFileIconOptions اختیاری

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌این‌صورت است: 

    (iconURL?: string) => void

    • iconURL

      رشته اختیاری

بازگشتی‌ها

  • Promise<string | undefined>

    Chrome نسخه ۹۶ و بالاتر

    یک Promise برمی‌گرداند که با نشانی وب تصویری که نشان‌دهنده بارگیری است حل می‌شود.

    وعده‌ها فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شوند، پلاتفرم‌های دیگر باید از «بازخوان‌ها» استفاده کنند.

open()

وعده 
chrome.downloads.open(
  downloadId: number,
  callback?: function,
): Promise<void>

اگر DownloadItem کامل باشد، فایل بارگیری‌شده را اکنون باز می‌کند؛ درغیراین‌صورت، خطایی را ازطریق runtime.lastError برمی‌گرداند. این روش علاوه‌بر اجازه "downloads"، به اجازه "downloads.open" نیز نیاز دارد. وقتی موردی برای اولین‌بار باز می‌شود، رویداد onChanged فعال می‌شود. این روش فقط در پاسخ به اشاره کاربر قابل‌فراخوانی است.

پارامترها

  • downloadId

    شماره

    شناسه فایل بارگیری‌شده.

  • تماس برگشتی

    تابع اختیاری

    Chrome نسخه ۱۲۳ به بالا

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۲۳ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

pause()

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

بارگیری را موقتاً متوقف کنید. اگر درخواست موفقیت‌آمیز باشد، بارگیری در حالت موقتاً متوقف‌شده قرار می‌گیرد. درغیراین‌صورت، runtime.lastError حاوی پیام خطا است. اگر بارگیری فعال نباشد، درخواست ناموفق خواهد بود.

پارامترها

  • downloadId

    شماره

    شناسه بارگیری برای موقتاً متوقف کردن.

  • بازخوانی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ به بالا

    «وعده‌ای» برمی‌گرداند که وقتی درخواست توقف موقت تکمیل شد، برآورده می‌شود.

    وعده‌ها فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شوند، پلاتفرم‌های دیگر باید از «بازخوان‌ها» استفاده کنند.

removeFile()

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

اگر فایل بارگیری‌شده وجود دارد و DownloadItem کامل است، آن را بردارید؛ درغیراین‌صورت، خطایی را ازطریق runtime.lastError برگردانید.

پارامترها

  • downloadId

    شماره

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

resume()

وعده 
chrome.downloads.resume(
  downloadId: number,
  callback?: function,
): Promise<void>

بارگیری موقتاً متوقف‌شده را ازسر بگیرید. اگر درخواست موفقیت‌آمیز بود، بارگیری درحال انجام است و موقتاً متوقف نشده است. درغیراین‌صورت، runtime.lastError حاوی پیام خطا است. اگر بارگیری فعال نباشد، درخواست ناموفق خواهد بود.

پارامترها

  • downloadId

    شماره

    شناسه بارگیری برای ازسرگیری.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۹۶ و بالاتر

    یک Promise برمی‌گرداند که وقتی درخواست ازسرگیری تکمیل شود، حل می‌شود.

    وعده‌ها فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شوند، پلاتفرم‌های دیگر باید از «بازخوان‌ها» استفاده کنند.

قول 
chrome.downloads.search(
  query: DownloadQuery,
  callback?: function,
): Promise<DownloadItem[]>

‫DownloadItem را پیدا کنید. برای دریافت همه DownloadItem، query را روی شیء خالی تنظیم کنید. برای دریافت DownloadItem خاص، فقط فیلد id را تنظیم کنید. برای پیمایش در تعداد زیادی از موارد، orderBy: ['-startTime'] را تنظیم کنید، limit را روی تعداد موارد در هر صفحه تنظیم کنید، و startedAfter را روی startTime آخرین مورد از صفحه آخر تنظیم کنید.

پارامترها

  • پُرسمان

    DownloadQuery

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (results: DownloadItem[]) => void

بازگشتی‌ها

  • Promise<DownloadItem[]>

    Chrome نسخه ۹۶ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

setShelfEnabled()

از Chrome 117 منسوخ شده است
chrome.downloads.setShelfEnabled(
  enabled: boolean,
): void

درعوض از setUiOptions استفاده کنید.

قفسه خاکستری را در پایین هر پنجره مرتبط با نمایه مرورگر فعلی فعال یا غیرفعال کنید. تا زمانی که حداقل یک افزونه قفسه را غیرفعال کرده باشد، قفسه غیرفعال خواهد بود. فعال کردن قفسه درحالی‌که حداقل یک افزونه دیگر آن را غیرفعال کرده است، ازطریق runtime.lastError خطا برمی‌گرداند. علاوه‌بر اجازه "downloads"، به اجازه "downloads.shelf" نیاز دارد.

پارامترها

  • فعال شد

    بولی

setUiOptions()

وعده Chrome نسخه ۱۰۵ و بالاتر 
chrome.downloads.setUiOptions(
  options: UiOptions,
  callback?: function,
): Promise<void>

رابط کاربری بارگیری هر پنجره مرتبط با نمایه مرورگر فعلی را تغییر دهید. تا زمانی که حداقل یک افزونه UiOptions.enabled را روی false تنظیم کرده باشد، واسط کاربر بارگیری پنهان خواهد بود. اگر UiOptions.enabled را روی «درست» تنظیم کنید درحالی‌که حداقل یک افزونه دیگر آن را غیرفعال کرده باشد، خطایی ازطریق runtime.lastError برگردانده خواهد شد. علاوه‌بر اجازه "downloads"، به اجازه "downloads.ui" نیاز دارد.

پارامترها

  • گزینه‌ها

    UiOptions

    Encapsulate a change to the download UI.

  • بازخوانی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    یک Promise برمی‌گرداند که وقتی به‌روزرسانی میانای کاربری تکمیل شود، حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

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

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

      شماره