chrome.downloads

الوصف

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

الأذونات

downloads

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

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

أمثلة

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

الأنواع

BooleanDelta

أماكن إقامة

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

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

• السابق

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

DangerType

ملف

اسم الملف الذي تمّ تنزيله مُريب.

url

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

للربح

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

غير شائعة

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

مضيف

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

غير مرغوب فيه

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

وضع آمن

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

مقبول

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

التعداد

"file"

"url"

"passwordProtected"

"sensitiveContentBlock"

"accountCompromise"

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، إن توفّر.

• state

  StringDelta اختيارية

  التغيير في state، إن توفّر.

• totalBytes

  DoubleDelta اختياري

  التغيير في totalBytes، إن توفّر.

• url

  StringDelta اختيارية

  التغيير في url، إن توفّر.

DownloadItem

أماكن إقامة

• byExtensionId

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

  معرّف الإضافة التي بدأت عملية التنزيل هذه إذا بدأت إحدى الإضافات عملية التنزيل هذه. لا يتغير بعد تعيينه.

• byExtensionName

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

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

• bytesReceived

  الرقم

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

• canResume

  boolean

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

• الخطر

  DangerType

  يشير إلى ما إذا كان هذا التنزيل آمنًا أو معروفًا للريبة.

• endTime

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

  تمثّل هذه السمة الوقت الذي انتهى فيه التنزيل بالتنسيق ISO 8601. يمكن تمريره مباشرةً إلى الدالة الإنشائية للتاريخ: 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. يمكن تمريره مباشرةً إلى الدالة الإنشائية للتاريخ: chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

• موجود

  boolean

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

• fileSize

  الرقم

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

• filename

  سلسلة

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

• finalUrl

  سلسلة

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

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

• id

  الرقم

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

• وضع التصفّح المتخفي

  boolean

  خطأ إذا تم تسجيل هذا التنزيل في السجل، يكون "صواب" إذا لم يتم تسجيله.

• مقلِّد

  سلسلة

  نوع MIME للملف

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

  boolean

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

• referrer

  سلسلة

  عنوان URL كامل.

• startTime

  سلسلة

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

• state

  الولاية

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

• totalBytes

  الرقم

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

• url

  سلسلة

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

DownloadOptions

أماكن إقامة

• body

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

  نص المشاركة

• conflictAction

  FilenameConflictAction اختياري

  تمثل هذه السمة الإجراء الذي يجب اتخاذه في حال توفُّر filename.

• filename

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

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

• headers

  HeaderNameValuePair[] اختيارية

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

• method

  HttpMethod اختيارية

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

• saveAs

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

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

• url

  سلسلة

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

DownloadQuery

أماكن إقامة

• bytesReceived

  الرقم اختياري

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

• الخطر

  DangerType اختيارية

  يشير إلى ما إذا كان هذا التنزيل آمنًا أو معروفًا للريبة.

• endTime

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

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

• endedAfter

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

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

• endedBefore

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

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

• خطأ

  InterruptReason اختياري

  أسباب انقطاع عملية التنزيل

• موجود

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

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

• fileSize

  الرقم اختياري

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

• filename

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

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

• filenameRegex

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

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

• finalUrl

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

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

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

• finalUrlRegex

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

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

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

• id

  الرقم اختياري

  id من DownloadItem المطلوب البحث عنها.

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

  الرقم اختياري

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

• مقلِّد

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

  نوع MIME للملف

• orderBy

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

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

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

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

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

• query

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

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

• startTime

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

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

• startedAfter

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

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

• startedBefore

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

  يؤدي هذا الخيار إلى حصر النتائج بـ DownloadItem التي بدأت قبل الملي ثانية المحددة بتنسيق ISO 8601.

• state

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

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

• totalBytes

  الرقم اختياري

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

• totalBytesGreater

  الرقم اختياري

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

• totalBytesLess

  الرقم اختياري

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

• url

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

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

• urlRegex

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

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

FilenameConflictAction

توحيد

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

استبدال

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

طلب

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

التعداد

"uniquify"

FilenameSuggestion

أماكن إقامة

• conflictAction

  FilenameConflictAction اختياري

  تمثل هذه السمة الإجراء الذي يجب اتخاذه في حال توفُّر filename.

• filename

  سلسلة

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

GetFileIconOptions

أماكن إقامة

• الحجم

   اختياري

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

HeaderNameValuePair

أماكن إقامة

• اسم

  سلسلة

  اسم عنوان HTTP.

• القيمة

  سلسلة

  قيمة عنوان HTTP.

HttpMethod

التعداد

"POST"

InterruptReason

التعداد

"FILE_ACCESS_DENIED"

"FILE_NO_SPACE"

"FILE_TOO_LARGE"

"FILE_TRANSIENT_ERROR"

"FILE_BLOCKED"

"FILE_TOO_SHORT"

"FILE_HASH_MISMATCH"

"FILE_SAME_AS_SOURCE"

"NETWORK_DISCONNECTED"

"NETWORK_SERVER_DOWN"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"SERVER_UNAUTHORIZED"

"SERVER_CERT_PROBLEM"

"SERVER_UNREACHABLE"

"SERVER_CONTENT_LENGTH_MISMATCH"

"USER_CANCELED"

"USER_SHUTDOWN"

"CRASH"

State

in_progress

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

تمت مقاطعة

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

مكتمل

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

التعداد

"in_progress"

StringDelta

أماكن إقامة

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

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

• السابق

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

UiOptions

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

أماكن إقامة

• مفعّلة

  boolean

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

الطُرق

acceptDanger()

وعد

chrome.downloads.acceptDanger(
  downloadId: number,
  callback?: function,
)

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

المَعلمات

• downloadId

  الرقم

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

cancel()

وعد

chrome.downloads.cancel(
  downloadId: number,
  callback?: function,
)

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

المَعلمات

• downloadId

  الرقم

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

download()

وعد

chrome.downloads.download(
  options: DownloadOptions,
  callback?: function,
)

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

المَعلمات

• الخيارات

  DownloadOptions

  المحتوى الذي يمكن تنزيله وكيفية إجراء ذلك

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (downloadId: number)=>void

  • downloadId

    الرقم

المرتجعات

• وعد<الرقم>

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

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

erase()

وعد

chrome.downloads.erase(
  query: DownloadQuery,
  callback?: function,
)

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

المَعلمات

• query

  DownloadQuery

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (erasedIds: number[])=>void

  • erasedIds

    الرقم[]

المرتجعات

• وعد<رقم[]>

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

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

getFileIcon()

وعد

chrome.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
  callback?: function,
)

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

المَعلمات

• downloadId

  الرقم

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

• الخيارات

  GetFileIconOptions اختيارية

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (iconURL?: string)=>void

  • iconURL

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

المرتجعات

• الوعد<string|unified>

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

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

open()

وعد

chrome.downloads.open(
  downloadId: number,
  callback?: function,
)

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

المَعلمات

• downloadId

  الرقم

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

• معاودة الاتصال

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

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

pause()

وعد

chrome.downloads.pause(
  downloadId: number,
  callback?: function,
)

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

المَعلمات

• downloadId

  الرقم

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

removeFile()

وعد

chrome.downloads.removeFile(
  downloadId: number,
  callback?: function,
)

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

المَعلمات

• downloadId

  الرقم

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

resume()

وعد

chrome.downloads.resume(
  downloadId: number,
  callback?: function,
)

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

المَعلمات

• downloadId

  الرقم

  رقم تعريف عملية التنزيل المراد استئنافها.

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

search()

وعد

chrome.downloads.search(
  query: DownloadQuery,
  callback?: function,
)

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

المَعلمات

• query

  DownloadQuery

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (results: DownloadItem[])=>void

  • النتائج

    DownloadItem[]

المرتجعات

• Promise<DownloadItem[]>

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

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

setShelfEnabled()

تم إيقافها منذ أن بدأت Chrome 117

chrome.downloads.setShelfEnabled(
  enabled: boolean,
)

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

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

المَعلمات

• مفعّلة

  boolean

setUiOptions()

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

chrome.downloads.setUiOptions(
  options: UiOptions,
  callback?: function,
)

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

المَعلمات

• الخيارات

  UiOptions

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

show()

chrome.downloads.show(
  downloadId: number,
)

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

المَعلمات

• downloadId

  الرقم

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

showDefaultFolder()

chrome.downloads.showDefaultFolder()

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

فعاليات

onChanged

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (downloadDelta: DownloadDelta)=>void

  • downloadDelta

    DownloadDelta

onCreated

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (downloadItem: DownloadItem)=>void

  • downloadItem

    DownloadItem

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

  • downloadItem

    DownloadItem

  • اقتراح

    الوظيفة

    تبدو معلَمة suggest على النحو التالي:

    (suggestion?: FilenameSuggestion)=>void

    • اقتراح

      FilenameSuggestion اختيارية

onErased

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (downloadId: number)=>void

  • downloadId

    الرقم