chrome.downloads

refresh date: 2026-09-25 robots: noindex

يؤدي هذا الإذن إلى إطلاق تحذير

الوصف

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

الأذونات

downloads

البيان

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

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

أمثلة

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

الأنواع

BooleanDelta

الخصائص

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

    boolean اختياري

  • السابق

    boolean اختياري

DangerType

تعداد

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

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

"المحتوى"
يُعرف أنّ الملف الذي تم تنزيله ضار.

"غير شائع"
عنوان URL لعملية التنزيل غير شائع وقد يكون خطيرًا.

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

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

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

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

"allowlistedByPolicy"
قيم مرتبطة بالمؤسسة

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

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

"forceSaveToOnedrive"
يتم استخدامها من خلال إضافة Secure Enterprise Browser. عند الحاجة، سيحظر 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 اختياري

    Chrome 54 والإصدارات الأحدث

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

  • id

    الرقم

    id DownloadItem الذي تم تغييره.

  • مقلِّد

    StringDelta اختياري

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

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

    BooleanDelta اختياري

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

  • startTime

    StringDelta اختياري

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

  • الولاية

    StringDelta اختياري

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

  • totalBytes

    DoubleDelta اختياري

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

  • url

    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() عدة مرات حسب الحاجة، ولكن لن يتم التحقّق من توفّر الملف أكثر من مرة كل 10 ثوانٍ.

  • fileSize

    الرقم

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

  • filename

    سلسلة

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

  • finalUrl

    سلسلة

    Chrome 54 والإصدارات الأحدث

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

  • id

    الرقم

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

  • incognito

    قيمة منطقية

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

  • مقلِّد

    سلسلة

    نوع MIME للملف

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

    قيمة منطقية

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

  • مُحيل

    سلسلة

    عنوان 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

الخصائص

  • body

    سلسلة اختيارية

    نص المنشور

  • conflictAction

    ‫FilenameConflictAction اختيارية

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

  • filename

    سلسلة اختيارية

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

  • العناوين

    HeaderNameValuePair[] اختيارية

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

  • method

    ‫HttpMethod اختياري

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

  • saveAs

    boolean اختياري

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

  • url

    سلسلة

    تمثّل هذه السمة عنوان URL المطلوب تنزيله.

DownloadQuery

الخصائص

  • bytesReceived

    number اختياري

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

  • خطر

    ‫DangerType اختياري

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

  • endTime

    سلسلة اختيارية

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

  • endedAfter

    سلسلة اختيارية

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

  • endedBefore

    سلسلة اختيارية

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

  • خطأ

    ‫InterruptReason اختياري

    أسباب إيقاف التنزيل

  • يوجد

    boolean اختياري

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

  • fileSize

    number اختياري

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

  • filename

    سلسلة اختيارية

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

  • filenameRegex

    سلسلة اختيارية

    يقتصر على النتائج التي يكون فيها DownloadItem الذي يتطابق filename مع التعبير العادي المحدّد.

  • finalUrl

    سلسلة اختيارية

    Chrome 54 والإصدارات الأحدث

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

  • finalUrlRegex

    سلسلة اختيارية

    Chrome 54 والإصدارات الأحدث

    يحصر النتائج في DownloadItem الذي يتطابق finalUrl فيه مع التعبير العادي المحدّد.

  • id

    number اختياري

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

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

    number اختياري

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

  • مقلِّد

    سلسلة اختيارية

    نوع MIME للملف

  • orderBy

    string[] اختياري

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

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

    boolean اختياري

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

  • query

    string[] اختياري

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

  • startTime

    سلسلة اختيارية

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

  • startedAfter

    سلسلة اختيارية

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

  • startedBefore

    سلسلة اختيارية

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

  • الولاية

    الولاية اختيارية

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

  • totalBytes

    number اختياري

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

  • totalBytesGreater

    number اختياري

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

  • totalBytesLess

    number اختياري

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

  • url

    سلسلة اختيارية

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

  • urlRegex

    سلسلة اختيارية

    يقتصر على النتائج التي يكون فيها DownloadItem الذي يتطابق url مع التعبير العادي المحدّد.

FilenameConflictAction

uniquify

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

استبدال

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

طلب

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

تعداد

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

الخصائص

  • conflictAction

    ‫FilenameConflictAction اختيارية

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

  • filename

    سلسلة

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

GetFileIconOptions

الخصائص

  • الحجم

    number اختياري

    حجم الرمز المعروض سيكون الرمز مربّعًا بأبعاد حجم * حجم بالبكسل. الحجم التلقائي والأكبر للرمز هو 32x32 بكسل. الأحجام المتوافقة فقط هي 16 و32. ويُعدّ تحديد أي حجم آخر خطأً.

HeaderNameValuePair

الخصائص

  • الاسم

    سلسلة

    اسم عنوان HTTP

  • القيمة

    سلسلة

    قيمة عنوان HTTP

HttpMethod

تعداد

"GET"

"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

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

متقطّع

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

complete

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

تعداد

"in_progress"

"interrupted"

"مكتملة"

StringDelta

الخصائص

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

    سلسلة اختيارية

  • السابق

    سلسلة اختيارية

UiOptions

‫Chrome 105 والإصدارات الأحدث

الخصائص

  • مفعّلة

    قيمة منطقية

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

الطُرق

acceptDanger()

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

يُطلب من المستخدم قبول تنزيل ملف خطير. لا يمكن استدعاؤها إلا من سياق مرئي (علامة تبويب أو نافذة أو صفحة أو نافذة منبثقة لإجراء في المتصفّح). لا يقبل عمليات التنزيل الخطيرة تلقائيًا. في حال قبول التنزيل، سيتم تنشيط الحدث onChanged، وإلا لن يحدث أي شيء. عندما يتم جلب جميع البيانات إلى ملف مؤقت، ويكون التنزيل إما غير خطير أو تم قبول الخطورة، تتم إعادة تسمية الملف المؤقت إلى اسم الملف المستهدف، ويتغير state إلى "مكتمل"، ويتم تشغيل onChanged.

المعلمات

  • downloadId

    الرقم

    معرّف DownloadItem.

  • callback

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

    ‫Chrome 96 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

cancel()

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

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

المعلمات

  • downloadId

    الرقم

    تمثّل هذه السمة رقم تعريف عملية التنزيل التي سيتم إلغاؤها.

  • callback

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

    ‫Chrome 96 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

download()

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

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

المعلمات

  • الخيارات

    DownloadOptions

    المحتوى الذي يمكن تنزيله وطريقة تنزيله

  • callback

    الدالة اختيارية

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

    (downloadId: number) => void

    • downloadId

      الرقم

المرتجعات

  • Promise<number>

    ‫Chrome 96 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

erase()

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

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

المعلمات

  • callback

    الدالة اختيارية

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

    (erasedIds: number[]) => void

    • erasedIds

      number[]

المرتجعات

  • Promise<number[]>

    ‫Chrome 96 والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

getFileIcon()

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

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

المعلمات

  • downloadId

    الرقم

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

  • الخيارات

    GetFileIconOptions اختياري

  • callback

    الدالة اختيارية

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

    (iconURL?: string) => void

    • iconURL

      سلسلة اختيارية

المرتجعات

  • Promise<string | undefined>

    ‫Chrome 96 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

open()

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

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

المعلمات

  • downloadId

    الرقم

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

  • callback

    الدالة اختيارية

    الإصدار 123 من Chrome والإصدارات الأحدث

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

    () => void

المرتجعات

  • Promise<void>

    الإصدار 123 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

pause()

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

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

المعلمات

  • downloadId

    الرقم

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

  • callback

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

    ‫Chrome 96 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

removeFile()

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

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

المعلمات

  • downloadId

    الرقم

  • callback

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

    ‫Chrome 96 والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

resume()

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

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

المعلمات

  • downloadId

    الرقم

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

  • callback

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

    ‫Chrome 96 والإصدارات الأحدث

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

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

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

المعلمات

  • callback

    الدالة اختيارية

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

    (results: DownloadItem[]) => void

المرتجعات

  • Promise<DownloadItem[]>

    ‫Chrome 96 والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

setShelfEnabled()

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

استخدِم setUiOptions بدلاً من ذلك.

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

المعلمات

  • مفعّلة

    قيمة منطقية

setUiOptions()

Promise Chrome 105 والإصدارات الأحدث 
chrome.downloads.setUiOptions(
  options: UiOptions,
  callback?: function,
): Promise<void>

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

المعلمات

  • الخيارات

    UiOptions

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

  • callback

    الدالة اختيارية

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

    () => void

المرتجعات

  • Promise<void>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

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

    دالة

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

    (downloadDelta: DownloadDelta) => void

onCreated

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

يتم تشغيل هذا الحدث باستخدام العنصر DownloadItem عند بدء عملية تنزيل.

المعلمات

  • callback

    دالة

    تظهر المَعلمة 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

    دالة

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

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

onErased

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

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

المعلمات

  • callback

    دالة

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

    (downloadId: number) => void

    • downloadId

      الرقم