此页面由社区从英文翻译而来。了解更多并加入 MDN Web Docs 社区。

View in English Always switch to English

declarativeNetRequest.RuleCondition

declarativeNetRequest.Rule 的 condition 属性,用于决定规则是否匹配请求的条件细节。

类型

该类型的值是对象,包含以下属性:

domainType 可选

string。指定网络请求是其源域的第一方还是第三方请求。如果省略,则接受所有请求。可能的值为 "firstParty" 和 "thirdParty"。

domains 可选

string 数组。请使用 initiatorDomains 代替。规则仅匹配源自此域名列表的网络请求。

excludedDomains 可选

string 数组。请使用 excludedInitiatorDomains 代替。规则不匹配源自此域名列表的网络请求。

initiatorDomains 可选

string 数组。规则仅匹配源自此域名列表的网络请求。如果省略该列表,则规则适用于所有域名的请求。不允许使用空列表。应使用规范域名。这与请求发起者而不是请求 URL 匹配。

excludedInitiatorDomains 可选

string 数组。规则不匹配源自此域名列表的网络请求。如果列表为空或省略,则不排除任何域名。这优先于 initiatorDomains。应使用规范域名。这与请求发起者而不是请求 URL 匹配。

isUrlFilterCaseSensitive 可选

boolean。urlFilter 或 regexFilter(指定的任何一个)是否区分大小写。尽管在 WECG issue 269 中,默认值为 false 已在各浏览器中达成共识,但在(较旧的)Chrome 和 Safari 版本中,该值曾为 true。详细信息请参见浏览器兼容性。

regexFilter 可选

string。用于匹配网络请求 URL 的正则表达式。注意:

requestDomains 可选

string 数组。规则仅在域名与此列表中的某个匹配时匹配网络请求。如果省略该列表,则规则适用于所有域名的请求。不允许使用空列表。应使用规范域名。

excludedRequestDomains 可选

string 数组。规则不匹配域名与此列表中的某个匹配的网络请求。如果列表为空或省略,则不排除任何域名。这优先于 requestDomains。应使用规范域名。

requestMethods 可选

string 数组。规则匹配的 HTTP 请求方法列表。不允许使用空列表。指定 requestMethods 规则条件还会排除非 HTTP(s) 请求,而指定 excludedRequestMethods 则不会。

excludedRequestMethods 可选

string 数组。规则不匹配此列表中的请求方法。只能指定 requestMethods 和 excludedRequestMethods 之一。如果两者都未指定,则匹配所有请求方法。

resourceTypes 可选

declarativeNetRequest.ResourceType 数组。规则匹配的资源类型列表。不允许使用空列表。必须为 "allowAllRequests" 规则指定,并且可能仅包含 "sub_frame" 和 "main_frame" 资源类型。

excludedResourceTypes 可选

declarativeNetRequest.ResourceType 数组。规则不匹配的资源类型列表。只能指定 resourceTypes 和 excludedResourceTypes 之一。如果两者都未指定,则阻止除 "main_frame" 之外的所有资源类型。

tabIds 可选

number 数组。规则应匹配的 tabs.Tab.id 列表。tabs.TAB_ID_NONE 的 ID 匹配不来源于选项卡的请求。不允许使用空列表。仅支持会话范围的规则。

excludedTabIds 可选

number 数组。规则不匹配的 tabs.Tab.id 列表。tabs.TAB_ID_NONE 的 ID 排除不来源于选项卡的请求。仅支持会话范围的规则。

urlFilter 可选

string。与网络请求 URL 匹配的模式。支持的结构:

  • * :通配符:匹配任意数量的字符。
  • | :左或右锚:如果在模式的任一端使用,则分别指定 URL 的开头或结尾。
  • || :域名锚:如果在模式的开头使用,则指定 URL 的(子)域的开头。
  • ^ :分隔符字符:这匹配字母、数字或 _、-、.、% 之外的任何内容。最后的 ^ 还可以匹配 URL 的结尾,而不是分隔符字符。

urlFilter 由以下部分组成:(可选的左/域名锚)+ 模式 +(可选的右锚)。如果省略,则匹配所有 URL。不允许使用空字符串。以 ||* 开头的模式不允许使用。请使用 * 代替。注意:

  • 只能指定 urlFilter 或 regexFilter 其中之一。
  • urlFilter 必须仅由 ASCII 字符组成。这与主机编码为国际化域名编码格式的 URL 匹配(在国际化域名的情况下),任何其他非 ASCII 字符都使用 utf-8 进行 URL 编码。例如,当请求 URL 为 http://abc.рф?q=ф 时,urlFilter 与 URL 为 http://abc.xn--p1ai/?q=%D1%84 匹配。

规范域名

在 initiatorDomains、excludedInitiatorDomains、requestDomains 或 excludedRequestDomains 中指定的域应遵循以下规则:

  • 允许子域名,如“a.example.com”。
  • 条目必须仅由小写 ASCII 字符组成。
  • 对于国际化域名,使用国际化域名编码进行编码。
  • IPv4 地址必须表示为由点分隔的 4 个数字。
  • IPv6 地址应表示为规范形式,括在方括号内。

要以编程方式生成 URL 的规范域,请使用 URL API 并读取其 hostname 属性,即 new URL(url).hostname。

示例扩展

浏览器兼容性