chrome.downloads

الوصف

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

الأذونات

downloads

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

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

أمثلة

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

الأنواع

BooleanDelta

أماكن إقامة

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

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

  • السابق

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

DangerType

ملف

اسم ملف عملية التنزيل مريب.

url

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

محتوى

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

غير شائعة

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

مضيف

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

غير مرغوب فيه

من المحتمل أن يكون التنزيل غير مرغوب فيه أو غير آمن. مثلاً: يمكنه إجراء تغييرات على إعدادات المتصفح أو الكمبيوتر.

وضع آمن

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

مقبول

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

Enum

"asyncScanning"

"asyncLocalPasswordScanning"

DoubleDelta

أماكن إقامة

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

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

  • السابق

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

DownloadDelta

أماكن إقامة

  • canResume

    BooleanDelta اختيارية

    تمثّل هذه السمة التغيير في canResume، إن وُجد.

  • الخطر

    StringDelta اختيارية

    تمثّل هذه السمة التغيير في danger، إن وُجد.

  • endTime

    StringDelta اختيارية

    تمثّل هذه السمة التغيير في endTime، إن وُجد.

  • خطأ

    StringDelta اختيارية

    تمثّل هذه السمة التغيير في error، إن وُجد.

  • موجود

    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

    منطقي

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

  • الخطر

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

  • موجود

    منطقي

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

  • fileSize

    الرقم

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

  • filename

    سلسلة

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

  • finalUrl

    سلسلة

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

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

  • id

    الرقم

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

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

    منطقي

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

  • مقلِّد

    سلسلة

    نوع MIME للملف

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

    منطقي

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

  • مُحيل

    سلسلة

    عنوان URL المطلق.

  • startTime

    سلسلة

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

  • الولاية

    الولاية

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

  • totalBytes

    الرقم

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

  • url

    سلسلة

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

DownloadOptions

أماكن إقامة

  • النص الأساسي

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

    نص المشاركة.

  • conflictAction

    FilenameConflictAction اختياري

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

  • filename

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

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

  • الرؤوس

    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

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

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

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

  • finalUrlRegex

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

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

    يؤدي هذا الإجراء إلى حصر النتائج بـ DownloadItem الذي يتطابق finalUrl مع التعبير العادي المحدَّد.

  • id

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

    id من DownloadItem لطلب البحث.

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

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

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

  • مقلِّد

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

    نوع MIME للملف

  • orderBy

    string[] اختيارية

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

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

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

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

  • query

    string[] اختيارية

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

  • startTime

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

    الوقت الذي بدأ فيه التنزيل بتنسيق ISO 8601

  • startedAfter

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

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

  • startedBefore

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

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

  • الولاية

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

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

  • totalBytes

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

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

  • totalBytesGreater

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

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

  • totalBytesLess

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

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

  • url

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

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

  • urlRegex

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

    يؤدي هذا الإجراء إلى حصر النتائج بـ DownloadItem الذي يتطابق url مع التعبير العادي المحدَّد.

FilenameConflictAction

توحيد

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

استبدال

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

إشعار

سيظهر مربع حوار "منتقي الملفات" لمطالبة المستخدم.

Enum

FilenameSuggestion

أماكن إقامة

  • conflictAction

    FilenameConflictAction اختياري

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

  • filename

    سلسلة

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

GetFileIconOptions

أماكن إقامة

  • الحجم

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

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

HeaderNameValuePair

أماكن إقامة

  • الاسم

    سلسلة

    اسم عنوان HTTP

  • القيمة

    سلسلة

    قيمة عنوان HTTP

HttpMethod

Enum

InterruptReason

Enum

State

in_progress

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

تمت مقاطعة

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

مكتمل

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

Enum

StringDelta

أماكن إقامة

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

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

  • السابق

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

UiOptions

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

أماكن إقامة

  • مفعّلة

    منطقي

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

الطُرق

acceptDanger()

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

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

المعلمات

  • downloadId

    الرقم

    معرِّف DownloadItem.

  • رد الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

cancel()

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

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

المعلمات

  • downloadId

    الرقم

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

      الرقم

المرتجعات

  • Promise<number>

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

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

erase()

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

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

المعلمات

  • رد الاتصال

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

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

    (erasedIds: number[]) => void

    • erasedIds

      رقم[]

المرتجعات

  • Promise<number[]>

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

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

getFileIcon()

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

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

المعلمات

  • downloadId

    الرقم

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

  • الخيارات

    GetFileIconOptions اختياري

  • رد الاتصال

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

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

    (iconURL?: string) => void

    • iconURL

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

المرتجعات

  • Promise<string | غير محددة>

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

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

open()

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

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

المعلمات

  • downloadId

    الرقم

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

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

pause()

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

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

المعلمات

  • downloadId

    الرقم

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

removeFile()

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

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

المعلمات

  • downloadId

    الرقم

  • رد الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

resume()

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

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

المعلمات

  • downloadId

    الرقم

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

  • رد الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

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

المعلمات

  • رد الاتصال

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

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

    (results: DownloadItem[]) => void

المرتجعات

  • Promise<DownloadItem[]>

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

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

setShelfEnabled()

متوقّف منذ الإصدار 117 من Chrome
chrome.downloads.setShelfEnabled(
  enabled: boolean,
)

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

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

المعلمات

  • مفعّلة

    منطقي

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

onCreated

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

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

المعلمات

  • رد الاتصال

    دالة

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

    (downloadItem: DownloadItem) => void

onDeterminingFilename

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

أثناء عملية تحديد اسم الملف، سيتم منح الإضافات فرصة لإلغاء DownloadItem.filename الهدف. قد لا تسجِّل كل إضافة أكثر من مستمع واحد لهذا الحدث. يجب أن يتّصل كل مستمع إلى suggest مرة واحدة بالضبط، إما بشكل متزامن أو غير متزامن. إذا طلب المستمع suggest بشكل غير متزامن، يجب عرض true. إذا لم يستدعي المستمع suggest بشكل متزامن أو لم يعرض true، سيتم استدعاء suggest تلقائيًا. لن تكتمل DownloadItem حتى يتصل جميع المستمعين بـ suggest. يمكن لأدوات معالجة البيانات استدعاء suggest بدون أي وسيطات للسماح للتنزيل باستخدام downloadItem.filename لاسم الملف، أو تمرير كائن suggestion إلى suggest لإلغاء اسم الملف الهدف. إذا تجاوزت أكثر من امتداد اسم الملف، ستفوز الإضافة الأخيرة التي تم تثبيتها والتي يمرّر المستمع كائن suggestion إلى suggest. ولتجنب الالتباس بشأن الإضافة التي ستفوز، لا ينبغي للمستخدمين تثبيت الإضافات التي قد تتعارض. إذا بدأت عملية التنزيل من قِبل download وكان اسم الملف الهدف معروفًا قبل تحديد نوع MIME واسم الملف المبدئي، انتقِل filename إلى download بدلاً من ذلك.

المعلمات

  • رد الاتصال

    دالة

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

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

onErased

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

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

المعلمات

  • رد الاتصال

    دالة

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

    (downloadId: number) => void

    • downloadId

      الرقم