chrome.downloads

يؤدي هذا الإذن إلى ظهور تحذير

الوصف

استخدِم واجهة برمجة التطبيقات 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"
يتم استخدامها من خلال إضافة "متصفّح المؤسسات الآمن". عند الحاجة، سيحظر Chrome تنزيل الملف على القرص وسينزّله مباشرةً إلى OneDrive.

DoubleDelta

الخصائص

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

    number اختياري

  • السابق

    number اختياري

DownloadDelta

الخصائص

  • canResume

    BooleanDelta اختياري

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

  • الخطر

    StringDelta اختياري

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

  • endTime

    StringDelta اختياري

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

  • خطأ

    StringDelta اختياري

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

  • exists

    BooleanDelta اختياري

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

  • fileSize

    DoubleDelta اختيارية

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

  • filename

    StringDelta اختياري

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

  • finalUrl

    StringDelta اختياري

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

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

  • id

    الرقم

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

  • مقلِّد

    StringDelta اختياري

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

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

    BooleanDelta اختياري

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

  • startTime

    StringDelta اختياري

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

  • الولاية

    StringDelta اختياري

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

  • totalBytes

    DoubleDelta اختيارية

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

  • url

    StringDelta اختياري

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

DownloadItem

الخصائص

  • byExtensionId

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

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

  • byExtensionName

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

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

  • bytesReceived

    الرقم

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

  • canResume

    قيمة منطقية

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

  • الخطر

    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))})})

  • exists

    قيمة منطقية

    تُستخدَم لتحديد ما إذا كان الملف الذي تم تنزيله لا يزال متوفّرًا. قد تكون هذه المعلومات قديمة لأنّ Chrome لا يتتبّع إزالة الملفات تلقائيًا. استخدِم الدالة search() لتفعيل عملية التحقّق من توفّر الملف. عند اكتمال عملية التحقّق من الوجود، إذا تم حذف الملف، سيتم تشغيل الحدث onChanged. يُرجى العِلم أنّ الدالة search() لا تنتظر انتهاء عملية التحقّق من الوجود قبل عرض النتيجة، لذا قد لا تعكس نتائج الدالة search() نظام الملفات بدقة. بالإضافة إلى ذلك، يمكن استدعاء search() عدة مرات حسب الحاجة، ولكن لن يتم التحقّق من توفّر الملف أكثر من مرة كل 10 ثوانٍ.

  • fileSize

    الرقم

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

  • filename

    سلسلة

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

  • finalUrl

    سلسلة

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

    عنوان 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 اختيارية

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

  • exists

    boolean اختياري

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

  • fileSize

    number اختياري

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

  • filename

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

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

  • filenameRegex

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

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

  • finalUrl

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

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

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

  • finalUrlRegex

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

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

    يحصر النتائج في 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 اختياري

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

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"

"complete"

StringDelta

الخصائص

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

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

  • السابق

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

UiOptions

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

الخصائص

  • مفعّلة

    قيمة منطقية

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

الطُرق

acceptDanger()

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

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

المعلمات

  • downloadId

    الرقم

    تمثّل هذه السمة المعرّف الخاص DownloadItem.

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

cancel()

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

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

المعلمات

  • downloadId

    الرقم

    رقم تعريف عملية التنزيل التي تريد إلغاءها.

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    تعرض هذه الطريقة 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>

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

    تعرض هذه الطريقة 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[]>

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

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

getFileIcon()

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

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

المعلمات

  • downloadId

    الرقم

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

  • الخيارات

    GetFileIconOptions اختياري

  • callback

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

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

    (iconURL?: string) => void

    • iconURL

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

المرتجعات

  • Promise<string | undefined>

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

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

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

open()

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

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

المعلمات

  • downloadId

    الرقم

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

  • callback

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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

pause()

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

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

المعلمات

  • downloadId

    الرقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

removeFile()

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

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

المعلمات

  • downloadId

    الرقم

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

resume()

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

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

المعلمات

  • downloadId

    الرقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    تعرض هذه الطريقة 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[]>

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

    لا تتوفّر الوعود إلا في الإصدار 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

      الرقم