browser.downloads

الوصف

استخدِم واجهة برمجة التطبيقات chrome.downloads لبدء عمليات التنزيل ومراقبتها ومعالجتها والبحث عنها آليًا.

الأذونات

downloads

يجب الإفصاح عن إذن "downloads" في بيان الإضافة لاستخدام واجهة برمجة التطبيقات هذه.

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

أمثلة

يمكنك العثور على أمثلة بسيطة لاستخدام واجهة برمجة تطبيقات browser.downloads في دليل examples/api/downloads. للاطّلاع على أمثلة أخرى وللحصول على مساعدة في عرض الرمز المصدر، يُرجى الاطّلاع على النماذج.

الأنواع

BooleanDelta

الخصائص

  • ملف الدفع الحالي

    قيمة منطقية اختيارية

  • السابق

    قيمة منطقية اختيارية

DangerType

Enum

"file"
اسم الملف الذي تم تنزيله مريب.

"url"
عنوان URL الخاص بعملية التنزيل معروف بأنّه ضارّ.

"content"
الملف الذي تم تنزيله معروف بأنّه ضار.

"uncommon"
لا يتم تنزيل عنوان URL الخاص بعملية التنزيل عادةً، وقد يكون خطيرًا.

"host"
تم تنزيل الملف من مضيف معروف بتوزيع برامج ثنائية ضارة، ومن المحتمل أن يكون خطيرًا.

"unwanted"
من المحتمل أن تكون عملية التنزيل غير مرغوب فيها أو غير آمنة. على سبيل المثال، قد يُجري تغييرات على إعدادات المتصفّح أو الكمبيوتر.

"safe"
لا يمثّل الملف الذي يتم تنزيله أي خطر معروف على جهاز الكمبيوتر الخاص بالمستخدم.

"accepted"
قبل المستخدم عملية التنزيل الخطيرة.

"allowlistedByPolicy"
القيم ذات الصلة بالمؤسسة

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

‫"forceSaveToGdrive"
تُستخدَم من خلال إضافة "متصفّح المؤسسات الآمن". وعند الحاجة، سيحظر Chrome عملية التنزيل على القرص وينزّل الملف مباشرةً إلى Google Drive.

"forceSaveToOnedrive"
تُستخدم هذه السياسة من قِبل إضافة "متصفّح المؤسسات الآمن". وعند الحاجة، سيحظر Chrome عملية التنزيل على القرص وينزّل الملف مباشرةً إلى OneDrive.

DoubleDelta

الخصائص

  • ملف الدفع الحالي

    number اختيارية

  • السابق

    number اختيارية

DownloadDelta

الخصائص

  • canResume

    BooleanDelta اختياري

    التغيير في canResume، إن وُجد

  • خطر

    ‫StringDelta اختياري

    التغيير في danger، إن وُجد

  • endTime

    ‫StringDelta اختياري

    التغيير في endTime، إن وُجد

  • خطأ

    ‫StringDelta اختياري

    التغيير في error، إن وُجد

  • يوجد

    BooleanDelta اختياري

    التغيير في exists، إن وُجد

  • fileSize

    DoubleDelta اختياري

    التغيير في fileSize، إن وُجد

  • filename

    StringDelta اختياري

    التغيير في filename، إن وُجد

  • finalUrl

    StringDelta اختياري

    الإصدار 54 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    التغيير في finalUrl، إن وُجد

  • id

    الرقم

    تمثّل هذه السمة id DownloadItem الذي تم تغييره.

  • مقلِّد

    StringDelta اختياري

    التغيير في mime، إن وُجد

  • متوقفة مؤقتًا

    BooleanDelta اختياري

    التغيير في paused، إن وُجد

  • startTime

    ‫StringDelta اختياري

    التغيير في startTime، إن وُجد

  • الولاية

    ‫StringDelta اختياري

    التغيير في state، إن وُجد

  • totalBytes

    DoubleDelta اختياري

    التغيير في totalBytes، إن وُجد

  • url

    ‫StringDelta اختياري

    التغيير في url، إن وُجد

DownloadItem

الخصائص

  • byExtensionId

    string اختياري

    معرّف الإضافة التي بدأت عملية التنزيل هذه إذا كانت عملية التنزيل قد بدأت من خلال إضافة. ولا يتغيّر بعد ضبطه.

  • byExtensionName

    string اختياري

    الاسم المترجَم للإضافة التي بدأت عملية التنزيل هذه إذا كانت الإضافة هي التي بدأت عملية التنزيل. قد يتغيّر إذا غيّرت الإضافة اسمها أو إذا غيّر المستخدم لغته.

  • bytesReceived

    الرقم

    عدد وحدات البايت التي تم تلقّيها حتى الآن من المضيف، بدون مراعاة ضغط الملفات

  • canResume

    قيمة منطقية

    تكون القيمة "صحيح" إذا كانت عملية التنزيل قيد التقدم وتم إيقافها مؤقتًا، أو إذا تمت مقاطعتها ويمكن استئنافها من حيث توقفت.

  • خطر

    DangerType

    يشير هذا الحقل إلى ما إذا كان يُعتقد أنّ عملية التنزيل هذه آمنة أو معروفة بأنّها مريبة.

  • endTime

    string اختياري

    تمثّل هذه السمة وقت انتهاء عملية التنزيل بتنسيق ISO 8601. يمكن تمريرها مباشرةً إلى دالة Date constructor: 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

    string اختياري

    تمثّل هذه السمة الوقت المقدَّر لاكتمال عملية التنزيل بتنسيق ISO 8601. يمكن تمريرها مباشرةً إلى دالة Date constructor: 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 ثوانٍ.

  • fileSize

    الرقم

    عدد وحدات البايت في الملف بأكمله بعد إلغاء الضغط، أو ‎-1 إذا كان غير معروف

  • filename

    سلسلة

    المسار المحلي المطلق

  • finalUrl

    سلسلة

    الإصدار 54 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    عنوان URL الكامل الذي يتم إجراء عملية التنزيل منه، بعد كل عمليات إعادة التوجيه.

  • id

    الرقم

    معرّف دائم في جميع جلسات المتصفّح

  • incognito

    قيمة منطقية

    "خطأ" إذا تم تسجيل عملية التنزيل هذه في السجلّ، و"صحيح" إذا لم يتم تسجيلها.

  • مقلِّد

    سلسلة

    نوع MIME للملف

  • متوقفة مؤقتًا

    قيمة منطقية

    تكون القيمة "صحيح" إذا توقفت عملية التنزيل عن قراءة البيانات من المضيف، ولكن تم الإبقاء على الاتصال مفتوحًا.

  • مُحيل

    سلسلة

    عنوان URL كامل

  • startTime

    سلسلة

    تمثّل هذه السمة وقت بدء عملية التنزيل بتنسيق ISO 8601. يمكن تمريرها مباشرةً إلى دالة Date constructor: chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

  • الولاية

    الولاية

    يشير إلى ما إذا كانت عملية التنزيل قيد التقدم أو متوقفة أو مكتملة.

  • totalBytes

    الرقم

    عدد وحدات البايت في الملف بأكمله، بدون مراعاة ضغط الملفات، أو ‎-1 إذا كان غير معروف

  • url

    سلسلة

    عنوان URL الكامل الذي بدأت منه عملية التنزيل هذه، قبل أي عمليات إعادة توجيه.

DownloadOptions

الخصائص

  • body

    string اختياري

    نص المنشور

  • conflictAction

    FilenameConflictAction اختياري

    الإجراء الذي يجب اتّخاذه إذا كان filename متوفّرًا مسبقًا

  • filename

    string اختياري

    مسار ملف مرتبط بدليل "عمليات التنزيل" لاحتواء الملف الذي تم تنزيله، وقد يحتوي على أدلة فرعية. ستؤدي المسارات المطلقة والمسارات الفارغة والمسارات التي تحتوي على مراجع خلفية ".." إلى حدوث خطأ. يسمح onDeterminingFilename باقتراح اسم ملف بعد تحديد نوع MIME للملف واسم ملف مؤقت.

  • العناوين

    HeaderNameValuePair[] اختياري

    عناوين HTTP الإضافية التي يتم إرسالها مع الطلب إذا كان عنوان URL يستخدم بروتوكول HTTP[s] يتم تمثيل كل عنوان كقاموس يحتوي على المفتاحين name وvalue أو binaryValue، ويقتصر على تلك التي يسمح بها XMLHttpRequest.

  • method

    HttpMethod اختيارية

    طريقة HTTP التي يجب استخدامها إذا كان عنوان URL يستخدم بروتوكول HTTP[S]

  • saveAs

    قيمة منطقية اختيارية

    استخدِم أداة اختيار الملفات للسماح للمستخدم باختيار اسم ملف بغض النظر عما إذا تم ضبط filename أو كان موجودًا من قبل.

  • url

    سلسلة

    عنوان URL المطلوب تنزيله

DownloadQuery

الخصائص

  • bytesReceived

    number اختيارية

    عدد وحدات البايت التي تم تلقّيها حتى الآن من المضيف، بدون مراعاة ضغط الملفات

  • خطر

    DangerType اختياري

    يشير هذا الحقل إلى ما إذا كان يُعتقد أنّ عملية التنزيل هذه آمنة أو معروفة بأنّها مريبة.

  • endTime

    string اختياري

    تمثّل هذه السمة وقت انتهاء عملية التنزيل بتنسيق ISO 8601.

  • endedAfter

    string اختياري

    تقتصر النتائج على DownloadItem التي انتهت بعد الميلي ثانية المحدّدة بتنسيق ISO 8601

  • endedBefore

    string اختياري

    تقتصر النتائج على DownloadItem التي انتهت قبل الملّي ثانية المحدّدة بتنسيق ISO 8601.

  • خطأ

    InterruptReason اختياري

    سبب إيقاف عملية التنزيل

  • يوجد

    قيمة منطقية اختيارية

    ما إذا كان الملف الذي تم تنزيله متوفّرًا

  • fileSize

    number اختيارية

    عدد وحدات البايت في الملف بأكمله بعد إلغاء الضغط، أو ‎-1 إذا كان غير معروف

  • filename

    string اختياري

    المسار المحلي المطلق

  • filenameRegex

    string اختياري

    يحدّ من النتائج إلى DownloadItem التي يتطابق filename مع التعبير العادي المحدّد.

  • finalUrl

    string اختياري

    الإصدار 54 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    عنوان URL الكامل الذي يتم إجراء عملية التنزيل منه، بعد كل عمليات إعادة التوجيه.

  • finalUrlRegex

    string اختياري

    الإصدار 54 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    يحدّ من النتائج إلى DownloadItem التي يتطابق finalUrl مع التعبير العادي المحدّد.

  • id

    number اختيارية

    تمثّل هذه السمة id DownloadItem المطلوب الاستعلام عنه.

  • الحدّ الأقصى المسموح به

    number اختيارية

    الحد الأقصى لعدد DownloadItem المطابقة التي يتم عرضها. القيمة التلقائية هي 1000. اضبط القيمة على 0 لعرض جميع DownloadItem المطابقة. يمكنك الاطّلاع على search لمعرفة كيفية تصفُّح النتائج.

  • مقلِّد

    string اختياري

    نوع MIME للملف

  • orderBy

    string[] اختياري

    اضبط عناصر هذه المصفوفة على سمات DownloadItem لترتيب نتائج البحث. على سبيل المثال، يؤدي ضبط orderBy=['startTime'] إلى ترتيب DownloadItem حسب وقت البدء تصاعديًا. لتحديد الترتيب التنازلي، أضِف واصلة قبل الحقل: "-startTime".

  • متوقفة مؤقتًا

    قيمة منطقية اختيارية

    تكون القيمة "صحيح" إذا توقفت عملية التنزيل عن قراءة البيانات من المضيف، ولكن تم الإبقاء على الاتصال مفتوحًا.

  • query

    string[] اختياري

    تحدّ مصفوفة عبارات البحث هذه من النتائج إلى DownloadItem التي تحتوي filename أو url أو finalUrl فيها على جميع عبارات البحث التي لا تبدأ بشرطة "-" ولا تحتوي على أي من عبارات البحث التي تبدأ بشرطة.

  • startTime

    string اختياري

    تمثّل هذه السمة وقت بدء عملية التنزيل بتنسيق ISO 8601.

  • startedAfter

    string اختياري

    يحدّ من النتائج إلى DownloadItem التي بدأت بعد الملّي ثانية المحدّدة بتنسيق ISO 8601.

  • startedBefore

    string اختياري

    يحدّ من النتائج إلى DownloadItem التي بدأت قبل الملّي ثانية المحدّدة بتنسيق ISO 8601.

  • الولاية

    State اختيارية

    يشير إلى ما إذا كانت عملية التنزيل قيد التقدم أو متوقفة أو مكتملة.

  • totalBytes

    number اختيارية

    عدد وحدات البايت في الملف بأكمله، بدون مراعاة ضغط الملفات، أو ‎-1 إذا كان غير معروف

  • totalBytesGreater

    number اختيارية

    يحدّ من النتائج إلى DownloadItem التي تكون قيمة totalBytes لها أكبر من العدد الصحيح المحدّد.

  • totalBytesLess

    number اختيارية

    يحدّ من النتائج إلى DownloadItem التي تكون قيمة totalBytes فيها أقل من العدد الصحيح المحدّد.

  • url

    string اختياري

    عنوان URL الكامل الذي بدأت منه عملية التنزيل هذه، قبل أي عمليات إعادة توجيه.

  • urlRegex

    string اختياري

    يحدّ من النتائج إلى DownloadItem التي يتطابق url مع التعبير العادي المحدّد.

FilenameConflictAction

uniquify

لتجنُّب التكرار، يتم تغيير filename لتضمين عدّاد قبل امتداد اسم الملف.

استبدال

سيتم استبدال الملف الحالي بالملف الجديد.

طلب

سيظهر للمستخدم مربّع حوار لاختيار الملفات.

Enum

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

الخصائص

  • conflictAction

    FilenameConflictAction اختياري

    الإجراء الذي يجب اتّخاذه إذا كان filename متوفّرًا مسبقًا

  • filename

    سلسلة

    الهدف الجديد DownloadItem.filename لـ DownloadItem، كمسار مرتبط بدليل "عمليات التنزيل" التلقائي للمستخدم، والذي قد يحتوي على أدلة فرعية. سيتم تجاهل المسارات المطلقة والمسارات الفارغة والمسارات التي تحتوي على مراجع خلفية "..". يتم تجاهل filename في حال وجود أي أدوات معالجة حدث onDeterminingFilename مسجَّلة من خلال أي إضافات.

GetFileIconOptions

الخصائص

  • الحجم

    number اختيارية

    حجم الرمز المعروض بوحدات بكسل مستقلة الكثافة (DIP) يجب أن تكون القيمة إما 16 أو 32 (القيمة التلقائية هي 32). على شاشات High-DPI، يتم تغيير حجم الصورة المعروضة باستخدام عامل قياس الجهاز (على سبيل المثال، 64×64 بكسل للحجم 32 على شاشة 2x). يتم ضبط المكالمات من مشغّلي الخدمات في الخلفية تلقائيًا على المقياس 1x.

HeaderNameValuePair

الخصائص

  • الاسم

    سلسلة

    اسم عنوان HTTP

  • القيمة

    سلسلة

    قيمة عنوان 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

يتلقّى التنزيل حاليًا بيانات من الخادم.

تمت المقاطعة

حدث خطأ أدى إلى قطع الاتصال بمضيف الملف.

complete

اكتملت عملية التنزيل بنجاح.

Enum

"in_progress"

"interrupted"

"complete"

StringDelta

الخصائص

  • ملف الدفع الحالي

    string اختياري

  • السابق

    string اختياري

UiOptions

الإصدار 105 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الخصائص

  • مفعّلة

    قيمة منطقية

    تفعيل واجهة مستخدم التنزيل أو إيقافها

الطُرق

acceptDanger()

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

يُطلب من المستخدم قبول عملية تنزيل خطيرة. Can only be called from a visible context (tab, window, or page/browser action popup). لا يقبل عمليات التنزيل الخطيرة تلقائيًا. إذا تم قبول عملية التنزيل، سيتم تنشيط حدث onChanged، وإلا لن يحدث شيء. عند جلب جميع البيانات إلى ملف مؤقت وعدم وجود خطر في عملية التنزيل أو قبول الخطر، تتم إعادة تسمية الملف المؤقت إلى اسم الملف المستهدف، وتتغير قيمة state إلى "complete"، ويتم تنشيط onChanged.

المعلمات

المرتجعات

  • وعد<فراغ>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم تنفيذه عند إغلاق مربّع حوار التحذير من الخطر.

cancel()

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

إلغاء عملية تنزيل عند تشغيل callback، يتم إلغاء عملية التنزيل أو إكمالها أو مقاطعتها أو لم تعد متوفّرة.

المعلمات

  • downloadId

    الرقم

    رقم تعريف عملية التنزيل المطلوب إلغاؤها

المرتجعات

  • وعد<فراغ>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله عند اكتمال طلب الإلغاء.

download()

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

تنزيل عنوان URL إذا كان عنوان URL يستخدم بروتوكول HTTP[S]، سيتضمّن الطلب جميع ملفات تعريف الارتباط التي تم ضبطها حاليًا لاسم المضيف. في حال تحديد كل من filename وsaveAs، سيتم عرض مربّع الحوار "حفظ باسم"، مع تعبئة filename المحدّد تلقائيًا. إذا بدأت عملية التنزيل بنجاح، سيتم استدعاء callback باستخدام downloadId الجديد لـ DownloadItem. في حال حدوث خطأ أثناء بدء عملية التنزيل، سيتم استدعاء callback باستخدام downloadId=undefined وسيحتوي runtime.lastError على سلسلة وصفية. لا نضمن أن تظل سلاسل الأخطاء متوافقة مع الأنظمة القديمة بين الإصدارات. ويجب ألا تحلّلها الإضافات.

المعلمات

  • الخيارات

    DownloadOptions

    ما يمكن تنزيله وكيفية تنزيله

المرتجعات

  • <number>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة Promise يتم حلّه باستخدام معرّف DownloadItem الجديد.

erase()

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

محو DownloadItem المطابق من السجلّ بدون حذف الملف الذي تم تنزيله سيتم تنشيط حدث onErased لكل DownloadItem يتطابق مع query، ثم سيتم استدعاء callback.

المعلمات

المرتجعات

  • Promise<number[]>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getFileIcon()

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

استرداد رمز لعملية التنزيل المحدّدة بالنسبة إلى عمليات التنزيل الجديدة، تتوفّر رموز الملفات بعد تحديد اسم الملف المستهدَف للتنزيل (على سبيل المثال، عند تنشيط onChanged مع تغيير filename). ستؤدي محاولة استرداد الرمز قبل تحديد اسم الملف إلى حدوث خطأ من خلال runtime.lastError. قد تختلف الصورة التي تعرضها هذه الدالة أثناء عملية التنزيل عن الصورة التي تعرضها بعد اكتمال عملية التنزيل. يتم استرداد الرموز من خلال طلب البحث في نظام التشغيل أو مجموعة الأدوات الأساسية حسب النظام الأساسي. وبالتالي، يعتمد الرمز الذي يتم عرضه على عدد من العوامل، بما في ذلك حالة عملية التنزيل والنظام الأساسي وأنواع الملفات المسجَّلة والمظهر المرئي. إذا تعذّر تحديد رمز ملف، سيحتوي runtime.lastError على رسالة خطأ.

المعلمات

  • downloadId

    الرقم

    معرّف عملية التنزيل

  • الخيارات

    GetFileIconOptions اختياري

المرتجعات

  • Promise<string | undefined>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله باستخدام عنوان URL لصورة تمثّل عملية التنزيل.

open()

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

يفتح الملف الذي تم تنزيله الآن إذا اكتملت عملية DownloadItem، وإلا سيتم عرض خطأ من خلال runtime.lastError. تتطلّب هذه الطريقة إذن "downloads.open" بالإضافة إلى إذن "downloads". يتم بدء حدث onChanged عند فتح العنصر لأول مرة. لا يمكن استدعاء هذه الطريقة إلا استجابةً لإجراء تفاعلي من المستخدم.

المعلمات

  • downloadId

    الرقم

    معرّف الملف الذي تم تنزيله

المرتجعات

  • وعد<فراغ>

    الإصدار 123 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

pause()

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

أوقِف عملية التنزيل مؤقتًا. إذا نجح الطلب، ستكون عملية التنزيل في حالة إيقاف مؤقت. بخلاف ذلك، يحتوي runtime.lastError على رسالة خطأ. سيتعذّر إكمال الطلب إذا لم تكن عملية التنزيل نشطة.

المعلمات

  • downloadId

    الرقم

    معرّف عملية التنزيل المطلوب إيقافها مؤقتًا

المرتجعات

  • وعد<فراغ>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله عند اكتمال طلب الإيقاف المؤقت.

removeFile()

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

يجب إزالة الملف الذي تم تنزيله إذا كان موجودًا واكتملت عملية DownloadItem، وإلا يجب عرض رسالة خطأ من خلال runtime.lastError.

المعلمات

  • downloadId

    الرقم

المرتجعات

  • وعد<فراغ>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

resume()

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

استئناف عملية تنزيل متوقفة مؤقتًا إذا تم تنفيذ الطلب بنجاح، ستكون عملية التنزيل جارية وغير متوقفة مؤقتًا. بخلاف ذلك، يحتوي runtime.lastError على رسالة خطأ. سيتعذّر إكمال الطلب إذا لم تكن عملية التنزيل نشطة.

المعلمات

  • downloadId

    الرقم

    رقم تعريف عملية التنزيل المطلوب استئنافها

المرتجعات

  • وعد<فراغ>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    تعرض هذه الطريقة كائن Promise يتم حله عند اكتمال طلب الاستئناف.

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

ابحث عن DownloadItem. اضبط query على العنصر الفارغ للحصول على جميع DownloadItem. للحصول على DownloadItem معيّن، اضبط الحقل id فقط. للانتقال بين عدد كبير من العناصر، اضبط orderBy: ['-startTime']، واضبط limit على عدد العناصر في كل صفحة، واضبط startedAfter على startTime لآخر عنصر من الصفحة الأخيرة.

المعلمات

المرتجعات

  • Promise<DownloadItem[]>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

setShelfEnabled()

تم إيقافها نهائيًا منذ الإصدار 117 من Chrome
browser.downloads.setShelfEnabled(
  enabled: boolean,
): void

يمكنك استخدام setUiOptions كبديل.

تتيح لك هذه السياسة تفعيل الرف الرمادي أو إيقافه في أسفل كل نافذة مرتبطة بالملف الشخصي الحالي للمتصفّح. سيتم إيقاف الرف طالما أنّ هناك إضافة واحدة على الأقل أوقفته. سيؤدي تفعيل الرف أثناء إيقافه من قِبل إضافة أخرى واحدة على الأقل إلى ظهور خطأ من خلال runtime.lastError. يتطلّب ذلك إذن "downloads.shelf" بالإضافة إلى إذن "downloads".

المعلمات

  • مفعّلة

    قيمة منطقية

setUiOptions()

الإصدار 105 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.downloads.setUiOptions(
  options: UiOptions,
): Promise<void>

يغيّر هذا الإعداد واجهة مستخدم التنزيل لكل نافذة مرتبطة بملف المتصفّح الشخصي الحالي. طالما أنّ هناك إضافة واحدة على الأقل تم ضبط UiOptions.enabled فيها على "خطأ"، سيتم إخفاء واجهة مستخدم التنزيل. سيؤدي ضبط UiOptions.enabled على "صحيح" في حال أوقفت إضافة أخرى واحدة على الأقل هذه الميزة إلى ظهور خطأ من خلال runtime.lastError. يتطلّب ذلك إذن "downloads.ui" بالإضافة إلى إذن "downloads".

المعلمات

  • الخيارات

    UiOptions

    تضمين تغيير في واجهة مستخدم التنزيل

المرتجعات

  • وعد<فراغ>

    تعرض هذه الطريقة كائن Promise يتم حله عند اكتمال تحديث واجهة المستخدم.

show()

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

عرض الملف الذي تم تنزيله في مجلده في مدير الملفات

المعلمات

  • downloadId

    الرقم

    معرّف الملف الذي تم تنزيله

showDefaultFolder()

browser.downloads.showDefaultFolder(): void

عرض مجلد "عمليات التنزيل" التلقائي في مدير الملفات

الفعاليات

onChanged

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

عندما تتغيّر أيّ من سمات DownloadItem باستثناء bytesReceived وestimatedEndTime، يتم تنشيط هذا الحدث باستخدام downloadId وعنصر يحتوي على السمات التي تم تغييرها.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (downloadDelta: DownloadDelta) => void

onCreated

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

يتم تنشيط هذا الحدث باستخدام الكائن DownloadItem عند بدء عملية تنزيل.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (downloadItem: DownloadItem) => void

onDeterminingFilename

browser.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

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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

onErased

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

يتم تنشيطه باستخدام downloadId عند محو عملية تنزيل من السجلّ.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (downloadId: number) => void

    • downloadId

      الرقم