chrome.declarativeNetRequest

الوصف

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

الأذونات

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

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

مدى التوفّر

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

البيان

بالإضافة إلى الأذونات الموضّحة سابقًا، تتطلب أنواع معيّنة من مجموعات القواعد، أو مجموعات القواعد الثابتة على وجه التحديد، التعريف بمفتاح بيان "declarative_net_request"، الذي يجب أن يكون قاموسًا يتضمّن مفتاحًا واحدًا يُعرف باسم "rule_resources". هذا المفتاح هو مصفوفة تحتوي على قواميس من النوع Ruleset، كما هو موضح في ما يلي. (يُرجى العِلم أنّ اسم "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(). يمكنك الاطّلاع على مثال على ذلك ضمن أمثلة الرموز.

قواعد الجلسة

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

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

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

يمكن أن تحتوي الإضافة على 5000 قاعدة ديناميكية على الأقل. يتم الكشف عن هذا على أنه 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

"الطرف الأول"
طلب الشبكة هو الطرف الأول في الإطار الذي تم إنشاؤه منه.

"الطرف الثالث"
طلب الشبكة هو طرف ثالث في الإطار الذي تم إنشاؤه منه.

ExtensionActionOptions

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

أماكن إقامة

  • displayActionCountAsBadgeText

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

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

  • tabUpdate

    TabActionCountUpdate اختياري

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

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

GetDisabledRuleIdsOptions

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

أماكن إقامة

  • rulesetId

    سلسلة

    رقم التعريف المتوافق مع Ruleset ثابت.

GetRulesFilter

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

أماكن إقامة

  • ruleIds

    number[] اختياري

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

HeaderInfo

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

أماكن إقامة

  • excludedValues

    string[] اختيارية

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

  • header

    سلسلة

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

  • values

    string[] اختيارية

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

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

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

    "*" و"؟" ويمكن تخطيها بشرطة مائلة للخلف، على سبيل المثال: "\*" و"\؟"

HeaderOperation

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

يصف هذا الإجراء العمليات المحتملة لـ "modifyHeaders" قاعدة البيانات.

Enum

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

"set"
تضبط قيمة جديدة للرأس المحدد، مع إزالة أي رؤوس حالية تحمل الاسم نفسه.

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

IsRegexSupportedResult

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

أماكن إقامة

  • isSupported

    منطقي

  • السبب

    UnsupportedRegexReason اختياري

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

MatchedRule

أماكن إقامة

  • ruleId

    الرقم

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

  • rulesetId

    سلسلة

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

MatchedRuleInfo

أماكن إقامة

  • قاعدة

    MatchedRule

  • tabId

    الرقم

    رقم تعريف علامة التبويب لعلامة التبويب التي نشأ منها الطلب إذا كانت علامة التبويب لا تزال نشطة. أخرى -1.

  • timeStamp

    الرقم

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

MatchedRuleInfoDebug

أماكن إقامة

  • تفاصيل حول الطلب الذي تمت مطابقة القاعدة له.

  • قاعدة

    MatchedRule

MatchedRulesFilter

أماكن إقامة

  • minTimeStamp

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

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

  • tabId

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

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

ModifyHeaderInfo

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

أماكن إقامة

  • header

    سلسلة

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

  • عملية

    HeaderOperation

    العملية المطلوب إجراؤها على العنوان.

  • القيمة

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

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

QueryKeyValue

أماكن إقامة

  • مفتاح

    سلسلة

  • replaceOnly

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

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

    إذا كانت القيمة true، يتم استبدال مفتاح الاستعلام فقط إذا كان موجودًا بالفعل. وبخلاف ذلك، تتم إضافة المفتاح أيضًا إذا كان مفقودًا. وتكون القيمة التلقائية على "خطأ".

  • القيمة

    سلسلة

QueryTransform

أماكن إقامة

  • addOrReplaceParams

    QueryKeyValue[] اختيارية

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

  • removeParams

    string[] اختيارية

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

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 اختياري

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

    تمثّل هذه السمة نوع الإطار إذا كان هذا الطلب يتعلّق بإطار.

  • بادئ التشغيل

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

    المصدر الذي تم فيه تقديم الطلب. ولا يتغيّر ذلك عند إجراء عمليات إعادة التوجيه. إذا كان هذا مصدرًا مبهمًا، ستظهر السلسلة "null" تنبؤي.

  • method

    سلسلة

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

  • parentDocumentId

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

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

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

  • parentFrameId

    الرقم

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

  • requestId

    سلسلة

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

  • tabId

    الرقم

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

  • كتابة

    ResourceType

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

  • url

    سلسلة

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

RequestMethod

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

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

Enum

"الاتصال"

"حذف"

"get"

"الرأس"

"الخيارات"

"التصحيح"

"مشاركة"

"put"

"other"

ResourceType

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

Enum

"الإطار_الرئيسي"

"sub_frame"

"ورقة الأنماط"

"script"

"صورة"

"الخط"

"كائن"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"نقل الويب"

"حزمة ويب"

"other"

Rule

أماكن إقامة

  • إجراء

    RuleAction

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

  • الشرط

    RuleCondition

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

  • id

    الرقم

    تمثّل هذه السمة رقم تعريف يعرّف القاعدة بشكل فريد. إلزامية ويجب أن تكون >= 1.

  • الحملة

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

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

RuleAction

أماكن إقامة

  • إعادة توجيه

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

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

  • requestHeaders

    ModifyHeaderInfo[] اختيارية

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

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

  • responseHeaders

    ModifyHeaderInfo[] اختيارية

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

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

  • كتابة

    RuleActionType

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

RuleActionType

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

Enum

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

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

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

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

"modifyHeaders"
عدّل عناوين الطلبات/الاستجابة من طلب الشبكة.

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

RuleCondition

أماكن إقامة

  • domainType

    DomainType اختياري

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

  • النطاقات

    string[] اختيارية

    متوقّف منذ الإصدار 101 من Chrome

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

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

  • excludedDomains

    string[] اختيارية

    متوقّف منذ الإصدار 101 من Chrome

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

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

  • excludedInitiatorDomains

    string[] اختيارية

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

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

    ملاحظات:

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

    string[] اختيارية

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

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

    ملاحظات:

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

    RequestMethod[] اختيارية

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

    قائمة بطرق الطلب التي لن تتطابق القاعدة معها. يجب تحديد سمة واحدة فقط من 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

    string[] اختيارية

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

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

    ملاحظات:

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

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

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

  • regexFilter

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

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

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

    ملاحظة: يجب أن يتألف regexFilter من أحرف ASCII فقط. وتتم مطابقة ذلك مع عنوان URL حيث يكون المضيف مرمّزًا بتنسيق punycode (في حال النطاقات الدولية) وأي أحرف أخرى غير ascii هي عنوان url بترميز utf-8.

  • requestDomains

    string[] اختيارية

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

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

    ملاحظات:

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

    RequestMethod[] اختيارية

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

    قائمة بطرق طلب 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 هي عنوان url بترميز utf-8. على سبيل المثال، عندما يكون عنوان URL الخاص بالطلب هو http://abc.рт?q=بصورة، ستتم مطابقة urlFilter مع عنوان URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

أماكن إقامة

  • مفعّلة

    منطقي

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

  • id

    سلسلة

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

  • المسار

    سلسلة

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

RulesMatchedDetails

أماكن إقامة

  • rulesMatchedInfo

    MatchedRuleInfo[]

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

TabActionCountUpdate

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

أماكن إقامة

  • زيادة

    الرقم

    المقدار المطلوب زيادة عدد إجراءات علامة التبويب به. وتقلل القيم السالبة العدد.

  • tabId

    الرقم

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

TestMatchOutcomeResult

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

أماكن إقامة

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

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

أماكن إقامة

  • بادئ التشغيل

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

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

  • method

    RequestMethod اختيارية

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

  • responseHeaders

    الكائن اختياري

    في انتظار المراجعة

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

  • tabId

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

    تمثّل هذه السمة رقم تعريف علامة التبويب التي يحدث فيها الطلب الافتراضي. لا يجب أن تتوافق مع رقم تعريف علامة تبويب حقيقي. القيمة التلقائية هي -1، ما يعني أنّ الطلب غير مرتبط بعلامة تبويب.

  • كتابة

    ResourceType

    تمثّل هذه السمة نوع مورد الطلب الافتراضي.

  • url

    سلسلة

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

UnsupportedRegexReason

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

يصف سبب عدم توافق تعبير عادي معين.

Enum

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

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

UpdateRuleOptions

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

أماكن إقامة

  • addRules

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

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

  • removeRuleIds

    number[] اختياري

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

UpdateRulesetOptions

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

أماكن إقامة

  • disableRulesetIds

    string[] اختيارية

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

  • enableRulesetIds

    string[] اختيارية

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

UpdateStaticRulesOptions

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

أماكن إقامة

  • disableRuleIds

    number[] اختياري

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

  • enableRuleIds

    number[] اختياري

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

  • rulesetId

    سلسلة

    رقم التعريف المتوافق مع Ruleset ثابت.

URLTransform

أماكن إقامة

  • جزء

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

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

  • مضيف

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

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

  • كلمة المرور

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

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

  • المسار

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

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

  • المنفذ

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

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

  • query

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

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

  • queryTransform

    QueryTransform اختياري

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

  • المخطط

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

    المخطط الجديد للطلب. القيم المسموح بها هي "http" و"https" و"ftp" و"إضافة chrome".

  • اسم مستخدم

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

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

أماكن إقامة

DYNAMIC_RULESET_ID

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

القيمة

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

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

القيمة

10

GUARANTEED_MINIMUM_STATIC_RULES

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

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

القيمة

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

عدد المرّات التي يمكن فيها طلب الدالة getMatchedRules خلال فترة GETMATCHEDRULES_QUOTA_INTERVAL.

القيمة

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

القيمة

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

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

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

القيمة

50

MAX_NUMBER_OF_REGEX_RULES

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

القيمة

1,000

MAX_NUMBER_OF_SESSION_RULES

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

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

القيمة

5,000

MAX_NUMBER_OF_STATIC_RULESETS

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

القيمة

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

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

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

القيمة

5,000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

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

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

القيمة

5,000

SESSION_RULESET_ID

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

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

القيمة

"_session"

الطُرق

getAvailableStaticRuleCount()

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

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

المعلمات

  • رد الاتصال

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

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

    (count: number) => void

    • العدد

      الرقم

المرتجعات

  • Promise<number>

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

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

getDisabledRuleIds()

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

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

المعلمات

  • الخيارات

    GetDisabledRuleIdsOptions

    تُستخدَم لتحديد مجموعة القواعد لطلب البحث.

  • رد الاتصال

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

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

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      رقم[]

المرتجعات

  • وعد <number[]>

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

getDynamicRules()

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

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

المعلمات

  • تصفية

    GetRulesFilter اختياري

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

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

  • رد الاتصال

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

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

    (rules: Rule[]) => void

المرتجعات

  • الوعد<Rule[]>

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

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

getEnabledRulesets()

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

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

المعلمات

  • رد الاتصال

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

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

    (rulesetIds: string[]) => void

    • rulesetIds

      سلسلة[]

المرتجعات

  • Promise&lt;string[]&gt;

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

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

getMatchedRules()

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

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

المعلمات

  • تصفية

    MatchedRulesFilter اختياري

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

  • رد الاتصال

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

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

    (details: RulesMatchedDetails) => void

المرتجعات

  • Promise&lt;RulesMatchedDetails&gt;

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

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

getSessionRules()

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

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

المعلمات

  • تصفية

    GetRulesFilter اختياري

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

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

  • رد الاتصال

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

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

    (rules: Rule[]) => void

المرتجعات

  • الوعد<Rule[]>

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

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

isRegexSupported()

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

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

المعلمات

  • regexOptions

    RegexOptions

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

  • رد الاتصال

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

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

    (result: IsRegexSupportedResult) => void

المرتجعات

  • Promise&lt;IsRegexSupportedResult&gt;

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

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

setExtensionActionOptions()

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

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

المعلمات

  • الخيارات

    ExtensionActionOptions

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

testMatchOutcome()

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

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

المعلمات

المرتجعات

  • Promise&lt;TestMatchOutcomeResult&gt;

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

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

المرتجعات

  • وعود <باطلة>

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

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

updateEnabledRulesets()

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

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

المعلمات

  • الخيارات

    UpdateRulesetOptions

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

updateSessionRules()

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

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

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

المعلمات

  • الخيارات

    UpdateRuleOptions

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

updateStaticRules()

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

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

المعلمات

  • الخيارات

    UpdateStaticRulesOptions

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

فعاليات

onRuleMatchedDebug

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

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

المعلمات