chrome.webRequest

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات chrome.webRequest لمراقبة حركة البيانات وتحليلها، وللتدخّل في الطلبات أثناء نقلها أو حظرها أو تعديلها.

الأذونات

webRequest

البيان

يجب تضمين الإذن "webRequest" في بيان الإضافة لاستخدام واجهة برمجة التطبيقات لطلبات الويب، بالإضافة إلى أذونات المضيف اللازمة. للتدخّل في طلب مورد فرعي، يجب أن يكون لدى الإضافة إذن الوصول إلى كلّ من عنوان URL المطلوب والمصدر الذي بدأ الطلب. على سبيل المثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

اعتبارًا من الإصدار 108 من Chrome، يمكنك تقديم بيانات الاعتماد بشكل غير متزامن لأحداث onAuthRequired إذا كنت تستخدم أذونات "webRequest" و"webRequestAuthProvider".

دورة حياة الطلبات

تحدّد واجهة برمجة التطبيقات لطلبات الويب مجموعة من الأحداث التي تتّبع دورة حياة طلب الويب. يمكنك استخدام هذه الأحداث لمراقبة حركة الزيارات وتحليلها. ستتيح لك بعض الأحداث المتزامنة اعتراض طلب أو حظره أو تعديله.

في ما يلي دورة حياة الحدث للطلبات الناجحة، يليها تعريفات الأحداث:

دورة حياة طلب الويب من منظور WebRequest API

‫onBeforeRequest (متزامن اختياريًا)
يتم تنشيط هذا الحدث عندما يكون هناك وشك حدوث طلب. يتم إرسال هذا الحدث قبل إنشاء أي اتصال TCP، ويمكن استخدامه لإلغاء الطلبات أو إعادة توجيهها.
‫onBeforeSendHeaders (متزامن اختياريًا)
يتم تشغيل هذا الحدث عندما يكون على وشك حدوث طلب وتم إعداد العناوين الأولية. يهدف الحدث إلى السماح للإضافات بإضافة عناوين الطلبات وتعديلها وحذفها (*). يتم تمرير الحدث onBeforeSendHeaders إلى جميع المشتركين، لذا قد يحاول المشتركون المختلفون تعديل الطلب. راجِع قسم تفاصيل التنفيذ لمعرفة كيفية التعامل مع ذلك. يمكن استخدام هذا الحدث لإلغاء الطلب.
onSendHeaders
يتم تنشيط هذا الحدث بعد أن تتاح لجميع الإضافات فرصة تعديل عناوين الطلبات، ويعرض الإصدار النهائي (*). يتم تشغيل الحدث قبل إرسال العناوين إلى الشبكة. هذا الحدث إعلامي ويتم التعامل معه بشكل غير متزامن. ولا يسمح بتعديل الطلب أو إلغائه.
‫onHeadersReceived (متزامن اختياريًا)
يتم تشغيل هذا المشغّل في كل مرة يتم فيها تلقّي عنوان استجابة HTTP(S). وبسبب عمليات إعادة التوجيه وطلبات المصادقة، يمكن أن يحدث ذلك عدة مرات لكل طلب. يهدف هذا الحدث إلى السماح للإضافات بإضافة عناوين الاستجابة وتعديلها وحذفها، مثل عناوين Content-Type الواردة. تتم معالجة توجيهات التخزين المؤقت قبل تشغيل هذا الحدث، لذا لن يكون لتعديل العناوين، مثل Cache-Control، أي تأثير في ذاكرة التخزين المؤقت للمتصفح. ويتيح لك أيضًا إلغاء الطلب أو إعادة توجيهه.
‫onAuthRequired (متزامن اختياريًا)
يتم تنشيط هذا الحدث عندما يتطلّب الطلب مصادقة المستخدم. يمكن التعامل مع هذا الحدث بشكل متزامن لتوفير بيانات اعتماد المصادقة. يُرجى العِلم أنّ الإضافات قد تقدّم بيانات اعتماد غير صالحة. يجب الحرص على عدم الدخول في حلقة لا نهائية من خلال تقديم بيانات اعتماد غير صالحة بشكل متكرّر. يمكن استخدام هذا الإجراء أيضًا لإلغاء الطلب.
onBeforeRedirect
يتم تنشيط هذا الحدث عندما توشك عملية إعادة التوجيه على التنفيذ. يمكن أن يتم تشغيل عملية إعادة التوجيه من خلال رمز استجابة HTTP أو من خلال إضافة. هذا الحدث إعلامي ويتم التعامل معه بشكل غير متزامن. ولا يسمح لك بتعديل الطلب أو إلغائه.
onResponseStarted
يتم تنشيط هذا الحدث عند تلقّي البايت الأول من نص الردّ. بالنسبة إلى طلبات HTTP، يعني ذلك أنّ سطر الحالة وعناوين الاستجابة متوفّرة. هذا الحدث إعلامي ويتم التعامل معه بشكل غير متزامن. ولا يسمح بتعديل الطلب أو إلغائه.
onCompleted
يتم تنشيط هذا الحدث عند معالجة طلب بنجاح.
onErrorOccurred
يتم تنشيط هذا الحدث عندما يتعذّر معالجة طلب بنجاح.

تضمن واجهة برمجة التطبيقات لطلبات الويب أنّه يتم تنشيط onCompleted أو onErrorOccurred كحدث نهائي لكل طلب، باستثناء حالة واحدة: إذا تمت إعادة توجيه الطلب إلى عنوان URL data://، سيكون onBeforeRedirect هو آخر حدث تم تسجيله.

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

في الوقت الحالي، لا يتم توفير العناوين التالية لحدث onBeforeSendHeaders. يُرجى العِلم أنّ هذه القائمة ليست مضمونة بأنّها كاملة أو ثابتة.

  • التفويض
  • Cache-Control
  • الاتصال
  • Content-Length
  • المضيف
  • If-Modified-Since
  • ‫If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Transfer-Encoding

بدءًا من الإصدار 79 من Chrome، تؤثر تعديلات عناوين الطلبات في عمليات التحقّق من مشاركة المراجع مع نطاقات خارجية (CORS). إذا لم تستوفِ العناوين المعدَّلة للطلبات المشتركة المنشأ المعايير، سيؤدي ذلك إلى إرسال طلب مبدئي لبروتوكول مشاركة الموارد المتعددة المصادر (CORS) إلى الخادم لمعرفة ما إذا كان يمكن قبول هذه العناوين. إذا كنت بحاجة إلى تعديل العناوين بطريقة تخالف بروتوكول CORS، عليك تحديد 'extraHeaders' في opt_extraInfoSpec. من ناحية أخرى، لا يمكن خداع عمليات التحقّق من CORS من خلال تعديل عناوين الاستجابة. إذا كنت بحاجة إلى خداع بروتوكول CORS، عليك أيضًا تحديد 'extraHeaders' لتعديلات الرد.

بدءًا من الإصدار 79 من Chrome، لا تعترض webRequest API طلبات CORS المسبقة والردود عليها تلقائيًا. يكون الطلب المبدئي لبروتوكول مشاركة الموارد المشتركة المنشأ (CORS) الخاص بعنوان URL مرئيًا لإحدى الإضافات إذا كان هناك مستمع يتضمّن 'extraHeaders' محدّدًا في opt_extraInfoSpec لعنوان URL الخاص بالطلب. يمكن أن يستفيد onBeforeRequest أيضًا من 'extraHeaders' في الإصدار 79 من Chrome.

اعتبارًا من الإصدار 79 من Chrome، لا يتم توفير عنوان الطلب التالي ولا يمكن تعديله أو إزالته بدون تحديد 'extraHeaders' في opt_extraInfoSpec:

  • الأصل

بدءًا من الإصدار 72 من Chrome، إذا كنت بحاجة إلى تعديل الردود قبل أن يتمكّن حظر القراءة من مصادر متعددة من حظر الرد، عليك تحديد 'extraHeaders' في opt_extraInfoSpec.

اعتبارًا من الإصدار 72 من Chrome، لا يتم توفير عناوين الطلبات التالية ولا يمكن تعديلها أو إزالتها بدون تحديد 'extraHeaders' في opt_extraInfoSpec:

  • Accept-Language
  • Accept-Encoding
  • المُحيل
  • ملف تعريف الارتباط

اعتبارًا من الإصدار 72 من Chrome، لن يتم توفير عنوان الاستجابة Set-Cookie ولا يمكن تعديله أو إزالته بدون تحديد 'extraHeaders' في opt_extraInfoSpec.

اعتبارًا من الإصدار 89 من Chrome، لا يمكن تعديل عنوان الاستجابة X-Frame-Options أو إزالته بشكل فعّال بدون تحديد 'extraHeaders' في opt_extraInfoSpec.

لا تعرض واجهة برمجة التطبيقات webRequest إلا الطلبات التي تملك الإضافة إذنًا بالاطّلاع عليها، وذلك وفقًا لأذونات المضيف. بالإضافة إلى ذلك، يمكن الوصول إلى المخططات التالية فقط: http:// أو https:// أو ftp:// أو file:// أو ws:// (منذ الإصدار 58 من Chrome) أو wss:// (منذ الإصدار 58 من Chrome) أو urn: (منذ الإصدار 91 من Chrome) أو chrome-extension://. بالإضافة إلى ذلك، يتم إخفاء بعض الطلبات التي تتضمّن عناوين URL تستخدم أحد المخططات أعلاه. وتشمل هذه الحالات chrome-extension://other_extension_id حيث لا يكون other_extension_id هو معرّف الإضافة التي ستتعامل مع الطلب، وhttps://www.google.com/chrome، وطلبات حساسة أخرى أساسية لوظائف المتصفح. بالإضافة إلى ذلك، يتم إخفاء طلبات XMLHttpRequests المتزامنة من معالِجات الأحداث التي تحظرها، وذلك لمنع حدوث حالات توقّف تام. يُرجى العِلم أنّه بالنسبة إلى بعض المخططات المتوافقة، قد تكون مجموعة الأحداث المتاحة محدودة بسبب طبيعة البروتوكول المعنيّ. على سبيل المثال، بالنسبة إلى مخطط الملفات، لا يمكن إرسال سوى onBeforeRequest وonResponseStarted وonCompleted وonErrorOccurred.

اعتبارًا من الإصدار 58 من Chrome، تتيح واجهة برمجة التطبيقات webRequest اعتراض طلب تأكيد الاتصال بخادم WebSocket. بما أنّ عملية المصافحة تتم من خلال طلب ترقية HTTP، فإنّ مسارها يتناسب مع نموذج webRequest الموجّه إلى HTTP. يُرجى العِلم أنّ واجهة برمجة التطبيقات لا تعترض ما يلي:

  • رسائل فردية يتم إرسالها عبر اتصال WebSocket تم إنشاؤه
  • جارٍ إغلاق اتصال WebSocket.

لا يمكن إعادة التوجيه لطلبات WebSocket.

اعتبارًا من الإصدار 72 من Chrome، لن تتمكّن الإضافة من اعتراض طلب إلا إذا كانت لديها أذونات المضيف لكل من عنوان URL المطلوب ومصدر الطلب.

بدءًا من الإصدار 96 من Chrome، تتيح واجهة برمجة التطبيقات webRequest اعتراض طلب المصافحة WebTransport عبر HTTP/3. بما أنّ عملية المصافحة تتم من خلال طلب HTTP CONNECT، فإنّ مسارها يتناسب مع نموذج webRequest المستند إلى HTTP. يُرجى ملاحظة ما يلي:

  • بعد إنشاء الجلسة، لا يمكن للإضافات مراقبة الجلسة أو التدخّل فيها من خلال webRequest API.
  • يتم تجاهل تعديل عناوين طلبات HTTP في onBeforeSendHeaders.
  • غير متاح عمليات إعادة التوجيه والمصادقة في WebTransport عبر HTTP/3.

المفاهيم

كما توضّح الأقسام التالية، تستخدم الأحداث في واجهة برمجة التطبيقات لطلبات الويب أرقام تعريف الطلبات، ويمكنك اختياريًا تحديد الفلاتر والمعلومات الإضافية عند تسجيل أدوات معالجة الأحداث.

معرّفات الطلبات

يتم تحديد كل طلب من خلال معرّف الطلب. ويكون هذا المعرّف فريدًا ضمن جلسة المتصفّح وسياق الإضافة. ويظل ثابتًا خلال دورة حياة الطلب ويمكن استخدامه لمطابقة الأحداث الخاصة بالطلب نفسه. يُرجى العِلم أنّه يتم ربط عدّة طلبات HTTP بطلب ويب واحد في حال إعادة التوجيه عبر HTTP أو المصادقة عبر HTTP.

تسجيل أدوات معالجة الأحداث

لتسجيل متتبِّع أحداث لطلب ويب، عليك استخدام صيغة مختلفة من الدالة addListener() العادية. بالإضافة إلى تحديد دالة ردّ الاتصال، عليك تحديد وسيطة فلتر، ويمكنك تحديد وسيطة معلومات إضافية اختيارية.

تتضمّن وسيطات addListener() لواجهة برمجة التطبيقات لطلبات الويب التعريفات التالية:

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

في ما يلي مثال على الاستماع إلى حدث onBeforeRequest:

chrome.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

يتطلّب كل طلب addListener() دالة ردّ اتصال إلزامية كالمَعلمة الأولى. يتم تمرير دالة معاودة الاتصال هذه إلى قاموس يحتوي على معلومات حول طلب عنوان URL الحالي. تعتمد المعلومات الواردة في هذا القاموس على نوع الحدث المحدّد بالإضافة إلى محتوى opt_extraInfoSpec.

إذا كانت مصفوفة opt_extraInfoSpec الاختيارية تحتوي على السلسلة 'blocking' (مسموح بها فقط للأحداث المحدّدة)، يتم التعامل مع دالّة رد الاتصال بشكل متزامن. وهذا يعني أنّه سيتم حظر الطلب إلى أن تعرض دالّة رد الاتصال النتيجة. في هذه الحالة، يمكن أن تعرض دالة معاودة الاتصال webRequest.BlockingResponse تحدّد دورة الحياة اللاحقة للطلب. استنادًا إلى السياق، يتيح هذا الرد إلغاء طلب أو إعادة توجيهه (onBeforeRequest)، أو إلغاء طلب أو تعديل العناوين (onBeforeSendHeaders وonHeadersReceived)، أو إلغاء طلب أو تقديم بيانات اعتماد المصادقة (onAuthRequired).

إذا كان مصفوفة opt_extraInfoSpec الاختيارية تحتوي على السلسلة 'asyncBlocking' بدلاً من ذلك (مسموح بها فقط لـ onAuthRequired)، يمكن للإضافة إنشاء webRequest.BlockingResponse بشكل غير متزامن.

تسمح السمة webRequest.RequestFilter filter بالحدّ من الطلبات التي يتم تشغيل الأحداث لها في مختلف السمات:

عناوين URL
أنماط عناوين URL، مثل *://www.google.com/foo*bar
الأنواع
أنواع الطلبات، مثل main_frame (مستند يتم تحميله لإطار ذي مستوى أعلى) وsub_frame (مستند يتم تحميله لإطار مضمّن) وimage (صورة على موقع إلكتروني). يمكنك الاطّلاع على webRequest.RequestFilter.
رقم تعريف علامة التبويب
معرّف لعلامة تبويب واحدة
رقم تعريف النافذة
معرّف النافذة

استنادًا إلى نوع الحدث، يمكنك تحديد السلاسل في opt_extraInfoSpec لطلب معلومات إضافية حول الطلب. يتم استخدامها لتقديم معلومات تفصيلية حول بيانات الطلب فقط إذا تم طلب ذلك صراحةً.

تفاصيل التنفيذ

هناك العديد من تفاصيل التنفيذ التي قد يكون من المهم فهمها عند تطوير إضافة تستخدم واجهة برمجة التطبيقات لطلبات الويب:

web_accessible_resources

عندما تستخدم إضافة واجهات برمجة تطبيقات webRequest لإعادة توجيه طلب مورد عام إلى مورد لا يمكن الوصول إليه على الويب، يتم حظرها وسيؤدي ذلك إلى حدوث خطأ. ينطبق ما ورد أعلاه حتى إذا كان المورد الذي لا يمكن الوصول إليه على الويب مملوكًا للإضافة التي تعيد التوجيه. لتحديد الموارد التي سيتم استخدامها مع واجهات برمجة التطبيقات declarativeWebRequest، يجب تحديد مصفوفة "web_accessible_resources" وتعبئتها في ملف البيان كما هو موضّح هنا.

حلّ النزاعات

في التنفيذ الحالي لواجهة برمجة التطبيقات لطلبات الويب، يُعدّ الطلب ملغيًا إذا طلبت إضافة واحدة على الأقل إلغاء الطلب. إذا ألغت إضافة طلبًا، سيتم إشعار جميع الإضافات من خلال حدث onErrorOccurred. يمكن لإضافة واحدة فقط إعادة توجيه طلب أو تعديل عنوان في كل مرة. إذا حاولت أكثر من إضافة تعديل الطلب، ستنجح الإضافة التي تم تثبيتها مؤخرًا، وسيتم تجاهل جميع الإضافات الأخرى. لا يتم إشعار الإضافة إذا تم تجاهل تعليماتها بتعديل المحتوى أو إعادة توجيهه.

التخزين المؤقت

يستخدم Chrome نوعَين من ذاكرة التخزين المؤقت: ذاكرة تخزين مؤقت على القرص وذاكرة تخزين مؤقت سريعة جدًا في الذاكرة. ترتبط مدة بقاء ذاكرة التخزين المؤقت داخل الذاكرة بمدة بقاء عملية العرض، والتي تتوافق تقريبًا مع علامة تبويب. لا يمكن لواجهة برمجة التطبيقات لطلبات الويب رصد الطلبات التي يتم الردّ عليها من ذاكرة التخزين المؤقت داخل الجهاز. إذا غيّر معالج الطلبات سلوكه (على سبيل المثال، السلوك الذي يتم بموجبه حظر الطلبات)، قد لا يتم تطبيق هذا السلوك المتغيّر عند إعادة تحميل الصفحة ببساطة. لضمان تطبيق التغيير في السلوك، اتّصِل بالدالة handlerBehaviorChanged() لإفراغ ذاكرة التخزين المؤقت. ولكن لا تفعل ذلك كثيرًا لأنّ إفراغ ذاكرة التخزين المؤقت عملية مكلفة جدًا. لست بحاجة إلى استدعاء handlerBehaviorChanged() بعد تسجيل متتبِّع الأحداث أو إلغاء تسجيله.

الطوابع الزمنية

لا يمكن ضمان اتّساق قيمة السمة timestamp لأحداث طلبات الويب إلا داخليًا. ستمنحك مقارنة حدث بحدث آخر الإزاحة الصحيحة بينهما، ولكن مقارنتهما بالوقت الحالي داخل الإضافة (من خلال (new Date()).getTime() مثلاً) قد تؤدي إلى نتائج غير متوقّعة.

معالجة الأخطاء

إذا حاولت تسجيل حدث باستخدام وسيطات غير صالحة، سيحدث خطأ في JavaScript، ولن يتم تسجيل معالج الحدث. إذا حدث خطأ أثناء معالجة حدث أو إذا عرض معالج الأحداث استجابة حظر غير صالحة، سيتم تسجيل رسالة خطأ في وحدة تحكّم الإضافة، وسيتم تجاهل المعالج لهذا الطلب.

أمثلة

يوضّح المثال التالي كيفية حظر جميع الطلبات إلى www.evil.com:

chrome.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

بما أنّ هذه الدالة تستخدم معالج أحداث حظر، فإنّها تتطلّب الإذن "webRequest" بالإضافة إلى الإذن "webRequestBlocking" في ملف البيان.

يحقّق المثال التالي الهدف نفسه بطريقة أكثر فعالية لأنّه لا حاجة إلى تمرير الطلبات غير المستهدِفة www.evil.com إلى الإضافة:

chrome.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

يوضّح المثال التالي كيفية حذف عنوان User-Agent من جميع الطلبات:

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

لتجربة واجهة برمجة التطبيقات chrome.webRequest، ثبِّت عينة webRequest من مستودع chrome-extension-samples.

الأنواع

BlockingResponse

تعرض هذه السمة قيمة لمعالجات الأحداث التي تم تطبيق extraInfoSpec عليها باستخدام القيمة "blocking". تسمح لمعالج الأحداث بتعديل طلبات الشبكة.

الخصائص

  • authCredentials

    كائن اختياري

    يتم استخدامها فقط كردّ على الحدث onAuthRequired. في حال ضبطها، يتم تقديم الطلب باستخدام بيانات الاعتماد المقدَّمة.

    • كلمة المرور

      سلسلة

    • اسم المستخدم

      سلسلة

  • إلغاء

    boolean اختياري

    إذا كانت القيمة صحيحة، يتم إلغاء الطلب. يمنع ذلك إرسال الطلب. يمكن استخدام هذا النوع من الاستجابات للردّ على الأحداث onBeforeRequest وonBeforeSendHeaders وonHeadersReceived وonAuthRequired.

  • redirectUrl

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

    يتم استخدامها فقط كردّ على الحدثَين onBeforeRequest وonHeadersReceived. في حال ضبط هذا الحقل، يتم منع إرسال الطلب الأصلي أو إكماله، ويتم بدلاً من ذلك إعادة توجيهه إلى عنوان URL المحدّد. يُسمح بعمليات إعادة التوجيه إلى مخطّطات غير HTTP، مثل data:. تستخدم عمليات إعادة التوجيه التي يتم بدؤها من خلال إجراء إعادة توجيه طريقة الطلب الأصلية لإعادة التوجيه، باستثناء حالة واحدة: إذا تم بدء عملية إعادة التوجيه في مرحلة onHeadersReceived، سيتم إصدار عملية إعادة التوجيه باستخدام طريقة GET. يتم تجاهل عمليات إعادة التوجيه من عناوين URL التي تتضمّن المخططَين ws:// وwss://.

  • requestHeaders

    ‫HttpHeaders اختيارية

    يُستخدَم فقط كردّ على الحدث onBeforeSendHeaders. في حال ضبطها، يتم تقديم الطلب باستخدام عناوين الطلبات هذه بدلاً من ذلك.

  • responseHeaders

    ‫HttpHeaders اختيارية

    يتم استخدامها فقط كردّ على الحدث onHeadersReceived. في حال ضبطها، يُفترض أنّ الخادم قد استجاب باستخدام عناوين الاستجابة هذه بدلاً من ذلك. لا تعرض القيمة responseHeaders إلا إذا كنت تريد تعديل العناوين للحدّ من عدد التعارضات (يمكن لإضافة واحدة فقط تعديل responseHeaders لكل طلب).

FormDataItem

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

يحتوي على البيانات التي تم تمريرها ضمن بيانات النموذج. بالنسبة إلى النموذج المشفر بعنوان URL، يتم تخزينه كسلسلة إذا كانت البيانات سلسلة UTF-8، وكـ ArrayBuffer في الحالات الأخرى. بالنسبة إلى form-data، يكون ArrayBuffer. إذا كانت form-data تمثّل تحميل ملف، تكون سلسلة تتضمّن اسم الملف، إذا تم توفير اسم الملف.

تعداد

ArrayBuffer

سلسلة

HttpHeaders

مصفوفة من عناوين HTTP يتم تمثيل كل عنوان كقاموس يحتوي على المفتاحين name وvalue أو binaryValue.

النوع

object[]

الخصائص

  • binaryValue

    number[] اختيارية

    قيمة عنوان HTTP إذا كان لا يمكن تمثيله باستخدام UTF-8، ويتم تخزينه كقيم بايت فردية (0..255).

  • الاسم

    سلسلة

    اسم عنوان HTTP

  • القيمة

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

    قيمة عنوان HTTP إذا كان يمكن تمثيله بترميز UTF-8

IgnoredActionType

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

تعداد

"redirect"

"request_headers"

"response_headers"

"auth_credentials"

OnAuthRequiredOptions

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

تعداد

‫"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

"blocking"
تحدّد ما إذا كان الطلب محظورًا إلى أن تعرض دالة ردّ الاتصال.

"asyncBlocking"
تحدّد هذه السمة أنّه يتم التعامل مع دالّة ردّ الاتصال بشكل غير متزامن.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

OnBeforeRedirectOptions

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

تعداد

‫"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

OnBeforeRequestOptions

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

تعداد

"blocking"
تحدّد ما إذا كان الطلب محظورًا إلى أن تعرض دالة ردّ الاتصال.

"requestBody"
تحدّد هذه السمة أنّه يجب تضمين نص الطلب في الحدث.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

OnBeforeSendHeadersOptions

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

تعداد

"requestHeaders"
تحدّد هذه السمة أنّه يجب تضمين عنوان الطلب في الحدث.

"blocking"
تحدّد ما إذا كان الطلب محظورًا إلى أن تعرض دالة ردّ الاتصال.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

OnCompletedOptions

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

تعداد

‫"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

OnErrorOccurredOptions

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

القيمة

"extraHeaders"

OnHeadersReceivedOptions

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

تعداد

"blocking"
تحدّد ما إذا كان الطلب محظورًا إلى أن تعرض دالة ردّ الاتصال.

‫"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

"securityInfo"
تحدّد هذه السمة أنّه يجب تضمين SecurityInfo في الحدث.

"securityInfoRawDer"
تحدّد هذه السمة أنّه يجب تضمين SecurityInfo مع وحدات البايت الأولية للشهادات في الحدث.

OnResponseStartedOptions

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

تعداد

‫"responseHeaders"
تحدّد ما إذا كان يجب تضمين عناوين الاستجابة في الحدث.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

OnSendHeadersOptions

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

تعداد

"requestHeaders"
تحدّد هذه السمة أنّه يجب تضمين عنوان الطلب في الحدث.

extraHeaders
يحدّد هذا الحقل أنّ العناوين يمكن أن تنتهك سياسة مشاركة المراجع مع نطاقات خارجية (CORS).

RequestFilter

تمثّل هذه السمة عنصرًا يصف الفلاتر التي سيتم تطبيقها على أحداث webRequest.

الخصائص

  • tabId

    number اختياري

  • الأنواع

    ‫ResourceType[] اختيارية

    قائمة بأنواع الطلبات سيتم استبعاد الطلبات التي لا تتطابق مع أي من الأنواع.

  • عناوين url

    string[]

    قائمة بعناوين URL أو أنماط عناوين URL سيتم استبعاد الطلبات التي لا يمكن أن تتطابق مع أي من عناوين URL.

  • windowId

    number اختياري

ResourceType

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

تعداد

"main_frame"
تحدّد هذه القيمة أنّ المورد هو الإطار الرئيسي.

‫"sub_frame"
تحدّد هذه السمة أنّ المرجع هو إطار فرعي.

"stylesheet"
تحدّد هذه السمة المورد على أنّه ورقة أنماط.

"script"
تحدّد هذه السمة المورد على أنّه نص برمجي.

"image"
تحدّد هذه السمة أنّ المورد هو صورة.

"font"
تحدّد هذه السمة أنّ المورد هو خط.

"object"
تحدّد هذه السمة المورد كعنصر.

"xmlhttprequest"
تحدّد هذه السمة المورد على أنّه XMLHttpRequest.

"ping"
تحدّد المورد على أنّه إشارة.

‫"csp_report"
تحدّد هذه السمة المورد كتقرير "سياسة أمان المحتوى" (CSP).

"media"
تحدّد هذه السمة المرجع كمادة عرض وسائط.

"websocket"
تحدّد هذه السمة المورد على أنّه WebSocket.

"webbundle"
تحدّد هذه القيمة أنّ المورد هو WebBundle.

other
تحدّد هذه القيمة المورد كنوع غير مضمّن في الأنواع المدرَجة.

SecurityInfo

Chrome 144+

الخصائص

  • الشهادات

    object[]

    قائمة بالشهادات

    • بصمة الإصبع

      عنصر

      تمثّل هذه السمة الملفات المرجعية للشهادة.

      • sha256

        سلسلة

        الملف المرجعي لمعيار SHA256 الخاص بالشهادة

    • rawDER

      ‫ArrayBuffer اختياري

      وحدات البايت الأولية لشهادة الخادم بترميز DER

  • الولاية

    سلسلة

    حالة الاتصال إحدى القيم التالية: آمن أو غير آمن أو معطّل

UploadData

يحتوي على البيانات التي تم تحميلها في طلب عنوان URL.

الخصائص

  • بايت

    أي اختياري

    ‫ArrayBuffer يحتوي على نسخة من البيانات

  • ملف واحد

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

    سلسلة تتضمّن مسار الملف واسمه

الخصائص

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

الحدّ الأقصى لعدد المرات التي يمكن فيها استدعاء handlerBehaviorChanged لكل فاصل زمني مستمر مدته 10 دقائق ‫handlerBehaviorChanged هي استدعاء دالة مكلف لا يجب استدعاؤه بشكل متكرر.

القيمة

‫20

الطُرق

handlerBehaviorChanged()

وعد 
chrome.webRequest.handlerBehaviorChanged(
  callback?: function,
): Promise<void>

يجب استدعاء هذه الدالة عند تغيير سلوك معالِجات webRequest لمنع المعالجة غير الصحيحة بسبب التخزين المؤقت. استدعاء هذه الدالة مكلف. لا تستدعِ هذه الدالة كثيرًا.

المعلمات

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

الفعاليات

onActionIgnored

الإصدار 70 من Chrome والإصدارات الأحدث 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عندما يتم تجاهل التعديل المقترح الذي أجرته إحدى الإضافات على طلب شبكة. يحدث ذلك في حال حدوث تعارضات مع إضافات أخرى.

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • إجراء

        IgnoredActionType

        الإجراء المقترَح الذي تم تجاهله

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

onAuthRequired

chrome.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

يتم تنشيط هذا الحدث عند تلقّي خطأ في المصادقة. لدى المستمع ثلاثة خيارات: يمكنه تقديم بيانات اعتماد المصادقة، أو إلغاء الطلب وعرض صفحة الخطأ، أو عدم اتّخاذ أي إجراء بشأن التحدّي. في حال تقديم بيانات اعتماد غير صالحة للمستخدم، قد يتم استدعاء هذه الدالة عدة مرات للطلب نفسه. يُرجى العِلم أنّه يجب تحديد وضع واحد فقط من الوضعَين 'blocking' أو 'asyncBlocking' في المَعلمة extraInfoSpec.

المعلمات

  • callback

    دالة

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

    (details: object, asyncCallback?: function) => BlockingResponse | undefined

    • التفاصيل

      عنصر

      • المنافس

        عنصر

        الخادم الذي يطلب المصادقة

        • مضيف

          سلسلة

        • المنفذ

          الرقم

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • isProxy

        قيمة منطقية

        القيمة هي "صحيح" بالنسبة إلى Proxy-Authenticate، و"خطأ" بالنسبة إلى WWW-Authenticate.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • realm

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

        نطاق المصادقة الذي يوفّره الخادم، إذا كان متوفّرًا

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • responseHeaders

        ‫HttpHeaders اختيارية

        تمثّل هذه السمة عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة.

      • المخطط

        سلسلة

        نظام المصادقة، مثل Basic أو Digest

      • statusCode

        الرقم

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

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP الخاص بالردّ أو السلسلة "HTTP/0.9 200 OK" للردود التي تستخدم HTTP/0.9 (أي الردود التي لا تتضمّن سطر حالة) أو سلسلة فارغة إذا لم تكن هناك عناوين.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • asyncCallback

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

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

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

      (response: BlockingResponse) => void

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن يعرض متتبِّع الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnAuthRequiredOptions[] اختيارية

onBeforeRedirect

chrome.webRequest.onBeforeRedirect.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRedirectOptions[],
)

يتم تنشيط هذا الحدث عندما توشك عملية إعادة توجيه من الخادم على الحدوث.

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        توضّح ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت للقرص.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • redirectUrl

        سلسلة

        عنوان URL الجديد

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • responseHeaders

        ‫HttpHeaders اختيارية

        عناوين استجابة HTTP التي تم تلقّيها مع عملية إعادة التوجيه هذه

      • statusCode

        الرقم

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP الخاص بالردّ أو السلسلة "HTTP/0.9 200 OK" للردود التي تستخدم HTTP/0.9 (أي الردود التي لا تتضمّن سطر حالة) أو سلسلة فارغة إذا لم تكن هناك عناوين.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnBeforeRedirectOptions[] اختيارية

onBeforeRequest

chrome.webRequest.onBeforeRequest.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRequestOptions[],
)

يتم تنشيط هذا الحدث عندما يكون على وشك حدوث طلب.

المعلمات

  • callback

    دالة

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

    (details: object) => BlockingResponse | undefined

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب.

      • documentLifecycle

        extensionTypes.DocumentLifecycle اختياري

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

      • frameType

        extensionTypes.FrameType اختيارية

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

        نوع الإطار الذي تم فيه الطلب.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestBody

        كائن اختياري

        يحتوي على بيانات نص طلب HTTP. يتم توفيرها فقط إذا كان extraInfoSpec يحتوي على "requestBody".

        • خطأ

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

          أخطاء عند الحصول على بيانات نص الطلب

        • formData

          كائن اختياري

          إذا كانت طريقة الطلب هي POST وكان النص عبارة عن سلسلة من أزواج المفتاح/القيمة مرمّزة بترميز UTF8، أو مرمّزة كبيانات متعددة الأجزاء/نموذج، أو application/x-www-form-urlencoded، يكون هذا القاموس متوفّرًا ويحتوي كل مفتاح على قائمة بجميع قيم هذا المفتاح. إذا كانت البيانات من نوع وسائط آخر أو إذا كانت غير صالحة، لن يكون القاموس متوفّرًا. مثال على قيمة هذا القاموس هو {'key': ['value1', 'value2']}.

        • raw

          ‫UploadData[] اختيارية

          إذا كانت طريقة الطلب هي PUT أو POST، ولم يتم تحليل النص الأساسي في formData، سيحتوي هذا الصفيف على عناصر نص الطلب غير المحلَّلة.

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن يعرض متتبِّع الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnBeforeRequestOptions[] اختيارية

onBeforeSendHeaders

chrome.webRequest.onBeforeSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeSendHeadersOptions[],
)

يتم تنشيط هذا الحدث قبل إرسال طلب HTTP، وذلك بعد توفّر عناوين الطلب. قد يحدث ذلك بعد إنشاء اتصال TCP بالخادم، ولكن قبل إرسال أي بيانات HTTP.

المعلمات

  • callback

    دالة

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

    (details: object) => BlockingResponse | undefined

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestHeaders

        ‫HttpHeaders اختيارية

        عناوين طلب HTTP التي سيتم إرسالها مع هذا الطلب

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن يعرض متتبِّع الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] اختيارية

onCompleted

chrome.webRequest.onCompleted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnCompletedOptions[],
)

يتم تنشيط هذا الحدث عند اكتمال الطلب.

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        توضّح ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت للقرص.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • responseHeaders

        ‫HttpHeaders اختيارية

        تمثّل هذه السمة عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة.

      • statusCode

        الرقم

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP الخاص بالردّ أو السلسلة "HTTP/0.9 200 OK" للردود التي تستخدم HTTP/0.9 (أي الردود التي لا تتضمّن سطر حالة) أو سلسلة فارغة إذا لم تكن هناك عناوين.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnCompletedOptions[] اختياري

onErrorOccurred

chrome.webRequest.onErrorOccurred.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnErrorOccurredOptions[],
)

يتم تنشيط هذا الحدث عند حدوث خطأ.

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب لا تظهر هذه القيمة إذا كان الطلب عبارة عن عملية تنقّل في إطار.

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

        دورة الحياة التي يكون فيها المستند

      • خطأ

        سلسلة

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

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        توضّح ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت للقرص.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnErrorOccurredOptions[] اختياري

onHeadersReceived

chrome.webRequest.onHeadersReceived.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnHeadersReceivedOptions[],
)

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

المعلمات

  • callback

    دالة

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

    (details: object) => BlockingResponse | undefined

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • responseHeaders

        ‫HttpHeaders اختيارية

        تمثّل هذه السمة عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة.

      • securityInfo

        ‫SecurityInfo اختيارية

        Chrome 144+

        معلومات عن اتصال TLS/QUIC المستخدَم في الاتصال الأساسي يتم توفيرها فقط إذا تم تحديد securityInfo في المَعلمة extraInfoSpec.

      • statusCode

        الرقم

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

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP للاستجابة أو السلسلة "HTTP/0.9 200 OK" للاستجابات التي تستخدم HTTP/0.9 (أي الاستجابات التي لا تتضمّن سطر حالة)

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

    • returns

      BlockingResponse | undefined

      إذا تم تحديد "blocking" في المَعلمة "extraInfoSpec"، يجب أن يعرض متتبِّع الأحداث عنصرًا من هذا النوع.

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnHeadersReceivedOptions[] اختيارية

onResponseStarted

chrome.webRequest.onResponseStarted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnResponseStartedOptions[],
)

يتم تنشيط هذا الحدث عند تلقّي البايت الأول من نص الردّ. بالنسبة إلى طلبات HTTP، يعني ذلك أنّ سطر الحالة وعناوين الاستجابة متوفّران.

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • fromCache

        قيمة منطقية

        توضّح ما إذا تم جلب هذه الاستجابة من ذاكرة التخزين المؤقت للقرص.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • ip

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

        عنوان IP للخادم الذي تم إرسال الطلب إليه فعليًا يُرجى العِلم أنّه قد يكون عنوان IPv6 حرفيًا.

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • responseHeaders

        ‫HttpHeaders اختيارية

        تمثّل هذه السمة عناوين استجابة HTTP التي تم تلقّيها مع هذه الاستجابة.

      • statusCode

        الرقم

        رمز حالة HTTP العادي الذي يعرضه الخادم.

      • statusLine

        سلسلة

        سطر حالة HTTP الخاص بالردّ أو السلسلة "HTTP/0.9 200 OK" للردود التي تستخدم HTTP/0.9 (أي الردود التي لا تتضمّن سطر حالة) أو سلسلة فارغة إذا لم تكن هناك عناوين.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnResponseStartedOptions[] اختياري

onSendHeaders

chrome.webRequest.onSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnSendHeadersOptions[],
)

يتم تنشيط هذا الحدث قبل إرسال طلب إلى الخادم مباشرةً (تكون التعديلات على عمليات معاودة الاتصال السابقة onBeforeSendHeaders مرئية عند تنشيط onSendHeaders).

المعلمات

  • callback

    دالة

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

    (details: object) => void

    • التفاصيل

      عنصر

      • documentId

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

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

        المعرّف الفريد العالمي (UUID) للمستند الذي يقدّم الطلب

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

        دورة الحياة التي يكون فيها المستند

      • frameId

        الرقم

        تشير القيمة 0 إلى أنّ الطلب يحدث في الإطار الرئيسي، وتشير القيمة الموجبة إلى رقم تعريف إطار فرعي يحدث فيه الطلب. في حال تحميل مستند لإطار (فرعي)، أي إذا كانت قيمة type هي main_frame أو sub_frame، يشير frameId إلى رقم تعريف هذا الإطار، وليس رقم تعريف الإطار الخارجي. تكون معرّفات الإطارات فريدة داخل علامة تبويب.

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

        نوع الإطار الذي تم فيه الطلب.

      • المستخدم

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

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

        المصدر الذي بدأ منه الطلب ولا يتغيّر ذلك من خلال عمليات إعادة التوجيه. إذا كان هذا المصدر غير شفاف، سيتم استخدام السلسلة "null".

      • method

        سلسلة

        طريقة HTTP عادية

      • parentDocumentId

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

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

        تمثّل هذه السمة المعرّف الفريد العالمي (UUID) للمستند الرئيسي الذي يملك هذا الإطار. لا يتم ضبط هذه السمة إذا لم يكن هناك موقع رئيسي.

      • parentFrameId

        الرقم

        معرّف الإطار الذي يغلّف الإطار الذي أرسل الطلب. يتم ضبط القيمة على -1 في حال عدم توفّر إطار رئيسي.

      • requestHeaders

        ‫HttpHeaders اختيارية

        عناوين طلب HTTP التي تم إرسالها مع هذا الطلب

      • requestId

        سلسلة

        معرّف الطلب. تكون أرقام تعريف الطلبات فريدة ضمن جلسة المتصفّح. نتيجةً لذلك، يمكن استخدامها لربط أحداث مختلفة من الطلب نفسه.

      • tabId

        الرقم

        رقم تعريف علامة التبويب التي يتم فيها تنفيذ الطلب اضبط القيمة على -1 إذا لم يكن الطلب مرتبطًا بعلامة تبويب.

      • timeStamp

        الرقم

        الوقت الذي يتم فيه تشغيل هذه الإشارة، بالملّي ثانية منذ بداية الحقبة

      • النوع

        ResourceType

        توضّح هذه السمة طريقة استخدام المورد المطلوب.

      • url

        سلسلة

  • تصفية

    RequestFilter

  • extraInfoSpec

    OnSendHeadersOptions[] اختياري