کروم اکنون از فضای نام استاندارد browser.* (از کروم ۱۴۸ قابل دسترسی است). ما به تدریج مستندات را به‌روزرسانی می‌کنیم. برای اطلاعات بیشتر به راهنمای انتقال ما مراجعه کنید.

‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

browser.declarativeNetRequest

شرح

از chrome.declarativeNetRequest API برای مسدود کردن یا اصلاح درخواست‌های شبکه با مشخص کردن قوانین اعلانی استفاده می‌شود. این کار به افزونه‌ها اجازه می‌دهد درخواست‌های شبکه را بدون رهگیری آن‌ها و مشاهده محتوایشان اصلاح کنند، بنابراین حریم خصوصی بیشتری فراهم می‌شود.

اجازه‌ها

declarativeNetRequest
declarativeNetRequestWithHostAccess

اجازه‌های «declarativeNetRequest» و «declarativeNetRequestWithHostAccess» قابلیت‌های یکسانی ارائه می‌دهند. تفاوت بین آن‌ها در زمان درخواست یا اعطای اجازه‌ها است.

"declarativeNetRequest": در زمان نصب، هشدار اجازه راه‌اندازی می‌کند اما دسترسی ضمنی به allow، allowAllRequests و block قانون ارائه می‌دهد. درصورت امکان از این گزینه استفاده کنید تا نیازی به درخواست دسترسی کامل به میزبان‌ها نباشد.
"declarativeNetRequestFeedback": ویژگی‌های اشکال‌زدایی را برای افزونه‌های نافشرده، به‌ویژه getMatchedRules() و onRuleMatchedDebug فعال می‌کند.
"declarativeNetRequestWithHostAccess": هشدار اجازه در زمان نصب نشان داده نمی‌شود، اما باید قبل‌از انجام هرگونه کنش در میزبان، اجازه‌های میزبان را درخواست کنید. این زمانی مناسب است که بخواهید از قوانین درخواست شبکه اعلانی در افزونه‌ای استفاده کنید که ازقبل اجازه‌های میزبان را دارد بدون اینکه هشدارهای بیشتری ایجاد شود.

دردسترس بودن

Chrome 84+ browser.* از Chrome 148

مانیفست

علاوه‌بر اجازه‌هایی که قبلاً شرح داده شد، انواع خاصی از مجموعه‌قوانین، به‌ویژه مجموعه‌قوانین ثابت، نیاز به اعلام کلید مانیفست "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).
با نفی کردن هرگونه قانون مسدودشده منطبق، از مسدود شدن درخواست جلوگیری کنید.
هدایت کردن درخواست شبکه.
سرایندهای درخواست یا پاسخ را اصلاح کنید.

سه نوع مجموعه قانون وجود دارد که به روش‌های کمی متفاوت مدیریت می‌شوند.

پویا: در جلسه‌های مرورگر و ارتقاهای افزونه پایدار می‌مانند و هنگام استفاده از افزونه بااستفاده از جاوا اسکریپت مدیریت می‌شوند.
جلسه: وقتی مرورگر بسته می‌شود و وقتی نسخه جدیدی از افزونه نصب می‌شود، پاک می‌شود. قوانین جلسه بااستفاده از جاوا اسکریپت درحین استفاده از افزونه مدیریت می‌شود.
ثابت: وقتی افزونه‌ای نصب یا ارتقا داده می‌شود، بسته‌بندی، نصب، و به‌روزرسانی می‌شود. قوانین ایستا در فایل‌های قانون با قالب JSON ذخیره می‌شوند و در فایل مانیفست فهرست می‌شوند.

مجموعه قوانین پویا و جلسه‌محور

مجموعه قوانین پویا و جلسه‌ای بااستفاده از جاوا اسکریپت درحین استفاده از افزونه مدیریت می‌شوند.

قوانین پویا در جلسه‌های مرورگر و ارتقاهای افزونه باقی می‌مانند.
قوانین جلسه هنگام بسته شدن مرورگر و هنگام نصب نسخه جدید افزونه پاک می‌شوند.

فقط یک مورد از هرکدام از این انواع مجموعه قوانین وجود دارد. افزونه می‌تواند با فراخوانی 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 تعریف می‌شوند. حداکثر محدودیت ۵۰۰۰ قانون ثابت غیرفعال وجود دارد.

برای فعال یا غیرفعال کردن مجموعه قوانین ایستا، updateEnabledRulesets() را فراخوانی کنید. این روش یک شیء UpdateRulesetOptions را می‌گیرد که حاوی آرایه‌هایی از شناسه‌های مجموعه‌قوانین برای فعال یا غیرفعال کردن است. شناسه‌ها بااستفاده از کلید "id" واژه‌نامه Ruleset تعریف می‌شوند.

ایجاد قوانین

صرف‌نظر از نوع، یک قانون با چهار فیلد شروع می‌شود که در زیر نشان داده شده است. درحالی‌که کلیدهای "id" و "priority" یک عدد می‌گیرند، کلیدهای "action" و "condition" ممکن است چندین شرط مسدود کردن و تغییر مسیر ارائه دهند. قانون زیر همه درخواست‌های اسکریپت را که از "foo.com" به هر نشانی وب با "abc" به‌عنوان رشته فرعی ارسال می‌شود مسدود می‌کند.

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

مطابقت نشانی وب

Declarative Net Request امکان مطابقت دادن نشانی‌های وب را با نحو تطابق الگو یا عبارت‌های باقاعده فراهم می‌کند.

نحو فیلتر نشانی وب

کلید "condition" قانون به کلید "urlFilter" اجازه می‌دهد تا روی نشانی‌های وب تحت دامنه مشخص‌شده عمل کند. الگوها را بااستفاده از نشان‌های تطبیق الگو ایجاد می‌کنید. در اینجا چند مثال آورده شده است.

`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" را ببینید. برای آشنایی با محدودیت‌هایی که برای این شرایط اعمال می‌شود، قوانینی که از عبارت‌های باقاعده استفاده می‌کنند را ببینید.

نوشتن شرایط نشانی وب خوب

هنگام نوشتن قوانین دقت کنید که همیشه با کل دامنه مطابقت داشته باشد. درغیراین‌صورت، ممکن است قانون شما در شرایط غیرمنتظره‌ای مطابقت داشته باشد. برای مثال، هنگام استفاده از نحو تطبیق الگو:

‫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 درخواست جدیدی به نشانی وب تغییرمسیرشده ارسال می‌کند. حتماً درنظر بگیرید که آیا این رفتارها با انتظارات حریم خصوصی برای افزونه شما مطابقت دارد یا نه.

اگر درخواست مسدود یا هدایت نشود، Chrome هرگونه قانون modifyHeaders را اعمال می‌کند. اعمال تغییرات در سرایندهای پاسخ به همان روشی که در «قبل‌از ارسال سرایندهای درخواست» توضیح داده شده است کار می‌کند. اعمال تغییرات در سرصفحه‌های درخواست هیچ کاری انجام نمی‌دهد، زیرا درخواست قبلاً انجام شده است.

قوانین ایمن

قوانین ایمن به‌عنوان قوانینی با کنش block، allow، allowAllRequests، یا upgradeScheme تعریف می‌شوند. این قوانین مشمول افزایش سهمیه قوانین پویا هستند.

حدود قانون

بار کردن و ارزیابی قوانین در مرورگر سربار عملکردی دارد، بنابراین هنگام استفاده از API برخی محدودیت‌ها اعمال می‌شود. محدودیت‌ها به نوع قاعده‌ای که استفاده می‌کنید بستگی دارد.

قوانین ایستا

قوانین ثابت قوانینی هستند که در فایل‌های قانون اعلام‌شده در فایل مانیفست مشخص شده‌اند. افزونه می‌تواند تا ۱۰۰ مجموعه قانون ایستا را به‌عنوان بخشی از کلید مانیفست "rule_resources" مشخص کند، اما فقط ۵۰ مورد از این مجموعه‌های قانون می‌توانند به‌طور هم‌زمان فعال شوند. به دومی MAX_NUMBER_OF_ENABLED_STATIC_RULESETS می‌گویند. درمجموع، برای این مجموعه‌های قانون حداقل ۳۰٬۰۰۰ قانون تضمین می‌شود. به این حالت GUARANTEED_MINIMUM_STATIC_RULES می‌گویند.

تعداد قوانین دردسترس پس‌از آن به تعداد قوانینی بستگی دارد که توسط همه افزونه‌های نصب‌شده در مرورگر کاربر فعال شده است. می‌توانید این شماره را در زمان اجرا با تماس با getAvailableStaticRuleCount() پیدا کنید. می‌توانید نمونه‌ای از این مورد را در بخش نمونه‌های کد مشاهده کنید.

قوانین جلسه

افزونه می‌تواند حداکثر ۵۰۰۰ قانون جلسه داشته باشد. این مورد به‌عنوان MAX_NUMBER_OF_SESSION_RULES نمایش داده می‌شود.

قبل‌از Chrome 120، محدودیتی برای ۵۰۰۰ قانون پویا و جلسه ترکیبی وجود داشت.

قوانین پویا

افزونه می‌تواند حداقل ۵۰۰۰ قانون پویا داشته باشد. این مورد به‌عنوان MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES نمایش داده می‌شود.

از Chrome نسخه ۱۲۱، محدودیت بزرگ‌تر ۳۰٬۰۰۰ قانون برای قوانین پویا ایمن دردسترس است، که به‌عنوان MAX_NUMBER_OF_DYNAMIC_RULES نمایش داده می‌شود. هرگونه قانون ناامن اضافه‌شده در محدوده ۵۰۰۰ نیز در این حد لحاظ خواهد شد.

قبل‌از Chrome 120، محدودیت ۵۰۰۰ قانون پویا و جلسه ترکیبی وجود داشت.

قوانینی که از عبارت‌های باقاعده استفاده می‌کنند

همه انواع قوانین می‌توانند از عبارت‌های باقاعده استفاده کنند؛ بااین‌حال، تعداد کل قوانین عبارت باقاعده از هر نوع نمی‌تواند از ۱۰۰۰ بیشتر باشد. این حالت MAX_NUMBER_OF_REGEX_RULES نامیده می‌شود.

علاوه‌براین، هر قانون پس‌از کامپایل شدن باید کمتر از ۲ کیلوبایت باشد. این زمان تقریباً با پیچیدگی قانون همبستگی دارد. اگر بخواهید قانونی را بار کنید که از این حد فراتر می‌رود، هشداری مانند زیر خواهید دید و قانون نادیده گرفته خواهد شد.

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 browser.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await browser.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 browser.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 > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

نمونه‌های قانون

مثال‌های زیر نشان می‌دهند که Chrome چگونه قوانین را در افزونه اولویت‌بندی می‌کند. هنگام مرور آن‌ها، ممکن است بخواهید قوانین اولویت‌بندی را در پنجره‌ای جداگانه باز کنید.

کلید «اولویت»

این نمونه‌ها به اجازه میزبان برای *://*.example.com/* نیاز دارند.

برای تعیین اولویت یک نشانی وب خاص، به کلید "priority" (تعریف‌شده توسط توسعه‌دهنده)، کلید "action"، و کلید "urlFilter" نگاه کنید. این مثال‌ها به فایل قانون نمونه‌ای که در زیر آن‌ها نشان داده شده است اشاره دارند.

پیمایش به https://google.com: دو قانون این نشانی وب را پوشش می‌دهد: قوانین با شناسه‌های ۱ و ۴. قانون با شناسه ۱ اعمال می‌شود زیرا کنش‌های "block" اولویت بالاتری نسبت‌به کنش‌های "redirect" دارند. قوانین باقی‌مانده اعمال نمی‌شوند زیرا برای نشانی‌های وب طولانی‌تر هستند.
پیمایش به https://google.com/1234: به‌دلیل طولانی‌تر بودن نشانی وب، قانون با شناسه ۲ اکنون علاوه‌بر قانون‌های با شناسه ۱ و ۴ مطابقت دارد. قانون با شناسه ۲ اعمال می‌شود زیرا "allow" اولویت بالاتری نسبت‌به "block" و "redirect" دارد.
پیمایش به https://google.com/12345: هر چهار قانون با این نشانی وب مطابقت دارد. قانون با شناسه ۳ اعمال می‌شود زیرا اولویت تعریف‌شده توسط توسعه‌دهنده آن بالاترین اولویت در گروه است.

[
  {
    "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» از نشانی وب هدایت‌شده گرفته می‌شود و در جایگزینی قرار می‌گیرد.

{
  "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) آن با قابی که درخواست در آن ایجاد شده است یکسان باشد.

شمارشی

«firstParty»
درخواست شبکه، طرف اول قابی است که در آن ایجاد شده است.

«thirdParty»
درخواست شبکه نسبت به قابی که در آن ایجاد شده است، طرف سوم است.

ExtensionActionOptions

Chrome 88+ browser.* از Chrome 148

مشخصات

displayActionCountAsBadgeText

بولی اختیاری

آیا تعداد کنش‌های یک صفحه به‌طور خودکار به‌عنوان نوشتار نشان افزونه نمایش داده شود یا نه. این اولویت در جلسات مختلف حفظ می‌شود.
tabUpdate

TabActionCountUpdate اختیاری

Chrome نسخه ۸۹ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

جزئیات نحوه تنظیم تعداد کنش‌های برگه.

GetDisabledRuleIdsOptions

Chrome 111+ browser.* از Chrome 148

مشخصات

rulesetId

رشته

شناسه مربوط به Ruleset ایستا.

GetRulesFilter

Chrome 111+ browser.* از Chrome 148

مشخصات

ruleIds

number[] اختیاری

اگر مشخص شده باشد، فقط قوانینی که شناسه‌های منطبق دارند گنجانده می‌شود.

HeaderInfo

‫Chrome نسخه ۱۲۸ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

excludedValues

رشته[] اختیاری

اگر مشخص شده باشد، درصورتی‌که سرصفحه وجود داشته باشد اما مقدار آن حاوی حداقل یک عنصر در این فهرست باشد، این شرط مطابقت داده نمی‌شود. این مورد از همان نحو الگوی مطابقت values استفاده می‌کند.
سرصفحه

رشته

نام سرایند. این شرط فقط درصورتی با نام مطابقت دارد که values و excludedValues مشخص نشده باشند.
مقادیر

رشته[] اختیاری

اگر مشخص شده باشد، این شرط درصورتی مطابقت دارد که مقدار سرصفحه با حداقل یک الگو در این فهرست مطابقت داشته باشد. این گزینه از مطابقت مقدار سرایند غیرحساس به حروف بزرگ و کوچک به‌علاوه ساختارهای زیر پشتیبانی می‌کند:

«*» : با هر تعداد نویسه مطابقت دارد.

«؟» : با صفر یا یک نویسه مطابقت دارد.

«*» و «؟» را می‌توان با واکج‌خط گریزاند، مثلاً «\*» و «\؟»

HeaderOperation

Chrome نسخه ۸۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

این بخش عملیات ممکن برای قانون «modifyHeaders» را شرح می‌دهد.

شمارشی

«append»
ورودی جدیدی برای سرایند مشخص‌شده اضافه می‌کند. هنگام اصلاح سرایندهای درخواست، این عملیات فقط برای سرایندهای خاص پشتیبانی می‌شود.

«set»
مقدار جدیدی برای سرصفحه مشخص‌شده تنظیم می‌کند و هرگونه سرصفحه موجود با همان نام را برمی‌دارد.

«remove»
همه ورودی‌های سرصفحه مشخص‌شده را برمی‌دارد.

IsRegexSupportedResult

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

isSupported

بولی
دلیل

UnsupportedRegexReason اختیاری

دلیل پشتیبانی نشدن عبارت باقاعده را مشخص می‌کند. فقط درصورتی ارائه می‌شود که isSupported نادرست باشد.

MatchedRule

مشخصات

ruleId

شماره

شناسه قانون منطبق.
rulesetId

رشته

شناسه Ruleset که این قانون به آن تعلق دارد. برای قانونی که از مجموعه قوانین پویا منشأ می‌گیرد، این مقدار برابر با DYNAMIC_RULESET_ID خواهد بود.

MatchedRuleInfo

مشخصات

قانون

MatchedRule
tabId

شماره

tabId زبانه‌ای که درخواست از آن منشأ گرفته است، اگر زبانه هنوز فعال باشد. Else -1.
timeStamp

شماره

زمانی که قانون مطابقت داده شد. مُهرهای زمان با قرارداد جاوا اسکریپت برای زمان‌ها مطابقت خواهند داشت، یعنی تعداد میلی‌ثانیه‌ها از تاریخ.

MatchedRuleInfoDebug

مشخصات

درخواست کردن

RequestDetails

جزئیات مربوط به درخواستی که قانون با آن مطابقت دارد.
قانون

MatchedRule

MatchedRulesFilter

مشخصات

minTimeStamp

شماره اختیاری

اگر مشخص شده باشد، فقط با قوانین پس‌از مُهر زمان داده‌شده مطابقت دارد.
tabId

شماره اختیاری

اگر مشخص شده باشد، فقط با قوانین برگه ارائه‌شده مطابقت دارد. اگر روی ‎-1 تنظیم شده باشد، با قوانینی که با هیچ برگه فعالی مرتبط نیستند مطابقت دارد.

ModifyHeaderInfo

Chrome نسخه ۸۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

مشخصات

سرصفحه

رشته

نام سرایندی که باید اصلاح شود.
عملیات

HeaderOperation

عملیاتی که باید روی سرصفحه انجام شود.
مقدار

رشته اختیاری

مقدار جدید برای سرایند. باید برای عملیات append و set مشخص شود.

QueryKeyValue

مشخصات

کلید

رشته
replaceOnly

بولی اختیاری

Chrome نسخه ۹۴ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

اگر درست باشد، کلید پُرسمان فقط درصورتی جایگزین می‌شود که ازقبل وجود داشته باشد. درغیراین‌صورت، اگر کلید وجود نداشته باشد، اضافه می‌شود. پیش‌فرض: نادرست.
مقدار

رشته

QueryTransform

مشخصات

addOrReplaceParams

QueryKeyValue[] اختیاری

فهرست جفت‌های کلید-مقدار پُرسمان برای افزودن یا جایگزین کردن.
removeParams

رشته[] اختیاری

فهرست کلیدهای پُرسمان برای برداشته شدن.

Redirect

مشخصات

extensionPath

رشته اختیاری

مسیر مرتبط با دایرکتوری افزونه. باید با «/» شروع شود.
regexSubstitution

رشته اختیاری

الگوی جایگزینی برای قوانینی که regexFilter را مشخص می‌کنند. اولین تطابق regexFilter در نشانی وب با این الگو جایگزین خواهد شد. در regexSubstitution، می‌توان از ارقام با واکج‌خط گریز (\1 تا \9) برای درج گروه‌های ضبط متناظر استفاده کرد. \0 به کل نوشتار منطبق اشاره دارد.
تبدیل کردن

URLTransform اختیاری

تبدیل‌های نشانی وب برای اجرا.
نشانی وب

رشته اختیاری

نشانی وب هدایتگر. هدایت به نشانی‌های وب جاوا اسکریپت مجاز نیست.

RegexOptions

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

isCaseSensitive

بولی اختیاری

آیا regex مشخص‌شده حروف‌حساس است یا نه. پیش‌فرض «درست» است.
عبارت باقاعده

رشته

عبارت باقاعده برای بررسی.
requireCapturing

بولی اختیاری

اینکه آیا regex مشخص‌شده به ضبط نیاز دارد یا نه. ضبط فقط برای قوانین تغییرمسیر که کنش regexSubstition را مشخص می‌کنند لازم است. پیش‌فرض false است.

RequestDetails

مشخصات

documentId

رشته اختیاری

Chrome 106+ browser.* از Chrome 148

شناسه یکتای سند قاب، اگر این درخواست برای قاب باشد.
documentLifecycle

DocumentLifecycle اختیاری

Chrome 106+ browser.* از Chrome 148

چرخه حیات سند قاب، اگر این درخواست برای قاب باشد.
frameId

شماره

مقدار ۰ نشان می‌دهد که درخواست در قاب اصلی اتفاق می‌افتد؛ مقدار مثبت نشان‌دهنده شناسه قاب فرعی است که درخواست در آن اتفاق می‌افتد. اگر سند یک (زیر)قاب بار شود (type main_frame یا sub_frame است)، frameId شناسه این قاب را نشان می‌دهد، نه شناسه قاب بیرونی را. شناسه‌های قاب در هر برگه یکتا هستند.
frameType

FrameType اختیاری

Chrome 106+ browser.* از Chrome 148

نوع قاب، اگر این درخواست برای قاب باشد.
آغازگر

رشته اختیاری

مبدأی که درخواست از آنجا آغاز شده است. این مورد با تغییر مسیر تغییر نمی‌کند. اگر این مبدأ مبهم باشد، از رشته «null» استفاده خواهد شد.
روش

رشته

روش HTTP استاندارد.
parentDocumentId

رشته اختیاری

Chrome 106+ browser.* از Chrome 148

شناسه یکتای سند ولی قاب، اگر این درخواست برای قاب باشد و ولی داشته باشد.
parentFrameId

شماره

شناسه قابی که قاب ارسال‌کننده درخواست را دربرمی‌گیرد. اگر قاب ولی وجود نداشته باشد، روی ۱- تنظیم می‌شود.
requestId

رشته

شناسه درخواست. شناسه‌های درخواست در یک جلسه مرورگر منحصربه‌فرد هستند.
tabId

شماره

شناسه زبانه‌ای که درخواست در آن انجام می‌شود. اگر درخواست به برگه‌ای مربوط نیست، روی ‎-1 تنظیم کنید.
نوع

ResourceType

نوع منبع درخواست.
نشانی وب

رشته

نشانی وب درخواست.

RequestMethod

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

این روش درخواست HTTP را برای درخواست شبکه شرح می‌دهد.

شمارشی

«متصل شدن»

«delete»

«get»

"head"

«گزینه‌ها»

"patch"

«پست»

«put»

«دیگر»

ResourceType

این نوع منبع درخواست شبکه را شرح می‌دهد.

شمارشی

"main_frame"

"sub_frame"

«stylesheet»

«script»

"image"

"font"

«شیء»

"xmlhttprequest"

"ping"

"csp_report"

«رسانه»

"websocket"

"webtransport"

"webbundle"

«دیگر»

Rule

مشخصات

کنش

RuleAction

کنشی که درصورت مطابقت با این قانون باید انجام شود.
شرط

RuleCondition

شرایطی که تحت آن این قانون راه‌اندازی می‌شود.
id

شماره

شناسه‌ای که به‌طور یکتا قانونی را مشخص می‌کند. اجباری است و باید >= ۱ باشد.
اولویت‌دار

شماره اختیاری

اولویت قانون. پیش‌فرض ۱ است. درصورت مشخص شدن، باید >= ۱ باشد.

RuleAction

مشخصات

هدایت کردن

هدایت کردن اختیاری

نحوه انجام تغییرمسیر را شرح می‌دهد. فقط برای قوانین تغییرمسیر معتبر است.
requestHeaders

ModifyHeaderInfo[] اختیاری

Chrome نسخه ۸۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

سرصفحه‌های درخواست برای اصلاح درخواست. فقط درصورتی معتبر است که RuleActionType برابر با «modifyHeaders» باشد.
responseHeaders

ModifyHeaderInfo[] اختیاری

Chrome نسخه ۸۶ و بالاتر browser.* از Chrome نسخه ۱۴۸

سرایندهای پاسخ برای اصلاح درخواست. فقط درصورتی معتبر است که RuleActionType برابر با «modifyHeaders» باشد.
نوع

RuleActionType

نوع کنشی که باید انجام شود.

RuleActionType

نوع اقدامی را که باید درصورت مطابقت RuleCondition داده‌شده انجام شود شرح می‌دهد.

شمارشی

«block»
درخواست شبکه را مسدود می‌کند.

«redirect»
درخواست شبکه را هدایت می‌کند.

«allow»
درخواست شبکه را مجاز می‌کند. اگر قانون مجاز کردن با درخواست مطابقت داشته باشد، درخواست رهگیری نخواهد شد.

"upgradeScheme"
اگر درخواست http یا ftp باشد، طرح نشانی وب درخواست شبکه را به https ارتقا می‌دهد.

«modifyHeaders»
سرایندهای درخواست/پاسخ را از درخواست شبکه اصلاح کنید.

«allowAllRequests»
همه درخواست‌ها را در سلسله‌مراتب قاب، ازجمله خود درخواست قاب، مجاز می‌کند.

RuleCondition

مشخصات

domainType

DomainType اختیاری

مشخص می‌کند که درخواست شبکه نسبت به دامنه‌ای که از آن منشأ گرفته است، شخص اول است یا شخص ثالث. اگر حذف شود، همه درخواست‌ها پذیرفته می‌شود.
دامنه‌ها

رشته[] اختیاری

از Chrome 101 منسوخ شده است

درعوض از initiatorDomains استفاده کنید
این قانون فقط با درخواست‌های شبکه که از فهرست domains منشأ می‌گیرند مطابقت خواهد داشت.
excludedDomains

رشته[] اختیاری

از Chrome 101 منسوخ شده است

درعوض از excludedInitiatorDomains استفاده کنید
این قانون با درخواست‌های شبکه که از فهرست excludedDomains منشأ می‌گیرند مطابقت نخواهد داشت.
excludedInitiatorDomains

رشته[] اختیاری

Chrome نسخه ۱۰۱ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

این قانون با درخواست‌های شبکه که از فهرست excludedInitiatorDomains منشأ می‌گیرند مطابقت نخواهد داشت. اگر فهرست خالی باشد یا حذف شده باشد، هیچ دامنه‌ای مستثنی نمی‌شود. این بر initiatorDomains اولویت دارد.

نکته‌ها:
- زیردامنه‌هایی مثل «a.example.com» نیز مجاز است.
- ورودی‌ها باید فقط شامل نویسه‌های ASCII باشد.
- برای دامنه‌های بین‌المللی‌شده از کدگذاری punycode استفاده کنید.
- این مورد با آغازگر درخواست مطابقت دارد و نه با نشانی وب درخواست.
- زیردامنه‌های دامنه‌های فهرست‌شده نیز مستثنی می‌شوند.
excludedRequestDomains

رشته[] اختیاری

Chrome نسخه ۱۰۱ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

وقتی دامنه‌ها با یکی از موارد موجود در فهرست excludedRequestDomains مطابقت داشته باشد، این قانون با درخواست‌های شبکه مطابقت نخواهد داشت. اگر فهرست خالی باشد یا حذف شده باشد، هیچ دامنه‌ای مستثنی نمی‌شود. این بر requestDomains اولویت دارد.

نکته‌ها:
- زیردامنه‌هایی مثل «a.example.com» نیز مجاز است.
- ورودی‌ها باید فقط شامل نویسه‌های ASCII باشد.
- برای دامنه‌های بین‌المللی‌شده از کدگذاری punycode استفاده کنید.
- زیردامنه‌های دامنه‌های فهرست‌شده نیز مستثنی می‌شوند.
excludedRequestMethods

RequestMethod[] اختیاری

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

فهرست روش‌های درخواست که قانون با آن‌ها مطابقت نخواهد داشت. فقط یکی از requestMethods و excludedRequestMethods باید مشخص شود. اگر هیچ‌کدام مشخص نشده باشد، همه روش‌های درخواست مطابقت داده می‌شود.
excludedResourceTypes

ResourceType[] اختیاری

فهرست انواع منابعی که قانون با آن‌ها مطابقت ندارد. فقط یکی از resourceTypes و excludedResourceTypes باید مشخص شود. اگر هیچ‌کدام مشخص نشده باشد، همه انواع منبع به‌جز «main_frame» مسدود می‌شود.
excludedResponseHeaders

HeaderInfo[] اختیاری

‫Chrome نسخه ۱۲۸ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

اگر درخواست با هریک از شرایط سرایند پاسخ در این فهرست (درصورت مشخص شدن) مطابقت داشته باشد، قانون مطابقت ندارد. اگر هر دو excludedResponseHeaders و responseHeaders مشخص شده باشند، ویژگی excludedResponseHeaders اولویت دارد.
excludedTabIds

number[] اختیاری

Chrome 92+ browser.* از Chrome 148

فهرست tabs.Tab.id که قانون نباید با آن مطابقت داشته باشد. شناسه tabs.TAB_ID_NONE درخواست‌هایی را که از برگه منشأ نمی‌گیرند مستثنی می‌کند. فقط برای قوانین جلسه‌محور پشتیبانی می‌شود.
excludedTopDomains

رشته[] اختیاری

Chrome نسخه ۱۴۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

وقتی دامنه قاب سطح بالای مرتبط با یکی از دامنه‌های موجود در فهرست excludedTopDomains مطابقت داشته باشد، این قانون با درخواست‌های شبکه مطابقت نخواهد داشت. اگر فهرست خالی باشد یا حذف شده باشد، هیچ دامنه‌ای مستثنی نمی‌شود. این بر topDomains اولویت دارد.

نکته‌ها:
- زیردامنه‌هایی مثل «a.example.com» نیز مجاز است.
- ورودی‌ها باید فقط شامل نویسه‌های ASCII باشد.
- برای دامنه‌های بین‌المللی‌شده از کدگذاری punycode استفاده کنید.
- زیردامنه‌های دامنه‌های فهرست‌شده نیز مستثنی می‌شوند.
- برای درخواست‌های بدون قاب سطح بالای مرتبط (مثلاً درخواست‌های آغازشده توسط ServiceWorker)، دامنه آغازگر درخواست به‌جای آن درنظر گرفته می‌شود.
initiatorDomains

رشته[] اختیاری

Chrome نسخه ۱۰۱ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

این قانون فقط با درخواست‌های شبکه که از فهرست initiatorDomains منشأ می‌گیرند مطابقت خواهد داشت. اگر فهرست حذف شود، این قانون برای درخواست‌های همه دامنه‌ها اعمال می‌شود. فهرست خالی مجاز نیست.

نکته‌ها:
- زیردامنه‌هایی مثل «a.example.com» نیز مجاز است.
- ورودی‌ها باید فقط شامل نویسه‌های ASCII باشد.
- برای دامنه‌های بین‌المللی‌شده از کدگذاری punycode استفاده کنید.
- این مورد با آغازگر درخواست مطابقت دارد و نه با نشانی وب درخواست.
- زیردامنه‌های دامنه‌های فهرست‌شده نیز مطابقت داده می‌شوند.
isUrlFilterCaseSensitive

بولی اختیاری

اینکه آیا urlFilter یا regexFilter (هرکدام که مشخص شده است) حروف‌حساس است یا نه. پیش‌فرض false است.
regexFilter

رشته اختیاری

عبارت باقاعده برای مطابقت با نشانی وب درخواست شبکه. این الگو از نحو RE2 پیروی می‌کند.

توجه: فقط یکی از urlFilter یا regexFilter را می‌توان مشخص کرد.

توجه: regexFilter باید فقط از نویسه‌های ASCII تشکیل شده باشد. این با نشانی وبی مطابقت داده می‌شود که میزبان آن در قالب punycode کدبندی شده است (درصورت بین‌المللی بودن دامنه‌ها) و هر نویسه غیر-ascii دیگری در utf-8 کدبندی شده است.
requestDomains

رشته[] اختیاری

Chrome نسخه ۱۰۱ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

این قانون فقط زمانی با درخواست‌های شبکه مطابقت خواهد داشت که دامنه با یکی از دامنه‌های موجود در فهرست requestDomains مطابقت داشته باشد. اگر فهرست حذف شود، این قانون برای درخواست‌های همه دامنه‌ها اعمال می‌شود. فهرست خالی مجاز نیست.

نکته‌ها:
- زیردامنه‌هایی مثل «a.example.com» نیز مجاز است.
- ورودی‌ها باید فقط شامل نویسه‌های ASCII باشد.
- برای دامنه‌های بین‌المللی‌شده از کدگذاری punycode استفاده کنید.
- زیردامنه‌های دامنه‌های فهرست‌شده نیز مطابقت داده می‌شوند.
requestMethods

RequestMethod[] اختیاری

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

فهرست روش‌های درخواست HTTP که قانون می‌تواند با آن‌ها مطابقت داشته باشد. فهرست خالی مجاز نیست.

توجه: مشخص کردن شرط قانون requestMethods درخواست‌های غیر-اچ‌تی‌تی‌پی(اس) را نیز مستثنی می‌کند، درحالی‌که مشخص کردن excludedRequestMethods این کار را نمی‌کند.
resourceTypes

ResourceType[] اختیاری

فهرست انواع منابعی که قانون می‌تواند با آن‌ها مطابقت داشته باشد. فهرست خالی مجاز نیست.

توجه: این مورد باید برای قوانین allowAllRequests مشخص شود و فقط می‌تواند شامل انواع منابع sub_frame و main_frame باشد.
responseHeaders

HeaderInfo[] اختیاری

‫Chrome نسخه ۱۲۸ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

اگر درخواست با هریک از شرایط سرایند پاسخ در این فهرست (درصورت مشخص شدن) مطابقت داشته باشد، قانون مطابقت دارد.
tabIds

number[] اختیاری

Chrome 92+ browser.* از Chrome 148

فهرست tabs.Tab.id که قانون باید با آن مطابقت داشته باشد. شناسه tabs.TAB_ID_NONE با درخواست‌هایی مطابقت دارد که از برگه منشأ نمی‌گیرند. فهرست خالی مجاز نیست. فقط برای قوانین جلسه‌محور پشتیبانی می‌شود.
topDomains

رشته[] اختیاری

Chrome نسخه ۱۴۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

این قانون فقط زمانی با درخواست‌های شبکه مطابقت خواهد داشت که دامنه قاب سطح بالای مرتبط با یکی از موارد موجود در فهرست topDomains مطابقت داشته باشد. اگر فهرست حذف شود، این قانون برای درخواست‌های مرتبط با همه دامنه‌های قاب سطح بالا اعمال می‌شود. فهرست خالی مجاز نیست.

نکته‌ها:
- زیردامنه‌هایی مثل «a.example.com» نیز مجاز است.
- ورودی‌ها باید فقط شامل نویسه‌های ASCII باشد.
- برای دامنه‌های بین‌المللی‌شده از کدگذاری punycode استفاده کنید.
- زیردامنه‌های دامنه‌های فهرست‌شده نیز مطابقت داده می‌شوند.
- برای درخواست‌های بدون قاب سطح بالای مرتبط (مثلاً درخواست‌های آغازشده توسط ServiceWorker)، دامنه آغازگر درخواست به‌جای آن درنظر گرفته می‌شود.
urlFilter

رشته اختیاری

الگویی که با نشانی وب درخواست شبکه مطابقت دارد. ساختارهای پشتیبانی‌شده:

«*» : نویسه عام: با هر تعداد نویسه مطابقت دارد.

«|» : لنگر چپ/راست: اگر در هریک از دو انتهای الگو استفاده شود، به‌ترتیب ابتدا/انتهای نشانی وب را مشخص می‌کند.

'||' : لنگر نام دامنه: اگر در ابتدای الگو استفاده شود، شروع (زیر)دامنه نشانی وب را مشخص می‌کند.

«^» : نویسه جداکننده: این نویسه با هر چیزی به‌جز حرف، رقم، یا یکی از موارد زیر مطابقت دارد: _، -، .، یا %. این الگو با انتهای نشانی وب نیز مطابقت دارد.

بنابراین urlFilter از بخش‌های زیر تشکیل شده است: (لنگر نام دامنه/چپ اختیاری) + الگو + (لنگر راست اختیاری).

اگر حذف شود، همه نشانی‌های وب مطابقت داده می‌شوند. رشته خالی مجاز نیست.

الگویی که با ||* شروع شود مجاز نیست. درعوض از * استفاده کنید.

توجه: فقط یکی از urlFilter یا regexFilter را می‌توان مشخص کرد.

توجه: urlFilter باید فقط از نویسه‌های ASCII تشکیل شده باشد. این با نشانی وبی مطابقت داده می‌شود که میزبان آن در قالب punycode کدبندی شده است (درصورت بین‌المللی بودن دامنه‌ها) و هر نویسه غیر-ascii دیگری در utf-8 کدبندی شده است. برای مثال، وقتی نشانی وب درخواست http://abc.рф?q=ф باشد، urlFilter با نشانی وب http://abc.xn--p1ai/?q=%D1%84 مطابقت داده می‌شود.

RuleConditionKeys

Chrome نسخه ۱۴۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

شمارشی

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

مشخصات

فعال شد

بولی

اینکه آیا مجموعه قوانین به‌طور پیش‌فرض فعال است یا نه.
id

رشته

رشته‌ای غیرخالی که مجموعه قوانین را به‌طور منحصربه‌فرد شناسایی می‌کند. شناسه‌هایی که با «_» شروع می‌شوند برای استفاده داخلی رزرو شده‌اند.
مسیر

رشته

مسیر مجموعه قوانین JSON نسبت به دایرکتوری افزونه.

RulesMatchedDetails

مشخصات

rulesMatchedInfo

MatchedRuleInfo[]

قوانین منطبق با فیلتر ارائه‌شده.

TabActionCountUpdate

Chrome نسخه ۸۹ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

افزایش

شماره

مقداری که باید به تعداد کنش‌های برگه اضافه شود. مقادیر منفی شمارش را کاهش می‌دهد.
tabId

شماره

برگه‌ای که تعداد کنش‌های آن به‌روزرسانی می‌شود.

TestMatchOutcomeResult

Chrome نسخه ۱۰۳ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

matchedRules

MatchedRule[]

قوانینی (درصورت وجود) که با درخواست فرضی مطابقت دارند.

TestMatchRequestDetails

Chrome نسخه ۱۰۳ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

آغازگر

رشته اختیاری

نشانی وب آغازگر (درصورت وجود) برای درخواست فرضی.
روش

RequestMethod اختیاری

روش استاندارد HTTP درخواست فرضی. برای درخواست‌های HTTP به‌طور پیش‌فرض روی «get» تنظیم شده است و برای درخواست‌های غیرHTTP نادیده گرفته می‌شود.
responseHeaders

شیء اختیاری

Chrome نسخه ۱۲۹ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

سرایندهای ارائه‌شده توسط پاسخ فرضی درصورتی‌که درخواست قبل‌از ارسال مسدود یا هدایت نشود. به‌صورت شیئی نشان داده می‌شود که نام سرصفحه را به فهرستی از مقادیر رشته‌ای نگاشت می‌کند. اگر مشخص نشده باشد، پاسخ فرضی سرایندهای پاسخ خالی را برمی‌گرداند که می‌تواند با قوانینی که با عدم وجود سرایندها مطابقت دارند مطابقت داشته باشد. به‌عنوان مثال «{"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}»
tabId

شماره اختیاری

شناسه برگه‌ای که درخواست فرضی در آن انجام می‌شود. لازم نیست با شناسه برگه واقعی مطابقت داشته باشد. پیش‌فرض ‎-1 است، یعنی درخواست به برگه مربوط نیست.
topUrl

رشته اختیاری

Chrome نسخه ۱۴۵ و بالاتر browser.* از Chrome نسخه ۱۴۸

نشانی وب قاب سطح بالای مرتبط (درصورت وجود) برای درخواست.
نوع

ResourceType

نوع منبع درخواست فرضی.
نشانی وب

رشته

نشانی وب درخواست فرضی.

UnsupportedRegexReason

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

دلیل پشتیبانی نشدن عبارت باقاعده ارائه‌شده را شرح می‌دهد.

شمارشی

«syntaxError»
عبارت باقاعده ازنظر نحوی نادرست است یا از ویژگی‌هایی استفاده می‌کند که در نحو RE2 دردسترس نیست.

"memoryLimitExceeded"
عبارت باقاعده از حد مجاز حافظه فراتر رفته است.

UpdateRuleOptions

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

addRules

قانون[] اختیاری

قوانینی که باید اضافه شود.
removeRuleIds

number[] اختیاری

شناسه‌های قوانینی که باید برداشته شوند. شناسه‌های نامعتبر نادیده گرفته خواهد شد.

UpdateRulesetOptions

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

مشخصات

disableRulesetIds

رشته[] اختیاری

مجموعه شناسه‌های مربوط به Ruleset ثابتی که باید غیرفعال شود.
enableRulesetIds

رشته[] اختیاری

مجموعه شناسه‌های مربوط به Ruleset ثابتی که باید فعال شود.

UpdateStaticRulesOptions

Chrome 111+ browser.* از Chrome 148

مشخصات

disableRuleIds

number[] اختیاری

مجموعه شناسه‌های مربوط به قوانین در Ruleset برای غیرفعال کردن.
enableRuleIds

number[] اختیاری

مجموعه شناسه‌های مربوط به قوانین در Ruleset برای فعال کردن.
rulesetId

رشته

شناسه مربوط به Ruleset ایستا.

URLTransform

مشخصات

بخش

رشته اختیاری

قطعه جدید برای درخواست. باید خالی باشد، که در این صورت قطعه موجود پاک می‌شود؛ یا باید با «#» شروع شود.
میزبان

رشته اختیاری

میزبان جدید برای درخواست.
گذرواژه

رشته اختیاری

گذرواژه جدید برای درخواست.
مسیر

رشته اختیاری

مسیر جدید برای درخواست. اگر خالی باشد، مسیر موجود پاک می‌شود.
درگاه

رشته اختیاری

درگاه جدید برای درخواست. اگر خالی باشد، درگاه موجود پاک می‌شود.
پُرسمان

رشته اختیاری

پُرسمان جدید برای درخواست. باید خالی باشد، که در این صورت پُرسمان موجود پاک می‌شود؛ یا باید با «؟» شروع شود.
queryTransform

QueryTransform اختیاری

جفت‌های کلید-مقدار پُرسمان را اضافه، حذف، یا جایگزین کنید.
طرح‌واره

رشته اختیاری

طرح جدید برای درخواست. مقادیر مجاز عبارتند از «http»،‏ «https»،‏ «ftp»، و «chrome-extension».
نام کاربری

رشته اختیاری

نام کاربری جدید برای درخواست.

مشخصات

DYNAMIC_RULESET_ID

شناسه مجموعه قوانین برای قوانین پویای اضافه‌شده توسط افزونه.

مقدار

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

بازه زمانی که در آن می‌توان تماس‌های MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules را برقرار کرد، به دقیقه مشخص شده است. تماس‌های دیگر بلافاصله ناموفق خواهد بود و runtime.lastError تنظیم می‌شود. توجه: تماس‌های getMatchedRules مرتبط با اشاره کاربر از سهمیه معاف هستند.

مقدار

‫۱۰

GUARANTEED_MINIMUM_STATIC_RULES

Chrome نسخه ۸۹ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

حداقل تعداد قوانین ایستایی که برای افزونه در سراسر مجموعه‌قوانین ایستای فعال آن تضمین شده است. هر قانونی که بالاتر از این حد باشد، در حد قانون ثابت سراسری لحاظ خواهد شد.

مقدار

۳۰۰۰۰

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

تعداد دفعاتی که می‌توان getMatchedRules را در دوره GETMATCHEDRULES_QUOTA_INTERVAL فراخوانی کرد.

مقدار

MAX_NUMBER_OF_DYNAMIC_RULES

حداکثر تعداد قوانین پویایی که افزونه می‌تواند اضافه کند.

مقدار

۳۰۰۰۰

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome نسخه ۹۴ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

حداکثر تعداد Rulesets ثابتی که افزونه می‌تواند در هر زمان فعال کند.

مقدار

۵۰

MAX_NUMBER_OF_REGEX_RULES

حداکثر تعداد قوانین عبارت باقاعده که افزونه می‌تواند اضافه کند. این محدودیت به‌طور جداگانه برای مجموعه قوانین پویا و قوانین مشخص‌شده در فایل منابع قانون ارزیابی می‌شود.

مقدار

۱۰۰۰

MAX_NUMBER_OF_SESSION_RULES

Chrome نسخه ۱۲۰ و بالاتر browser.* از Chrome نسخه ۱۴۸

حداکثر تعداد قوانین با دامنه جلسه که افزونه می‌تواند اضافه کند.

مقدار

‫۵۰۰۰

MAX_NUMBER_OF_STATIC_RULESETS

حداکثر تعداد Rulesets ثابتی که افزونه می‌تواند به‌عنوان بخشی از کلید مانیفست "rule_resources" مشخص کند.

مقدار

۱۰۰

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome نسخه ۱۲۰ و بالاتر browser.* از Chrome نسخه ۱۴۸

حداکثر تعداد قوانین پویای «ناامن» که افزونه می‌تواند اضافه کند.

مقدار

‫۵۰۰۰

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome نسخه ۱۲۰ و بالاتر browser.* از Chrome نسخه ۱۴۸

حداکثر تعداد قوانین با دامنه جلسه «ناامن» که افزونه می‌تواند اضافه کند.

مقدار

‫۵۰۰۰

SESSION_RULESET_ID

Chrome نسخه ۹۰ به بالا browser.* از Chrome نسخه ۱۴۸

شناسه مجموعه قوانین برای قوانین جلسه‌محور اضافه‌شده توسط افزونه.

مقدار

«_session»

روش‌ها

getAvailableStaticRuleCount()

Chrome نسخه ۸۹ به بالا browser.* ‎ از Chrome نسخه ۱۴۸

browser.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

تعداد قوانین ثابتی را که افزونه می‌تواند قبل‌از رسیدن به محدودیت قانون ثابت سراسری فعال کند برمی‌گرداند.

بازگشتی‌ها

Promise<number>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

getDisabledRuleIds()

Chrome 111+ browser.* از Chrome 148

browser.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

فهرست قوانین ثابتی را که درحال‌حاضر در Ruleset داده‌شده غیرفعال هستند برمی‌گرداند.

پارامترها

گزینه‌ها

GetDisabledRuleIdsOptions

مجموعه قوانین را برای پرسمان مشخص می‌کند.

بازگشتی‌ها

Promise<number[]>

Promise که با فهرستی از شناسه‌های مربوط به قوانین غیرفعال در آن مجموعه قوانین حل می‌شود.

getDynamicRules()

browser.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

مجموعه فعلی قوانین پویا را برای افزونه برمی‌گرداند. تماس‌گیرندگان می‌توانند به‌طور اختیاری فهرست قوانین واکشی‌شده را با مشخص کردن filter فیلتر کنند.

پارامترها

فیلتر کردن

GetRulesFilter اختیاری

Chrome 111+ browser.* از Chrome 148

شیئی برای فیلتر کردن فهرست قوانین واکشی‌شده.

بازگشتی‌ها

Promise<Rule[]>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که با مجموعه قوانین پویا حل می‌شود. درصورت بروز خطاهای داخلی گذرا، ممکن است Promise رد شود.

getEnabledRulesets()

browser.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

شناسه‌های مجموعه کنونی مجموعه‌قوانین ایستا فعال را برمی‌گرداند.

بازگشتی‌ها

Promise<string[]>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که با فهرستی از شناسه‌ها حل می‌شود، که هر شناسه با یک Ruleset ثابت فعال مطابقت دارد.

getMatchedRules()

browser.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

همه قوانین منطبق با افزونه را برمی‌گرداند. تماس‌گیرندگان می‌توانند به‌طور اختیاری فهرست قوانین منطبق را با مشخص کردن filter فیلتر کنند. این روش فقط برای افزونه‌هایی دردسترس است که اجازه "declarativeNetRequestFeedback" را دارند یا اجازه "activeTab" برای tabId مشخص‌شده در filter به آن‌ها اعطا شده است. توجه: قوانینی که با سند فعالی مرتبط نیستند و بیش‌از پنج دقیقه پیش مطابقت داده شده‌اند برگردانده نخواهند شد.

پارامترها

فیلتر کردن

MatchedRulesFilter اختیاری

شیئی برای فیلتر کردن فهرست قوانین منطبق.

بازگشتی‌ها

Promise<RulesMatchedDetails>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که پس‌از واکشی فهرست قوانین منطبق حل‌وفصل می‌شود. درصورت بروز خطا، Promise رد خواهد شد. این اتفاق ممکن است به دلایل مختلفی رخ دهد، مانند مجوزهای ناکافی یا فراتر رفتن از سهمیه.

getSessionRules()

Chrome نسخه ۹۰ به بالا browser.* از Chrome نسخه ۱۴۸

browser.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

مجموعه فعلی قوانین با دامنه جلسه را برای افزونه برمی‌گرداند. تماس‌گیرندگان می‌توانند به‌طور اختیاری فهرست قوانین واکشی‌شده را با مشخص کردن filter فیلتر کنند.

پارامترها

فیلتر کردن

GetRulesFilter اختیاری

Chrome 111+ browser.* از Chrome 148

شیئی برای فیلتر کردن فهرست قوانین واکشی‌شده.

بازگشتی‌ها

Promise<Rule[]>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که با مجموعه قوانین جلسه‌محور حل می‌شود.

isRegexSupported()

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

browser.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

بررسی می‌کند که آیا عبارت باقاعده ارائه‌شده به‌عنوان شرط قانون regexFilter پشتیبانی می‌شود یا نه.

پارامترها

regexOptions

RegexOptions

عبارت باقاعده برای بررسی.

بازگشتی‌ها

Promise<IsRegexSupportedResult>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که با جزئیاتی شامل اینکه آیا عبارت باقاعده پشتیبانی می‌شود یا نه و دلیل آن درصورت عدم پشتیبانی حل می‌شود.

setExtensionActionOptions()

Chrome 88+ browser.* از Chrome 148

browser.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

پیکربندی می‌کند که آیا تعداد کنش‌های برگه‌ها باید به‌عنوان نوشتار نشان کنش افزونه نمایش داده شود یا نه و راهی برای افزایش تعداد کنش‌ها ارائه می‌دهد.

پارامترها

گزینه‌ها

ExtensionActionOptions

بازگشتی‌ها

Promise<void>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

testMatchOutcome()

Chrome نسخه ۱۰۳ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

browser.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

بررسی می‌کند که آیا هیچ‌یک از قوانین declarativeNetRequest افزونه با درخواست فرضی مطابقت دارد یا نه. توجه: فقط برای افزونه‌های ازبسته‌بندی خارج‌شده دردسترس است زیرا فقط برای استفاده درطول توسعه افزونه درنظر گرفته شده است.

پارامترها

درخواست کردن

TestMatchRequestDetails

بازگشتی‌ها

Promise<TestMatchOutcomeResult>

قولی که با جزئیات قوانین مطابقت‌داده‌شده حل می‌شود.

updateDynamicRules()

browser.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

مجموعه فعلی قوانین پویا را برای افزونه اصلاح می‌کند. قوانین با شناسه‌های فهرست‌شده در options.removeRuleIds ابتدا برداشته می‌شوند و سپس قوانین ارائه‌شده در options.addRules اضافه می‌شوند. نکته‌ها:

این به‌روزرسانی به‌عنوان یک عملیات اتمی واحد انجام می‌شود: یا همه قوانین مشخص‌شده اضافه و حذف می‌شوند، یا خطایی برگردانده می‌شود.
این قوانین در جلسه‌های مرورگر و به‌روزرسانی‌های افزونه حفظ می‌شوند.
قوانین ثابتی که به‌عنوان بخشی از بسته افزونه مشخص شده‌اند را نمی‌توان بااستفاده از این تابع حذف کرد.
MAX_NUMBER_OF_DYNAMIC_RULES حداکثر تعداد قوانین پویایی است که افزونه می‌تواند اضافه کند. تعداد قوانین ناامن نباید از MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES بیشتر باشد.

پارامترها

گزینه‌ها

UpdateRuleOptions

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

بازگشتی‌ها

Promise<void>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که پس‌از تکمیل به‌روزرسانی حل می‌شود. درصورت بروز خطا، وعده رد خواهد شد و هیچ تغییری در مجموعه قانون ایجاد نخواهد شد. این اتفاق ممکن است به‌دلایل مختلفی رخ دهد، ازجمله قالب نامعتبر قانون، شناسه قانون تکراری، فراتر رفتن از حد تعداد قانون، خطاهای داخلی، و غیره.

updateEnabledRulesets()

browser.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

مجموعه قوانین ایستا فعال‌شده را برای افزونه به‌روز می‌کند. مجموعه قوانین با شناسه‌های فهرست‌شده در options.disableRulesetIds ابتدا برداشته می‌شوند و سپس مجموعه قوانین فهرست‌شده در options.enableRulesetIds اضافه می‌شوند. توجه داشته باشید که مجموعه مجموعه‌قوانین ایستا فعال‌شده در جلسه‌ها حفظ می‌شود اما در به‌روزرسانی‌های افزونه حفظ نمی‌شود، یعنی کلید مانیفست rule_resources مجموعه مجموعه‌قوانین ایستا فعال‌شده را در هر به‌روزرسانی افزونه تعیین می‌کند.

پارامترها

گزینه‌ها

UpdateRulesetOptions

Chrome نسخه ۸۷ و بالاتر browser.* ‎ از Chrome نسخه ۱۴۸

بازگشتی‌ها

Promise<void>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که پس‌از تکمیل به‌روزرسانی حل می‌شود. درصورت بروز خطا، وعده رد خواهد شد و هیچ تغییری در مجموعه قانون‌های فعال‌شده ایجاد نخواهد شد. این اتفاق ممکن است به دلایل متعددی رخ دهد، مانند شناسه‌های مجموعه قوانین نامعتبر، فراتر رفتن از حد مجاز تعداد قوانین، یا خطاهای داخلی.

updateSessionRules()

Chrome نسخه ۹۰ به بالا browser.* از Chrome نسخه ۱۴۸

browser.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

مجموعه فعلی قوانین با دامنه جلسه را برای افزونه اصلاح می‌کند. قوانین با شناسه‌های فهرست‌شده در options.removeRuleIds ابتدا برداشته می‌شوند و سپس قوانین ارائه‌شده در options.addRules اضافه می‌شوند. نکته‌ها:

این به‌روزرسانی به‌عنوان یک عملیات اتمی واحد انجام می‌شود: یا همه قوانین مشخص‌شده اضافه و حذف می‌شوند، یا خطایی برگردانده می‌شود.
این قوانین در جلسه‌ها حفظ نمی‌شوند و در حافظه پشتیبان‌گیری می‌شوند.
MAX_NUMBER_OF_SESSION_RULES حداکثر تعداد قانون‌های جلسه‌ای است که افزونه می‌تواند اضافه کند.

پارامترها

گزینه‌ها

UpdateRuleOptions

بازگشتی‌ها

Promise<void>

Chrome نسخه ۹۱ و بالاتر browser.* از Chrome نسخه ۱۴۸

Promise که پس‌از تکمیل به‌روزرسانی حل می‌شود. درصورت بروز خطا، وعده رد خواهد شد و هیچ تغییری در مجموعه قانون ایجاد نخواهد شد. این اتفاق ممکن است به دلایل مختلفی رخ دهد، ازجمله قالب نامعتبر قانون، شناسه قانون تکراری، فراتر رفتن از حد مجاز تعداد قانون، و غیره.

updateStaticRules()

Chrome 111+ browser.* از Chrome 148

browser.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

قوانین ثابت جداگانه را در Ruleset غیرفعال و فعال می‌کند. تغییرات در قوانین متعلق به Ruleset غیرفعال‌شده دفعه بعدی که فعال شود اعمال خواهد شد.

پارامترها

گزینه‌ها

UpdateStaticRulesOptions

بازگشتی‌ها

Promise<void>

Promise که پس‌از تکمیل به‌روزرسانی حل می‌شود. درصورت بروز خطا، وعده رد خواهد شد و هیچ تغییری در قوانین ثابت فعال‌شده ایجاد نخواهد شد.

رویدادها

onRuleMatchedDebug

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

وقتی قانونی با درخواستی مطابقت داشته باشد، فعال می‌شود. فقط برای افزونه‌های ازبسته‌خارج‌شده با اجازه "declarativeNetRequestFeedback" دردسترس است، زیرا این ویژگی فقط برای اهداف اشکال‌زدایی درنظر گرفته شده است.

پارامترها

تماس برگشتی

عملکرد

پارامتر callback به‌صورت زیر است:
```
(info: MatchedRuleInfoDebug) => void
```
- اطلاعات
  
  MatchedRuleInfoDebug

browser.declarativeNetRequest با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

شرح

اجازه‌ها

دردسترس بودن

مانیفست

قوانین و مجموعه‌قوانین

مجموعه قوانین پویا و جلسه‌محور

مجموعه قوانین ایستا

بازبینی سریع

فعال و غیرفعال کردن قوانین و مجموعه‌قوانین ایستا

ایجاد قوانین

مطابقت نشانی وب

نحو فیلتر نشانی وب

عبارت‌های باقاعده

نوشتن شرایط نشانی وب خوب

ارزیابی قانون

قبل‌از درخواست

پیش‌از ارسال سرصفحه‌های درخواست

وقتی پاسخی دریافت شد

قوانین ایمن

حدود قانون

قوانین ایستا

قوانین جلسه

قوانین پویا

قوانینی که از عبارت‌های باقاعده استفاده می‌کنند

تعامل با کارگران خدماتی

منابع دردسترس وب

اصلاح سرصفحه

مثال‌ها

نمونه‌های کد

به‌روزرسانی قوانین پویا

به‌روزرسانی مجموعه‌قوانین ایستا

نمونه‌های قانون

کلید «اولویت»

هدایت‌های مجدد

سرایندها

انواع

DomainType

شمارشی

ExtensionActionOptions

مشخصات

GetDisabledRuleIdsOptions

مشخصات

GetRulesFilter

مشخصات

HeaderInfo

مشخصات

HeaderOperation

شمارشی

IsRegexSupportedResult

مشخصات

MatchedRule

مشخصات

MatchedRuleInfo

مشخصات

MatchedRuleInfoDebug

مشخصات

MatchedRulesFilter

مشخصات

ModifyHeaderInfo

مشخصات

QueryKeyValue

مشخصات

QueryTransform

مشخصات

Redirect

مشخصات

RegexOptions

مشخصات

RequestDetails

مشخصات

RequestMethod

شمارشی

ResourceType

شمارشی

Rule

مشخصات

RuleAction

مشخصات

RuleActionType

browser.declarativeNetRequest