chrome.declarativeNetRequest

الوصف

تُستخدَم واجهة برمجة التطبيقات chrome.declarativeNetRequest لحظر طلبات الشبكة أو تعديلها من خلال تحديد قواعد وصفية. يتيح ذلك للإضافة تعديل طلبات الشبكة بدون اعتراضها وعرض محتواها، ما يضمن المزيد من الخصوصية.

الأذونات

declarativeNetRequest
declarativeNetRequestWithHostAccess

يقدّم إذنَا "declarativeNetRequest" و "declarativeNetRequestWithHostAccess" الإمكانات نفسها. وتختلف هذه الأذونات عن بعضها في وقت طلبها أو منحها.

"declarativeNetRequest"
يؤدي إلى ظهور تحذير بشأن الأذونات في وقت التثبيت، ولكنه يمنح إذن وصول ضمنيًا إلى قواعد allow وallowAllRequests وblock. استخدِم هذا الإجراء متى أمكن لتجنُّب الحاجة إلى طلب إذن الوصول الكامل إلى المضيفين.
"declarativeNetRequestFeedback"
تفعيل ميزات تصحيح الأخطاء للإضافات غير المُنزَّلة، وتحديدًا getMatchedRules() وonRuleMatchedDebug
"declarativeNetRequestWithHostAccess"
لا يتم عرض تحذير بشأن الأذونات في وقت التثبيت، ولكن عليك طلب أذونات المضيف قبل أن تتمكّن من تنفيذ أي إجراء على مضيف. يكون هذا الإجراء مناسبًا عندما تريد استخدام قواعد طلب الشبكة التعريفية في إضافة لديها أذونات مضيف بدون إنشاء تحذيرات إضافية.

مدى التوفّر

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

البيان

بالإضافة إلى الأذونات الموضّحة سابقًا، تتطلّب أنواع معيّنة من قواعد المجموعات، وقواعد المجموعات الثابتة على وجه التحديد، الإفصاح عن مفتاح البيان "declarative_net_request"، والذي يجب أن يكون قاموسًا يتضمّن مفتاحًا واحدًا يُسمّى "rule_resources". هذا المفتاح هو صفيف يحتوي على قواميس من النوع Ruleset، كما هو موضّح في ما يلي. (يُرجى العلم أنّ الاسم "مجموعة القواعد" لا يظهر في ملف البيان بتنسيق JSON لأنّه مجرد مصفوفة). يتم شرح قواعد القواعد الثابتة لاحقًا في هذا المستند.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

القواعد وقواعد المجموعات

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

  • حظر طلب شبكة
  • ترقية المخطط (من http إلى https)
  • يمكنك منع حظر طلب معيّن من خلال إلغاء أي قواعد محظورة مطابقة.
  • إعادة توجيه طلب شبكة
  • تعديل عناوين الطلبات أو الاستجابات

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

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

قواعد القواعد الديناميكية وعلى مستوى الجلسة

تتم إدارة قواعد الجلسات والقواعد الديناميكية باستخدام JavaScript أثناء استخدام إحدى الإضافات.

  • تظل القواعد الديناميكية محفوظة في جميع جلسات المتصفّح وعمليات ترقية الإضافات.
  • يتم محو قواعد الجلسات عند إغلاق المتصفّح وعند تثبيت إصدار جديد من الإضافة.

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

قواعد القواعد الثابتة

على عكس القواعد الديناميكية وقواعد الجلسات، يتم تجميع القواعد الثابتة وتثبيتها وتحديثها عند تثبيت إضافة أو ترقيتها. ويتم تخزينها في ملفات القواعد بتنسيق JSON، والتي يتم الإشارة إليها في الإضافة باستخدام مفتاحَي "declarative_net_request" و"rule_resources" على النحو الموضّح أعلاه، بالإضافة إلى قاموس واحد أو أكثر من قواميس Ruleset. يحتوي معجم Ruleset على مسار إلى ملف القاعدة ورقم تعريف لقاعدة القواعد الواردة في الملف وما إذا كانت قاعدة القواعد مفعَّلة أو غير مفعَّلة. ويكون العنصران الأخيران مهمّين عند تفعيل مجموعة قواعد أو إيقافها آليًا.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

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

المراجعة السريعة

قد تكون التغييرات على قواعد القواعد الثابتة مؤهَّلة للمراجعة السريعة. اطّلِع على المراجعة السريعة للتغييرات المؤهَّلة.

تفعيل القواعد الثابتة وقواعد المجموعات وإيقافها

يمكن تفعيل القواعد الثابتة الفردية وقواعد القواعد الثابتة الكاملة أو إيقافها أثناء التشغيل.

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

لأسباب تتعلّق بالأداء، هناك أيضًا حدود لعدد القواعد وقواعد القواعد التي يمكن تفعيلها في الوقت نفسه. يُرجى الاتصال على getAvailableStaticRuleCount() للتحقّق من عدد القواعد الإضافية التي قد تكون مفعّلة. للحصول على معلومات عن حدود القواعد، يُرجى الاطّلاع على حدود القواعد.

لتفعيل القواعد الثابتة أو إيقافها، اتصل بالرقم updateStaticRules(). تأخذ هذه الطريقة عنصر UpdateStaticRulesOptions الذي يحتوي على صفائف من أرقام تعريف القواعد المطلوب تفعيلها أو إيقافها. يتم تحديد أرقام التعريف باستخدام مفتاح "id" في قاموس Ruleset. الحد الأقصى المسموح به هو 5,000 قاعدة ثابتة غير مفعّلة.

لتفعيل مجموعات القواعد الثابتة أو إيقافها، اتصل بالرقم updateEnabledRulesets(). تأخذ هذه الطريقة عنصر UpdateRulesetOptions الذي يحتوي على مصفوفات أرقام تعريف قواعد القواعد لتفعيلها أو إيقافها. يتم تحديد أرقام التعريف باستخدام مفتاح "id" في قاموس Ruleset.

قواعد الإنشاء

بغض النظر عن النوع، تبدأ القاعدة بأربعة حقول كما هو موضّح في ما يلي. في حين أنّ المفتاحَين "id" و"priority" يقبلان رقمًا، قد يوفّر المفتاحان "action" و"condition" عدّة شروط لحظر المحتوى وإعادة توجيهه. تحظر القاعدة التالية جميع طلبات النصوص البرمجية الواردة من "foo.com" إلى أي عنوان URL يتضمّن "abc" كسلسلة فرعية.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

مطابقة عناوين URL

يوفّر أسلوب "طلب الشبكة التعريفي" إمكانية مطابقة عناوين URL باستخدام بنية مطابقة للنمط أو تعبيرات عادية.

بنية فلتر عنوان URL

يسمح مفتاح "condition" للقاعدة بمفتاح "urlFilter" لتنفيذ إجراءات بشأن عناوين URL ضمن نطاق محدّد. يمكنك إنشاء أنماط باستخدام الرموز المخصّصة لمطابقة الأنماط. وفي ما يلي بعض الأمثلة.

urlFilter المطابقات لا يطابق
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz
https://a.example.company		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

التعبيرات العادية

يمكن أن تستخدم الشروط أيضًا تعبيرات عادية. اطّلِع على مفتاح "regexFilter". للتعرّف على الحدود التي تنطبق على هذه الشروط، يُرجى الاطّلاع على القواعد التي تستخدِم التعبيرات العادية.

كتابة شروط عناوين URL جيدة

احرِص عند كتابة القواعد على مطابقة نطاق كامل دائمًا. وإلا، قد يتطابق القاعدة في مواقف غير متوقّعة. على سبيل المثال، عند استخدام بنية مطابقة الأنماط:

  • يتطابق google.com بشكل غير صحيح مع https://example.com/?param=google.com
  • يتطابق ||google.com بشكل غير صحيح مع https://google.company
  • يتطابق https://www.google.com بشكل غير صحيح مع https://example.com/?param=https://www.google.com

ننصحك باستخدام:

  • ||google.com/، الذي يتطابق مع جميع المسارات وجميع النطاقات الفرعية
  • |https://www.google.com/ الذي يتطابق مع جميع المسارات وليس مع النطاقات الفرعية

وبالمثل، استخدِم الحرفَين ^ و/ لتثبيت تعبير عادي. على سبيل المثال، يتطابق ^https:\/\/www\.google\.com\/ مع أي مسار على https://www.google.com.

تقييم القاعدة

يطبّق المتصفّح قواعد DNR على مدار مراحل مختلفة من دورة طلب الشبكة.

قبل تقديم الطلب

قبل تقديم طلب، يمكن أن تحظر إحدى الإضافات الطلب أو إعادة توجيهه (بما في ذلك ترقية المخطط من HTTP إلى HTTPS) باستخدام قاعدة مطابقة.

يحدِّد المتصفّح قائمة بالقواعد المطابقة لكل إضافة. لا يتم تضمين القواعد التي تتضمّن إجراء modifyHeaders هنا لأنّه سيتم التعامل معها لاحقًا. بالإضافة إلى ذلك، سيتمّ النظر في القواعد التي تتضمّن شرط responseHeaders لاحقًا (عندما تتوفّر رؤوس الاستجابة) ولن يتمّ تضمينها.

بعد ذلك، يختار Chrome مرشحًا واحدًا بحد أقصى لكل طلب لكل إضافة. يعثر Chrome على قاعدة مطابقة من خلال ترتيب جميع القواعد المطابقة حسب الأولوية. يتم ترتيب القواعد التي لها الأولوية نفسها حسب الإجراء (allow أو allowAllRequests > block > upgradeScheme > redirect).

إذا كان المرشح هو قاعدة allow أو allowAllRequests، أو إذا كان الإطار الذي يتم تقديم الطلب فيه قد تطابق سابقًا مع قاعدة allowAllRequests ذات أولوية أعلى أو مساوية من هذه الإضافة، يكون الطلب "مسموحًا به" ولن يكون للإضافة أي تأثير على الطلب.

إذا أرادت أكثر من إضافة واحدة حظر هذا الطلب أو إعادة توجيهه، يتم اختيار إجراء واحد اتّخاذه. وينفّذ Chrome ذلك من خلال ترتيب القواعد بالترتيب block > redirect أو upgradeScheme > allow أو allowAllRequests. إذا كانت القاعدتان من النوع نفسه، يختار Chrome القاعدة من الإضافة التي تم تثبيتها مؤخرًا.

قبل إرسال رؤوس الطلبات

قبل أن يرسل Chrome رؤوس الطلبات إلى الخادم، يتم تعديلها استنادًا إلى مطابقة قواعد modifyHeaders.

ضمن إضافة واحدة، ينشئ Chrome قائمة التعديلات التي يجب إجراؤها من خلال العثور على جميع قواعد modifyHeaders المطابقة. كما في السابق، لا يتم تضمين سوى القواعد التي لها أولوية أعلى من أي قواعد allow أو allowAllRequests مطابقة.

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

  • إذا تم إلحاق قاعدة برأس، لا يمكن إلحاق القواعد ذات الأولوية الأدنى بهذا الرأس إلا. لا يُسمح بعمليات الضبط والإزالة.
  • إذا كانت القاعدة تضبط عنوانًا، لا يمكن إلحاق سوى القواعد ذات الأولوية الأقل من الإضافة نفسها بهذا العنوان. ولا يُسمح بإجراء أي تعديلات أخرى.
  • إذا أزالت إحدى القواعد عنوانًا، لا يمكن للقواعد ذات الأولوية الأقل تعديل العنوان بعد ذلك.

بعد تلقّي ردّ

بعد تلقّي عناوين الاستجابة، يُقيّم Chrome القواعد باستخدام شرط responseHeaders.

بعد ترتيب هذه القواعد حسب action وpriority واستبعاد أي قواعد أصبحت زائدة عن الحاجة بسبب تطابق قاعدة allow أو allowAllRequests (يحدث ذلك بالطريقة نفسها المتّبعة في الخطوات الواردة في قسم "قبل تقديم الطلب")، قد يحظر Chrome الطلب أو يعيد توجيهه نيابةً عن إحدى الإضافات.

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

في حال تطبيق قاعدة حظر، تتعامل الصفحة التي قدّمت الطلب مع الاستجابة المحظورة ويُنهي Chrome الطلب مبكرًا. في حال تطبيق قاعدة إعادة توجيه، يُرسل Chrome طلبًا جديدًا إلى عنوان URL المُعاد التوجيه إليه. احرص على مراعاة ما إذا كانت هذه السلوكيات تستوفي توقعات الخصوصية لملحقك.

إذا لم يتم حظر الطلب أو إعادة توجيهه، يطبّق Chrome أي قواعد modifyHeaders. يتم تطبيق التعديلات على عناوين الاستجابة بالطريقة نفسها الموضّحة في القسم "قبل إرسال عناوين الطلبات". لا يؤدي تطبيق التعديلات على عناوين الطلبات إلى أيّ تأثير، لأنّه سبق أن تم تقديم الطلب.

القواعد الآمنة

يتم تعريف القواعد الآمنة على أنّها قواعد تتضمّن إجراءً من block أو allow أو allowAllRequests أو upgradeScheme. تخضع هذه القواعد لحصة متزايدة للقواعد الديناميكية.

حدود القواعد

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

القواعد الثابتة

القواعد الثابتة هي تلك المحدّدة في ملفات القواعد التي تم الإعلان عنها في ملف البيان. يمكن أن تحدِّد الإضافة ما يصل إلى 100 مجموعة قواعد ثابتة كجزء من مفتاح بيان "rule_resources"، ولكن يمكن تفعيل 50 مجموعة قواعد فقط في المرة الواحدة. ويُطلق على هذا الأخير اسم MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. وتضمن هذه القواعد معًا 30,000 قاعدة على الأقل. ويُعرف هذا باسم GUARANTEED_MINIMUM_STATIC_RULES.

يعتمد عدد القواعد المتاحة بعد ذلك على عدد القواعد التي تم تفعيلها من خلال جميع الإضافات المثبّتة على متصفّح المستخدم. يمكنك العثور على هذا الرقم أثناء التشغيل من خلال الاتصال بالرقم getAvailableStaticRuleCount(). يمكنك الاطّلاع على مثال على ذلك ضمن أمثلة الرموز البرمجية.

قواعد الجلسات

يمكن أن تحتوي الإضافة على ما يصل إلى 5,000 قاعدة جلسة. ويتم عرض هذا الإجراء على أنّه MAX_NUMBER_OF_SESSION_RULES.

قبل الإصدار 120 من Chrome، كان الحد الأقصى المسموح به هو 5, 000 قاعدة ديناميكية وقاعدة جلسة مجتمعة.

القواعد الديناميكية

يمكن أن تحتوي الإضافة على 5,000 قاعدة ديناميكية على الأقل. ويتم عرض هذا الإجراء على أنّه MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

بدءًا من الإصدار 121 من Chrome، أصبح الحد الأقصى المسموح به للقواعد الديناميكية الآمنة هو 30,000 قاعدة، ويُشار إليها بالرمز MAX_NUMBER_OF_DYNAMIC_RULES. وستُحتسَب أيضًا أي قواعد غير آمنة تمّت إضافتها ضمن الحدّ الأقصى البالغ 5,000 قاعدة.

قبل الإصدار 120 من Chrome، كان الحد الأقصى المسموح به لقواعد الجلسات والقواعد الديناميكية هو 5, 000 قاعدة.

القواعد التي تستخدِم تعبيرات عادية

يمكن لجميع أنواع القواعد استخدام التعبيرات العادية، ولكن لا يمكن أن يتجاوز العدد الإجمالي لقواعد التعبيرات العادية من كل نوع 1000. يُطلَق على ذلك اسم MAX_NUMBER_OF_REGEX_RULES.

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

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

التفاعلات مع عمال الخدمات

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

المراجع المتوفّرة على الويب

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

تعديل العنوان

لا تتوفّر عملية الإضافة إلا للرؤوس التالية: accept وaccept-encoding وaccept-language وaccess-control-request-headers وcache-control وconnection وcontent-language وcookie وforwarded وif-match وif-none-match وkeep-alive وrange وte وtrailer وtransfer-encoding وupgrade وuser-agent وvia وwant-digest وx-forwarded-for.

أمثلة

أمثلة على الرموز البرمجية

تعديل القواعد الديناميكية

يوضّح المثال التالي كيفية الاتصال برقم updateDynamicRules(). وينطبق الإجراء نفسه على updateSessionRules().

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

تعديل قواعد المجموعات الثابتة

يوضّح المثال التالي كيفية تفعيل قواعد القواعد وإيقافها مع مراعاة عدد قواعد القواعد الثابتة المتاحة والحد الأقصى لعدد قواعد القواعد الثابتة المفعّلة. يمكنك إجراء ذلك عندما يكون عدد القواعد الثابتة التي تحتاج إليها أكبر من العدد المسموح به. لكي يعمل هذا الإجراء، يجب تثبيت بعض قواعد القواعد مع إيقاف بعض قواعد القواعد (ضبط "Enabled" على false في ملف البيان).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

أمثلة على القواعد

توضِّح الأمثلة التالية كيفية تحديد Chrome لأولويات القواعد في إحدى الإضافات. عند مراجعتها، قد تحتاج إلى فتح قواعد تحديد الأولوية في نافذة منفصلة.

مفتاح "الأولوية"

تتطلّب هذه الأمثلة إذن المضيف للوصول إلى *://*.example.com/*.

لتحديد أولوية عنوان URL معيّن، اطّلِع على مفتاح "priority" (الذي يحدّده المطوّر) ومفتاح "action" ومفتاح "urlFilter". تشير هذه الأمثلة إلى نموذج ملف القواعد المعروض أدناه.

الانتقال إلى https://google.com
تغطي قاعدتان عنوان URL هذا: القاعدتان اللتان تحملان الرقمَين التعريفيَّين 1 و4. يتم تطبيق القاعدة التي تحمل المعرّف 1 لأنّ إجراءات "block" لها أولوية أعلى من إجراءات "redirect". لا تنطبق القواعد المتبقية لأنّها مخصّصة لعناوين URL الأطول.
الانتقال إلى https://google.com/1234
بسبب عنوان URL الأطول، تتطابق الآن القاعدة التي تحمل رقم التعريف 2 مع القواعد التي تحمل رقمَي التعريف 1 و4. تنطبق القاعدة التي تحمل رقم التعريف 2 لأنّ "allow" لها أولوية أعلى من "block" و"redirect".
الانتقال إلى https://google.com/12345
تتطابق جميع القواعد الأربعة مع عنوان URL هذا. يتم تطبيق القاعدة التي تحمل رقم التعريف 3 لأنّ الأولوية التي حدّدها المطوّر هي الأعلى في المجموعة.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

عمليات إعادة التوجيه

يتطلّب المثال أدناه إذن المضيف للوصول إلى *://*.example.com/*.

يوضّح المثال التالي كيفية إعادة توجيه طلب من example.com إلى صفحة ضمن الإضافة نفسها. يُحلّ مسار الإضافة /a.jpg إلى chrome-extension://EXTENSION_ID/a.jpg، حيث يكون EXTENSION_ID هو معرّف الإضافة. لكي يعمل هذا الإجراء، يجب أن يُعرِّف البيان /a.jpg على أنّه مورد يمكن الوصول إليه من الويب.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

يستخدم العنوان التالي المفتاح "transform" لإعادة التوجيه إلى نطاق فرعي من example.com. ويستخدم علامة اسم نطاق ("||") لمنع الطلبات التي تستخدم أي مخطّط من example.com. ويحدّد المفتاح "scheme" في "transform" أنّ عمليات إعادة التوجيه إلى النطاق الفرعي ستستخدم دائمًا "https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com/",
    "resourceTypes": ["main_frame"]
  }
}

يستخدِم المثال التالي تعبيرات عادية لإعادة التوجيه من https://www.abc.xyz.com/path إلى https://abc.xyz.com/path. في مفتاح "regexFilter"، لاحظ كيفية تحويل النقط إلى أحرف خاصة وأنّ المجموعة التي تُحتسَب القيمة لها تختار إما "abc" أو "def". يحدّد مفتاح "regexSubstitution" أول مطابقة معروضة للتعبير العادي باستخدام "\1". في هذه الحالة، يتمّ تسجيل "abc" من عنوان URL المُعاد التوجيه إليه ويتمّ وضعه في عملية الاستبدال.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

العناوين

يزيل المثال التالي جميع ملفات تعريف الارتباط من كلّ من الإطار الرئيسي وأيّ إطارات فرعية.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

الأنواع

DomainType

يصف هذا الحقل ما إذا كان الطلب تابعًا لطرف أوّل أو ثالث في الإطار الذي نشأ منه. يُقال إنّ الطلب مقدَّم من طرف أول إذا كان لديه النطاق نفسه (eTLD+1) مثل الإطار الذي نشأ منه الطلب.

Enum

‫"firstParty"
طلب الشبكة هو جهة خارجية للإطار الذي نشأ منه.

‫"thirdParty"
طلب الشبكة تابع لجهة خارجية عن الإطار الذي نشأ منه.

ExtensionActionOptions

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

أماكن إقامة

  • displayActionCountAsBadgeText

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

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

  • tabUpdate

    ‫TabActionCountUpdate اختياري

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

    تفاصيل حول كيفية تعديل عدد الإجراءات في علامة التبويب

GetDisabledRuleIdsOptions

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

أماكن إقامة

  • rulesetId

    سلسلة

    المعرّف المقابل لعنصر Ruleset ثابت

GetRulesFilter

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

أماكن إقامة

  • ruleIds

    number[] اختيارية

    في حال تحديدها، يتم تضمين القواعد التي تتضمّن معرّفات مطابقة فقط.

HeaderInfo

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

أماكن إقامة

  • excludedValues

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

    في حال تحديد هذا الشرط، لا تتم مطابقته إذا كان العنوان متوفّرًا ولكن قيمته تحتوي على عنصر واحد على الأقل في هذه القائمة. يستخدم هذا الإجراء بنية نمط المطابقة نفسها المستخدَمة في values.

  • header

    سلسلة

    اسم العنوان. لا يتطابق هذا الشرط مع الاسم إلا في حال عدم تحديد values وexcludedValues.

  • values

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

    في حال تحديده، يتطابق هذا الشرط إذا كانت قيمة العنوان تتطابق مع نمط واحد على الأقل في هذه القائمة. يتيح ذلك مطابقة قيمة العنوان غير الحساسة لحالة الأحرف بالإضافة إلى البنى التالية:

    '*' : تتطابق مع أي عدد من الأحرف.

    '?' : يتطابق مع صفر أو حرف واحد.

    يمكن إلغاء حرفَي * و؟ باستخدام الشرطة المائلة للخلف، على سبيل المثال \* و\?

HeaderOperation

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

يصف هذا القسم العمليات المحتمَلة لقاعدة "تعديل الرؤوس".

Enum

‫"append"
تُضيف إدخالاً جديدًا للعنوان المحدّد. هذه العملية غير متاحة لرؤوس الطلبات.

‫"set"
تُستخدَم لضبط قيمة جديدة للعنوان المحدّد، مع إزالة أيّ عناوين حالية تحمل الاسم نفسه.

‫"remove"
تزيل جميع الإدخالات للعنوان المحدّد.

IsRegexSupportedResult

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

أماكن إقامة

  • isSupported

    قيمة منطقية

  • السبب

    ‫UnsupportedRegexReason اختياري

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

MatchedRule

أماكن إقامة

  • ruleId

    الرقم

    رقم تعريف قاعدة مطابقة

  • rulesetId

    سلسلة

    معرّف Ruleset التي تنتمي إليها هذه القاعدة. بالنسبة إلى قاعدة نشأت من مجموعة القواعد الديناميكية، سيكون هذا الرقم مساويًا DYNAMIC_RULESET_ID.

MatchedRuleInfo

أماكن إقامة

  • قاعدة

    MatchedRule

  • tabId

    الرقم

    رقم تعريف علامة التبويب التي صدر منها الطلب إذا كانت علامة التبويب لا تزال نشطة. غير ذلك -1.

  • timeStamp

    الرقم

    وقت مطابقة القاعدة. ستتوافق الطوابع الزمنية مع اصطلاح JavaScript للوقت، أي عدد المللي ثانية منذ بدء حساب الحقبة.

MatchedRuleInfoDebug

أماكن إقامة

MatchedRulesFilter

أماكن إقامة

  • minTimeStamp

    رقم اختياري

    في حال تحديدها، لا تتطابق إلا مع القواعد بعد الطابع الزمني المحدّد.

  • tabId

    رقم اختياري

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

ModifyHeaderInfo

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

أماكن إقامة

  • header

    سلسلة

    اسم العنوان المطلوب تعديله.

  • عملية

    HeaderOperation

    العملية التي سيتم تنفيذها على عنوان

  • القيمة

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

    القيمة الجديدة للعنوان يجب تحديدها لإجراءَي append وset.

QueryKeyValue

أماكن إقامة

  • مفتاح

    سلسلة

  • replaceOnly

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

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

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

  • القيمة

    سلسلة

QueryTransform

أماكن إقامة

  • addOrReplaceParams

    QueryKeyValue[] اختياري

    قائمة أزواج مفتاح/قيمة طلب البحث التي ستتم إضافتها أو استبدالها

  • removeParams

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

    قائمة مفاتيح طلبات البحث التي سيتمّت إزالتها

Redirect

أماكن إقامة

  • extensionPath

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

    المسار النسبي لدليل الإضافة يجب أن يبدأ بـ "/".

  • regexSubstitution

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

    نمط الاستبدال للقواعد التي تحدّد regexFilter سيتم استبدال المطابقة الأولى لـ regexFilter ضمن عنوان URL بهذا النمط. ضمن regexSubstitution، يمكن استخدام الأرقام التي تم تحويلها باستخدام الشرطة المائلة للخلف (\1 إلى \9) لإدراج مجموعات الالتقاط المقابلة. يشير \0 إلى النص المطابق بالكامل.

  • تحويل

    ‫URLTransform اختياري

    عمليات تحويل عناوين URL التي يجب إجراؤها

  • url

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

    عنوان URL لإعادة التوجيه لا يُسمح بعمليات إعادة التوجيه إلى عناوين URL لرمز JavaScript.

RegexOptions

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

أماكن إقامة

  • isCaseSensitive

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

    ما إذا كان regex المحدّد حسّاسًا لحالة الأحرف الإعداد التلقائي هو "صحيح".

  • تعبير عادي

    سلسلة

    التعبير العادي المطلوب التحقّق منه

  • requireCapturing

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

    ما إذا كان regex المحدّد يتطلّب التقاطه لا تكون عملية الالتقاط مطلوبة إلّا لقواعد إعادة التوجيه التي تحدّد إجراء regexSubstition. القيمة التلقائية هي false.

RequestDetails

أماكن إقامة

  • documentId

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

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

    المعرّف الفريد لمستند الإطار، إذا كان هذا الطلب يتعلق بإطار.

  • documentLifecycle

    ‫DocumentLifecycle اختياري

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

    دورة حياة مستند الإطار، إذا كان هذا الطلب يتعلق بإطار.

  • frameId

    الرقم

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

  • frameType

    ‫FrameType اختياري

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

    نوع الإطار، إذا كان هذا الطلب لإطار

  • بادئ

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

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

  • method

    سلسلة

    طريقة HTTP العادية

  • parentDocumentId

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

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

    المعرّف الفريد للمستند الرئيسي للإطار، إذا كان هذا الطلب لإطار له مستند رئيسي

  • parentFrameId

    الرقم

    رقم تعريف الإطار الذي يلفّ الإطار الذي أرسل الطلب. يتم ضبطه على -1 إذا لم يكن هناك إطار رئيسي.

  • requestId

    سلسلة

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

  • tabId

    الرقم

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

  • كتابة

    ResourceType

    نوع المورد للطلب

  • url

    سلسلة

    عنوان URL للطلب.

RequestMethod

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

يصف هذا الحقل طريقة طلب HTTP لطلب الشبكة.

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

يصف هذا الحقل نوع المورد لطلب الشبكة.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

أماكن إقامة

  • إجراء

    RuleAction

    الإجراء الذي يجب اتّخاذه في حال تطابق هذه القاعدة.

  • الشرط

    RuleCondition

    الشرط الذي يتم بموجبه تفعيل هذه القاعدة.

  • id

    الرقم

    معرّف يحدِّد قاعدة بشكلٍ فريد مطلوبة ويجب أن تكون >= 1.

  • الحملة

    رقم اختياري

    أولوية القاعدة القيمة التلقائية هي 1. يجب أن تكون >= 1 عند تحديدها.

RuleAction

أماكن إقامة

  • إعادة توجيه

    إعادة التوجيه اختياري

    يصف كيفية تنفيذ عملية إعادة التوجيه. صالح لقواعد إعادة التوجيه فقط.

  • requestHeaders

    ModifyHeaderInfo[] اختيارية

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

    عناوين الطلبات التي يجب تعديلها للطلب. تكون صالحة فقط إذا كانت قيمة RuleActionType هي "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] اختيارية

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

    عناوين الاستجابة التي يجب تعديلها للطلب تكون صالحة فقط إذا كانت قيمة RuleActionType هي "modifyHeaders".

  • كتابة

    RuleActionType

    نوع الإجراء الذي سيتم تنفيذه

RuleActionType

يصف نوع الإجراء الذي يجب اتّخاذه في حال تطابق شرط قاعدة معيّن.

Enum

"حظر"
حظر طلب الشبكة

"إعادة التوجيه"
إعادة توجيه طلب الشبكة

"allow"
السماح بطلب الوصول إلى الشبكة لن يتم اعتراض الطلب إذا كانت هناك قاعدة السماح تتطابق معه.

‫"upgradeScheme"
ترقية مخطّط عنوان URL لطلب الشبكة إلى https إذا كان الطلب http أو ftp

‫"modifyHeaders"
تعديل رؤوس الطلب/الردّ من طلب الشبكة

‫"allowAllRequests"
السماح بجميع الطلبات ضمن تسلسل هرمي للإطارات، بما في ذلك طلب الإطار نفسه

RuleCondition

أماكن إقامة

  • domainType

    ‫DomainType اختياري

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

  • النطاقات

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

    تم إيقافها نهائيًا منذ الإصدار 101 من Chrome

    استخدِم initiatorDomains بدلاً من ذلك.

    لن تتطابق القاعدة إلا مع طلبات الشبكة التي تأتي من قائمة domains.

  • excludedDomains

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

    تم إيقافها نهائيًا منذ الإصدار 101 من Chrome

    استخدِم excludedInitiatorDomains بدلاً من ذلك.

    لن تتطابق القاعدة مع طلبات الشبكة الواردة من قائمة excludedDomains.

  • excludedInitiatorDomains

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

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

    لن تتطابق القاعدة مع طلبات الشبكة الواردة من قائمة excludedInitiatorDomains. إذا كانت القائمة فارغة أو تم حذفها، لن يتم استبعاد أي نطاقات. تكون هذه السياسة لها الأولوية على initiatorDomains.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتألّف الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode لنطاقات اللغات الأجنبية.
    • وتتطابق هذه القيمة مع عنصر بدء الطلب وليس عنوان URL للطلب.
    • ويتم أيضًا استبعاد النطاقات الفرعية للنطاقات المدرَجة.
  • excludedRequestDomains

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

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

    لن تتطابق القاعدة مع طلبات الشبكة عندما تتطابق النطاقات مع أحد النطاقات من قائمة excludedRequestDomains. إذا كانت القائمة فارغة أو تم حذفها، لن يتم استبعاد أي نطاقات. تكون هذه السياسة لها الأولوية على requestDomains.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتألّف الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode لنطاقات اللغات الأجنبية.
    • ويتم أيضًا استبعاد النطاقات الفرعية للنطاقات المدرَجة.
  • excludedRequestMethods

    RequestMethod[] اختياري

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

    قائمة طُرق الطلب التي لن تتطابق معها القاعدة يجب تحديد سمة واحدة فقط من requestMethods وexcludedRequestMethods. في حال عدم تحديد أي منهما، تتم مطابقة جميع طُرق الطلب.

  • excludedResourceTypes

    ResourceType[] اختياري

    قائمة بأنواع الموارد التي لن تتطابق معها القاعدة يجب تحديد سمة واحدة فقط من resourceTypes وexcludedResourceTypes. في حال عدم تحديد أيّ منهما، يتم حظر جميع أنواع الموارد باستثناء "main_frame".

  • excludedResponseHeaders

    HeaderInfo[] اختياري

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

    لا تتطابق القاعدة إذا كان الطلب يتطابق مع أيّ شرط لعنوان الاستجابة في هذه القائمة (إذا تم تحديده). إذا تم تحديد السمتَين excludedResponseHeaders وresponseHeaders، تكون السمة excludedResponseHeaders لها الأولوية.

  • excludedTabIds

    number[] اختيارية

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

    قائمة tabs.Tab.id التي يجب ألا تتطابق معها القاعدة يُستبعد من خلال المعرّف tabs.TAB_ID_NONE الطلبات التي لا تأتي من علامة تبويب. لا تتوفّر هذه الميزة إلا للقواعد على مستوى الجلسة.

  • initiatorDomains

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

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

    لن تتطابق القاعدة إلا مع طلبات الشبكة التي تأتي من قائمة initiatorDomains. في حال حذف القائمة، يتم تطبيق القاعدة على الطلبات الواردة من جميع النطاقات. لا يُسمح بقائمة فارغة.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتألّف الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode لنطاقات اللغات الأجنبية.
    • وتتطابق هذه القيمة مع عنصر بدء الطلب وليس عنوان URL للطلب.
    • تتم أيضًا مطابقة النطاقات الفرعية للنطاقات المدرَجة.
  • isUrlFilterCaseSensitive

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

    ما إذا كان urlFilter أو regexFilter (أيهما محدّد) حسّاسًا لحالة الأحرف القيمة التلقائية هي false.

  • regexFilter

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

    تعبير عادي لمطابقته مع عنوان URL لطلب الشبكة ويتبع ذلك بنية RE2.

    ملاحظة: يمكن تحديد قيمة واحدة فقط من urlFilter أو regexFilter.

    ملاحظة: يجب أن يتألّف regexFilter من أحرف ASCII فقط. تتم مطابقة هذا مع عنوان URL تم ترميز المضيف فيه بتنسيق punycode (في حال النطاقات المُعرَّبة) وأي أحرف أخرى غير ASCII يتم ترميزها بترميز UTF-8.

  • requestDomains

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

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

    لن تتطابق القاعدة مع طلبات الشبكة إلا عندما يتطابق النطاق مع أحد النطاقات من قائمة requestDomains. في حال حذف القائمة، يتم تطبيق القاعدة على الطلبات الواردة من جميع النطاقات. لا يُسمح بقائمة فارغة.

    ملاحظات:

    • ويُسمح أيضًا بالنطاقات الفرعية مثل "a.example.com".
    • يجب أن تتألّف الإدخالات من أحرف ASCII فقط.
    • استخدِم ترميز punycode لنطاقات اللغات الأجنبية.
    • تتم أيضًا مطابقة النطاقات الفرعية للنطاقات المدرَجة.
  • requestMethods

    RequestMethod[] اختياري

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

    قائمة بطرق طلب HTTP التي يمكن للقاعدة مطابقتها لا يُسمح بقائمة فارغة.

    ملاحظة: سيؤدي تحديد شرط قاعدة requestMethods إلى استبعاد طلبات غير HTTP أيضًا، في حين لن يؤدي تحديد excludedRequestMethods إلى ذلك.

  • resourceTypes

    ResourceType[] اختياري

    قائمة بأنواع الموارد التي يمكن أن تتطابق معها القاعدة لا يُسمح بقائمة فارغة.

    ملاحظة: يجب تحديد هذا الخيار لقواعد allowAllRequests، ولا يمكن أن يتضمّن سوى نوعَي الموارد sub_frame وmain_frame.

  • responseHeaders

    HeaderInfo[] اختياري

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

    تتم مطابقة القاعدة إذا كان الطلب يتطابق مع أيّ شرط لعنوان الاستجابة في هذه القائمة (إذا تم تحديده).

  • tabIds

    number[] اختيارية

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

    قائمة tabs.Tab.id التي يجب أن تتطابق معها القاعدة يتطابق المعرّف tabs.TAB_ID_NONE مع الطلبات التي لا تأتي من علامة تبويب. لا يُسمح بقائمة فارغة. لا تتوفّر إلا للقواعد على مستوى الجلسة.

  • urlFilter

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

    النمط الذي تتم مطابقته مع عنوان URL لطلب الشبكة البنى المسموح بها:

    '*' : حرف البدل: يتطابق مع أي عدد من الأحرف.

    '|' : علامة الإرساء اليمنى/اليسرى: في حال استخدامها في أي من طرفَي النمط، تحدّد بداية/نهاية عنوان URL على التوالي.

    '||' : عنصر تثبيت اسم النطاق: في حال استخدامه في بداية النمط، يحدّد بداية نطاق (فرعي) لعنوان URL.

    '^' : رمز الفاصل: يتطابق هذا الرمز مع أي عنصر باستثناء حرف أو رقم أو أحد العناصر التالية: _ أو - أو . أو %. يتطابق هذا أيضًا مع نهاية عنوان URL.

    لذلك، يتألّف الرمز urlFilter من الأجزاء التالية: (مرجع اختياري لليسار/اسم النطاق) + النمط + (مرجع اختياري لليمين).

    في حال حذفه، تتم مطابقة جميع عناوين URL. لا يُسمح باستخدام سلسلة فارغة.

    لا يُسمح باستخدام نمط يبدأ بـ ||*. استخدِم * بدلاً من ذلك.

    ملاحظة: يمكن تحديد قيمة واحدة فقط من urlFilter أو regexFilter.

    ملاحظة: يجب أن يتألّف urlFilter من أحرف ASCII فقط. تتم مطابقة هذا مع عنوان URL تم ترميز المضيف فيه بتنسيق punycode (في حال النطاقات المُعرَّبة) وأي أحرف أخرى غير ASCII يتم ترميزها بترميز UTF-8. على سبيل المثال، عندما يكون عنوان URL للطلب هو http://abc.рф?q=ф، سيتم مطابقة urlFilter مع عنوان URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

أماكن إقامة

  • مفعّلة

    قيمة منطقية

    ما إذا كانت مجموعة القواعد مفعّلة تلقائيًا.

  • id

    سلسلة

    سلسلة غير فارغة تُعرّف مجموعة القواعد بشكل فريد إنّ المعرّفات التي تبدأ بـ "_" محجوزة للاستخدام الداخلي.

  • المسار

    سلسلة

    مسار مجموعة قواعد JSON بالنسبة إلى دليل الإضافات

RulesMatchedDetails

أماكن إقامة

  • rulesMatchedInfo

    MatchedRuleInfo[]

    القواعد التي تتطابق مع الفلتر المحدّد

TabActionCountUpdate

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

أماكن إقامة

  • زيادة

    الرقم

    القيمة التي ستزيد بها عدد إجراءات علامة التبويب ستؤدي القيم السلبية إلى خفض العدد.

  • tabId

    الرقم

    علامة التبويب التي تريد تعديل عدد الإجراءات فيها.

TestMatchOutcomeResult

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

أماكن إقامة

  • matchedRules

    MatchedRule[]

    القواعد (إن توفّرت) التي تتطابق مع الطلب الافتراضي

TestMatchRequestDetails

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

أماكن إقامة

  • بادئ

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

    عنوان URL لبادئ التشغيل (إن توفّر) للطلب الافتراضي.

  • method

    ‫RequestMethod اختياري

    طريقة HTTP العادية للطلب الافتراضي القيمة التلقائية هي get لطلبات HTTP ويتم تجاهلها لطلبات غير HTTP.

  • responseHeaders

    العنصر اختياري

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

    الرؤوس المقدَّمة من خلال ردّ افتراضي في حال عدم حظر الطلب أو إعادة توجيهه قبل إرساله يتم تمثيله كعنصر يربط اسم عنوان بقائمة من قيم السلاسل. في حال عدم تحديده، سيعرض الاستجابة الافتراضية رؤوس استجابة فارغة، ما يمكن أن يتطابق مع القواعد التي تتطابق مع عدم توفّر رؤوس. مثلاً {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    رقم اختياري

    رقم تعريف علامة التبويب التي يتم فيها الطلب الافتراضي ولا يُشترَط أن يتطابق مع معرّف علامة تبويب حقيقي. القيمة التلقائية هي -1، ما يعني أنّ الطلب غير مرتبط بعلامة تبويب.

  • كتابة

    ResourceType

    نوع المورد للطلب الافتراضي

  • url

    سلسلة

    عنوان URL للطلب الافتراضي

UnsupportedRegexReason

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

يوضّح سبب عدم توفّر تعبير عادي معيّن.

Enum

"syntaxError"
التعبير العادي غير صحيح من الناحية النحوية أو يستخدم ميزات غير متوفّرة في بنية RE2.

"memoryLimitExceeded"
يتجاوز التعبير العادي الحد الأقصى للذاكرة.

UpdateRuleOptions

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

أماكن إقامة

  • addRules

    القاعدة[] اختيارية

    القواعد المطلوب إضافتها

  • removeRuleIds

    number[] اختيارية

    أرقام تعريف القواعد المطلوب إزالتها وسيتم تجاهل أي أرقام تعريف غير صالحة.

UpdateRulesetOptions

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

أماكن إقامة

  • disableRulesetIds

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

    مجموعة الأرقام التعريفية التي تتوافق مع Ruleset ثابتة يجب إيقافها

  • enableRulesetIds

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

    مجموعة الأرقام التعريفية التي تتوافق مع Ruleset ثابتة يجب تفعيلها.

UpdateStaticRulesOptions

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

أماكن إقامة

  • disableRuleIds

    number[] اختيارية

    مجموعة أرقام التعريف المقابلة للقواعد في Ruleset المطلوب إيقافها

  • enableRuleIds

    number[] اختيارية

    مجموعة من أرقام التعريف المقابلة للقواعد في Ruleset المطلوب تفعيلها

  • rulesetId

    سلسلة

    المعرّف المقابل لعنصر Ruleset ثابت

URLTransform

أماكن إقامة

  • جزء

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

    المقتطف الجديد للطلب يجب أن يكون فارغًا، وفي هذه الحالة يتم محو المقتطف الحالي، أو يجب أن يبدأ بـ "#".

  • مضيف

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

    المضيف الجديد للطلب.

  • كلمة المرور

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

    كلمة المرور الجديدة للطلب.

  • المسار

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

    المسار الجديد للطلب إذا كان فارغًا، يتم محو المسار الحالي.

  • المنفذ

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

    المنفذ الجديد للطلب إذا كان الحقل فارغًا، يتم محو المنفذ الحالي.

  • query

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

    الطلب الجديد يجب أن يكون فارغًا، وفي هذه الحالة يتم محو طلب البحث الحالي، أو يجب أن يبدأ بعلامة "؟".

  • queryTransform

    ‫QueryTransform اختياري

    إضافة أزواج مفتاح/قيمة للطلبات أو إزالتها أو استبدالها

  • المخطط

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

    المخطّط الجديد للطلب. القيم المسموح بها هي "http" و"https" و"ftp" و "chrome-extension".

  • اسم مستخدم

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

    اسم المستخدم الجديد للطلب.

أماكن إقامة

DYNAMIC_RULESET_ID

معرّف مجموعة القواعد للقواعد الديناميكية التي أضافتها الإضافة

القيمة

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

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

القيمة

10

GUARANTEED_MINIMUM_STATIC_RULES

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

الحد الأدنى لعدد القواعد الثابتة المضمونة للإضافة في جميع مجموعات القواعد الثابتة المفعّلة وسيتم احتساب أي قواعد تتجاوز هذا الحدّ ضمن الحدّ الأقصى للقواعد الثابتة العالمية.

القيمة

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

عدد المرات التي يمكن فيها استدعاء getMatchedRules خلال فترة GETMATCHEDRULES_QUOTA_INTERVAL

القيمة

20

MAX_NUMBER_OF_DYNAMIC_RULES

الحد الأقصى لعدد القواعد الديناميكية التي يمكن أن تضيفها الإضافة

القيمة

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

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

الحدّ الأقصى لعدد Rulesets الثابتة التي يمكن أن تفعّلها الإضافة في أيّ وقت

القيمة

50

MAX_NUMBER_OF_REGEX_RULES

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

القيمة

1,000

MAX_NUMBER_OF_SESSION_RULES

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

الحد الأقصى لعدد القواعد على مستوى الجلسة التي يمكن أن تضيفها الإضافة

القيمة

5,000

MAX_NUMBER_OF_STATIC_RULESETS

الحد الأقصى لعدد Rulesets الثابتة التي يمكن أن تحدّدها الإضافة كجزء من مفتاح بيان "rule_resources"

القيمة

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

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

الحد الأقصى لعدد القواعد الديناميكية "غير الآمنة" التي يمكن أن تضيفها إحدى الإضافات

القيمة

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

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

الحد الأقصى لعدد القواعد على مستوى الجلسة "غير الآمنة" التي يمكن أن تضيفها إحدى الإضافات

القيمة

5,000

SESSION_RULESET_ID

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

رقم تعريف مجموعة القواعد للقواعد على مستوى الجلسة التي أضافتها الإضافة.

القيمة

"_session"

الطُرق

getAvailableStaticRuleCount()

الوعد الإصدار 89 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

المعلمات

  • ردّ الاتصال

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

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

    (count: number) => void

    • العدد

      الرقم

المرتجعات

  • Promise<number>

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

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

getDisabledRuleIds()

الوعد Chrome 111 والإصدارات الأحدث 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

عرض قائمة القواعد الثابتة في Ruleset المحدّدة والتي تم إيقافها حاليًا

المعلمات

  • الخيارات

    GetDisabledRuleIdsOptions

    تُحدِّد مجموعة القواعد التي سيتم الاستعلام عنها.

  • ردّ الاتصال

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

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

المرتجعات

  • Promise<number[]>

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

getDynamicRules()

الوعد 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

لعرض المجموعة الحالية من القواعد الديناميكية للإضافة. يمكن للمتصلين اختياريًا فلترة قائمة القواعد التي تم جلبها من خلال تحديد filter.

المعلمات

  • تصفية

    GetRulesFilter اختياري

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

    عنصر لفلترة قائمة القواعد التي تم جلبها

  • ردّ الاتصال

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

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

    (rules: Rule[]) => void

المرتجعات

  • Promise<Rule[]>

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

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

getEnabledRulesets()

الوعد 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

لعرض أرقام تعريف المجموعة الحالية من قواعد القواعد الثابتة المفعّلة.

المعلمات

  • ردّ الاتصال

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

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

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

المرتجعات

  • Promise<string[]>

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

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

getMatchedRules()

الوعد 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

تعرِض هذه الدالة جميع القواعد التي تمت مطابقتها مع الإضافة. يمكن للمتصلين اختياريًا فلترة قائمة القواعد المطابقة من خلال تحديد filter. لا تتوفّر هذه الطريقة إلا للإضافات التي تملك إذن "declarativeNetRequestFeedback" أو التي تم منحها إذن "activeTab" للtabId المحدّد في filter. ملاحظة: لن يتم عرض القواعد غير المرتبطة بمستند نشط والتي تمت مطابقتها قبل أكثر من خمس دقائق.

المعلمات

  • تصفية

    MatchedRulesFilter اختياري

    عنصر لفلترة قائمة القواعد المطابقة

  • ردّ الاتصال

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

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

    (details: RulesMatchedDetails) => void

المرتجعات

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

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

getSessionRules()

الوعد Chrome 90 والإصدارات الأحدث 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

لعرض المجموعة الحالية من القواعد على مستوى الجلسة للإضافات. يمكن للمتصلين اختياريًا فلترة قائمة القواعد التي تم جلبها من خلال تحديد filter.

المعلمات

  • تصفية

    GetRulesFilter اختياري

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

    عنصر لفلترة قائمة القواعد التي تم جلبها

  • ردّ الاتصال

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

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

    (rules: Rule[]) => void

المرتجعات

  • Promise<Rule[]>

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

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

isRegexSupported()

الوعد الإصدار 87 من Chrome والإصدارات الأحدث 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

للتحقّق مما إذا كان التعبير العادي المحدّد متوافقًا كشرط لقاعدة regexFilter.

المعلمات

  • regexOptions

    RegexOptions

    التعبير العادي المطلوب التحقّق منه.

  • ردّ الاتصال

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

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

    (result: IsRegexSupportedResult) => void

المرتجعات

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

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

setExtensionActionOptions()

الوعد Chrome 88 والإصدارات الأحدث 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

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

المعلمات

  • الخيارات

    ExtensionActionOptions

  • ردّ الاتصال

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

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

testMatchOutcome()

الوعد Chrome 103 والإصدارات الأحدث 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

للتحقّق مما إذا كانت أيّ من قواعد declarativeNetRequest في الإضافة تتطابق مع طلب افتراضي. ملاحظة: لا تتوفّر هذه الميزة إلا للإضافات غير المُنزَّلة، لأنّها مخصّصة للاستخدام أثناء تطوير الإضافة فقط.

المعلمات

المرتجعات

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

updateDynamicRules()

الوعد 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

تعديل المجموعة الحالية من القواعد الديناميكية للإضافة تتم أولاً إزالة القواعد التي تتضمّن أرقام التعريف المدرَجة في options.removeRuleIds، ثم تتم إضافة القواعد الواردة في options.addRules. ملاحظات:

  • يتم إجراء هذا التعديل كعملية واحدة أساسية: إما أن تتم إضافة جميع القواعد المحدّدة وإزالتها، أو يتم عرض خطأ.
  • ويتم الاحتفاظ بهذه القواعد في جميع جلسات المتصفّح وعمليات تحديث الإضافات.
  • لا يمكن إزالة القواعد الثابتة المحدّدة كجزء من حزمة الإضافة باستخدام هذه الدالة.
  • MAX_NUMBER_OF_DYNAMIC_RULES هو الحد الأقصى لعدد القواعد الديناميكية التي يمكن أن تضيفها الإضافة. يجب ألا يتجاوز عدد القواعد غير الآمنة MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

المعلمات

  • الخيارات

    UpdateRuleOptions

    الإصدار 87 من Chrome والإصدارات الأحدث
  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

updateEnabledRulesets()

الوعد 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

تعديل مجموعة القواعد الثابتة المفعّلة للإضافات تتم أولاً إزالة قواعد القواعد التي تحتوي على أرقام التعريف المدرَجة في options.disableRulesetIds، ثم تتم إضافة قواعد القواعد المدرَجة في options.enableRulesetIds. يُرجى العِلم أنّه يتم الاحتفاظ بمجموعة القواعد الثابتة المفعَّلة في جميع الجلسات، ولكن ليس في جميع تحديثات الإضافات، أي أنّ مفتاح البيان rule_resources سيحدِّد مجموعة القواعد الثابتة المفعَّلة في كل تحديث للإضافة.

المعلمات

  • الخيارات

    UpdateRulesetOptions

    الإصدار 87 من Chrome والإصدارات الأحدث
  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

updateSessionRules()

الوعد Chrome 90 والإصدارات الأحدث 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

تعديل المجموعة الحالية من القواعد على مستوى الجلسة للإضافة أولاً، تتم إزالة القواعد التي تحتوي على أرقام التعريف المدرَجة في options.removeRuleIds، ثم تتم إضافة القواعد الواردة في options.addRules. ملاحظات:

  • يتم إجراء هذا التعديل كعملية واحدة أساسية: إما أن تتم إضافة جميع القواعد المحدّدة وإزالتها، أو يتم عرض خطأ.
  • لا يتم الاحتفاظ بهذه القواعد على مستوى الجلسات ويتم الاحتفاظ بنسخة احتياطية منها في الذاكرة.
  • MAX_NUMBER_OF_SESSION_RULES هو الحد الأقصى لعدد قواعد الجلسات التي يمكن أن تضيفها الإضافة.

المعلمات

  • الخيارات

    UpdateRuleOptions

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

updateStaticRules()

الوعد Chrome 111 والإصدارات الأحدث 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

يتيح هذا الإعداد إيقاف القواعد الثابتة الفردية وتفعيلها في Ruleset. ستسري التغييرات على القواعد التي تنتمي إلى Ruleset غير مفعّل في المرة التالية التي يتم فيها تفعيله.

المعلمات

  • الخيارات

    UpdateStaticRulesOptions

  • ردّ الاتصال

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

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

    () => void

المرتجعات

  • Promise<void>

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

الفعاليات

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

يتمّ تشغيله عند مطابقة قاعدة مع طلب. لا يتوفّر هذا الخيار إلا للإضافات غير المُعنوَنة التي تملك إذن "declarativeNetRequestFeedback"، لأنّه مخصّص لاستخدامه لأغراض تصحيح الأخطاء فقط.

المعلمات