chrome.downloads

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

الوصف

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

الأذونات

downloads

البيان

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

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

أمثلة

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

الأنواع

BooleanDelta

الخصائص

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

    boolean اختياري

  • السابق

    boolean اختياري

DangerType

ملف

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

url

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

المحتوى

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

غير شائعة

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

مضيف

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

غير مرغوب فيه

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

فعّالة

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

مقبول

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

Enum

"file"

"url"

"content"

"uncommon"

"host"

"unwanted"

"safe"

"accepted"

"allowlistedByPolicy"

"asyncScanning"

"asyncLocalPasswordScanning"

"passwordProtected"

"blockedTooLarge"

"sensitiveContentWarning"

"sensitiveContentBlock"

"deepScannedFailed"

"deepScannedSafe"

"deepScannedOpenedDangerous"

"promptForScanning"

"promptForLocalPasswordScanning"

"accountCompromise"

"blockedScanFailed"

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

    قيمة منطقية

    القيمة False إذا تم تسجيل عملية التنزيل هذه في السجلّ، والقيمة True إذا لم يتم تسجيلها.

  • مقلِّد

    سلسلة

    نوع 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 لتضمين عدّاد قبل امتداد اسم الملف.

استبدال

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

prompt

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

Enum

"uniquify"

"overwrite"

"prompt"

FilenameSuggestion

الخصائص

  • conflictAction

    ‫FilenameConflictAction اختياري

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

  • filename

    سلسلة

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

GetFileIconOptions

الخصائص

  • الحجم

    number اختياري

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

HeaderNameValuePair

الخصائص

  • الاسم

    سلسلة

    اسم عنوان HTTP.

  • القيمة

    سلسلة

    قيمة عنوان HTTP

HttpMethod

Enum

"GET"

"POST"

InterruptReason

Enum

"FILE_FAILED"

"FILE_ACCESS_DENIED"

"FILE_NO_SPACE"

"FILE_NAME_TOO_LONG"

"FILE_TOO_LARGE"

"FILE_VIRUS_INFECTED"

"FILE_TRANSIENT_ERROR"

"FILE_BLOCKED"

"FILE_SECURITY_CHECK_FAILED"

"FILE_TOO_SHORT"

"FILE_HASH_MISMATCH"

"FILE_SAME_AS_SOURCE"

"NETWORK_FAILED"

"NETWORK_TIMEOUT"

"NETWORK_DISCONNECTED"

"NETWORK_SERVER_DOWN"

"NETWORK_INVALID_REQUEST"

"SERVER_FAILED"

"SERVER_NO_RANGE"

"SERVER_BAD_CONTENT"

"SERVER_UNAUTHORIZED"

"SERVER_CERT_PROBLEM"

"SERVER_FORBIDDEN"

"SERVER_UNREACHABLE"

"SERVER_CONTENT_LENGTH_MISMATCH"

"SERVER_CROSS_ORIGIN_REDIRECT"

"USER_CANCELED"

"USER_SHUTDOWN"

"CRASH"

State

in_progress

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

متقطّع

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

مكتمل

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

Enum

"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 والإصدارات الأحدث

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

cancel()

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

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

المعلمات

  • downloadId

    الرقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    لا تتوافق الوعود إلا مع الإصدار 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 والإصدارات الأحدث

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

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

المعلمات

  • downloadId

    الرقم

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

  • الخيارات

    GetFileIconOptions اختيارية

  • callback

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

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

    (iconURL?: string) => void

    • iconURL

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

المرتجعات

  • Promise<string | undefined>

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

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

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

    لا تتوافق الوعود إلا مع الإصدار 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 والإصدارات الأحدث

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

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

      الرقم