说明
chrome.declarativeNetRequest
API 用于通过指定声明式规则来屏蔽或修改网络请求。这样一来,扩展程序就能够修改网络请求,而不会拦截这类请求并查看其中的内容,从而更好地保护用户隐私。
权限
declarativeNetRequest
declarativeNetRequestWithHostAccess
“declarativeNetRequest
”和“declarativeNetRequestWithHostAccess
”权限
它们的功能相同两者的区别在于
请求或同意。
"declarativeNetRequest"
- 在安装时触发权限警告,但提供对以下项目的隐式访问权限
allow
、allowAllRequests
和block
规则。请尽可能使用该功能 需要请求对主机的完整访问权限。 "declarativeNetRequestFeedback"
- 为已解压的扩展程序(特别是
getMatchedRules()
和onRuleMatchedDebug
)启用调试功能。 "declarativeNetRequestWithHostAccess"
- 安装时不会显示权限警告,但您必须请求托管 然后才能对主机执行任何操作。这个 如果您想在 该扩展程序已拥有主机权限,且不会生成额外的 警告。
可用性
清单
除了之前介绍的权限之外,某些类型的规则集(具体而言,是静态规则集)还要求声明 "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/*"
],
...
}
规则和规则集
如需使用此 API,请指定一个或多个规则集。规则集包含一组规则。一条规则会执行以下某项操作:
- 屏蔽网络请求。
- 升级架构(从 http 升级到 https)。
- 通过排除所有匹配的已屏蔽规则来防止请求被屏蔽。
- 重定向网络请求。
- 修改请求或响应标头。
规则集分为三种类型,管理方式略有不同。
- 动态
- 在浏览器会话和扩展程序升级之间保持不变,并在使用扩展程序期间通过 JavaScript 进行管理。
- 会话
- 当浏览器关闭以及安装新版本的扩展程序时被清除。在使用扩展程序时,通过 JavaScript 管理会话规则。
- 静态
- 在安装或升级扩展程序时打包、安装和更新。静态规则存储在 JSON 格式的规则文件中,并列在清单文件中。
动态和会话级范围的规则集
在使用扩展程序时,动态规则集和会话规则集可通过 JavaScript 进行管理。
- 动态规则在浏览器会话和扩展程序升级后保持不变。
- 当浏览器关闭或安装了扩展程序的新版本时,系统会清除会话规则。
这样的规则集类型只有一种。扩展程序可以通过调用 updateDynamicRules()
和 updateSessionRules()
为规则动态添加或移除规则,只要不超过规则限制即可。如需了解规则限制,请参阅规则限制。您可以在代码示例下查看相关示例。
静态规则集
与动态规则和会话规则不同,静态规则会在扩展程序安装或升级时打包、安装和更新。它们存储在 JSON 格式的规则文件中,并使用 "declarative_net_request"
和 "rule_resources"
键(如上所述)以及一个或多个 Ruleset
字典来指示扩展程序。Ruleset
字典包含规则文件的路径、文件中包含的规则集的 ID,以及规则集是已启用还是已停用。在以编程方式启用或停用规则集时,后两项非常重要。
{
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
},
...
]
}
...
}
要测试规则文件,请加载已解压的扩展程序。只有解压缩的扩展程序才可以显示有关无效静态规则的错误和警告。系统会忽略打包的扩展程序中的无效静态规则。
加急审核
对静态规则集所做的更改可能符合加急审核条件。请参阅 加快审核符合条件的更改的速度。
启用和停用静态规则和规则集
单个静态规则和完整的静态规则集都可以在运行时启用或停用。
这组已启用的静态规则和规则集将跨浏览器会话保留。这两者在扩展程序更新后不会保留,也就是说,只有您选择保留在规则文件中的规则在更新后才可用。
出于性能方面的原因,一次可以启用的规则和规则集的数量也有限制。调用 getAvailableStaticRuleCount()
以检查可能启用的其他规则的数量。如需了解规则限制,请参阅规则限制。
如需启用或停用静态规则,请调用 updateStaticRules()
。此方法接受 UpdateStaticRulesOptions
对象,该对象包含要启用或停用的规则 ID 数组。这些 ID 使用 Ruleset
字典的 "id"
键进行定义。停用的静态规则数量上限为 5,000 条。
如需启用或停用静态规则集,请调用 updateEnabledRulesets()
。此方法接受 UpdateRulesetOptions
对象,该对象包含要启用或停用的规则集 ID 数组。这些 ID 使用 Ruleset
字典的 "id"
键进行定义。
构建规则
无论什么类型,规则都从四个字段开始,如下所示。虽然 "id"
和 "priority"
键接受数字,但 "action"
和 "condition"
键可能会提供多种屏蔽和重定向条件。以下规则会屏蔽从 "foo.com"
发送到以 "abc"
作为子字符串的任何网址的所有脚本请求。
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "abc",
"initiatorDomains" : ["foo.com"],
"resourceTypes" : ["script"]
}
}
网址匹配
声明式网络请求支持将网址与格式 匹配语法或正则表达式。
网址过滤器语法
规则的 "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 针对每个请求至多会选择 1 个候选扩展程序。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 时有一些限制具体限制取决于 您使用的规则
静态规则
静态规则是在清单文件中声明的规则文件中指定的规则。一个扩展程序最多可以指定 100 个静态规则集作为 "rule_resources"
清单键的一部分,但一次只能启用 50 个规则集。后者称为 MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
。这些规则集总共保证至少 30,000 条规则。这称为 GUARANTEED_MINIMUM_STATIC_RULES
。
之后可用的规则数量取决于用户浏览器中安装的所有扩展程序启用的规则数量。您可以在运行时通过调用 getAvailableStaticRuleCount()
找到此数字。您可以在代码示例下查看相关示例。
会话规则
一个扩展程序最多可以有 5,000 条会话规则。这作为
MAX_NUMBER_OF_SESSION_RULES
。
在 Chrome 120 之前,动态规则和会话规则的总和不得超过 5, 000 条。
动态规则
一个附加信息可以有至少 5,000 条动态规则。这作为
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
。
从 Chrome 121 开始,适用于安全的动态规则的规则增加了 3 万条,
显示为 MAX_NUMBER_OF_DYNAMIC_RULES
。不限
数量不超过 5,000 条的不安全规则也会计入此限制。
在 Chrome 120 之前,动态规则和会话规则的总数上限为 5, 000。
使用正则表达式的规则
所有类型的规则都可以使用正则表达式;不过,每种类型的正则表达式规则的总数不能超过 1000 个。这称为 MAX_NUMBER_OF_REGEX_RULES。
此外,每条规则在编译后必须小于 2KB。这与规则的复杂程度大致相关。如果您尝试加载的规则超过此限制,则会看到如下所示的警告,并忽略该规则。
rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.
与 Service Worker 的交互
declarativeNetRequest 仅适用于到达网络堆栈的请求。这包括来自 HTTP 缓存的响应,但可能不包括经过 Service Worker 的 onfetch
处理程序的响应。declarativeNetRequest 不会影响 Service Worker 生成或从 CacheStorage
检索到的响应,但会影响 Service Worker 中对 fetch()
的调用。
可通过网络访问的资源
declarativeNetRequest 规则无法从公开资源请求重定向到不可网络访问的资源。这样做会触发错误。即使指定的 Web 可访问资源归重定向扩展程序所有,也是如此。如需为 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/*
的主机权限。
若要确定特定网址的优先级,请查看(开发者定义的)"priority"
键、"action"
键和 "urlFilter"
键。以下示例是下面显示的规则文件示例。
- 导航到 https://google.com
- 有两个规则涵盖此网址:ID 为 1 和 4 的规则。系统会应用 ID 为 1 的规则,因为
"block"
操作的优先级高于"redirect"
操作。其余规则不适用,因为这些规则适用于较长的网址。 - 导航到 https://google.com/1234
- 由于网址更长,现在除了 ID 为 1 和 4 的规则之外,系统还会匹配 ID 为 2 的规则。系统会应用 ID 为 2 的规则,因为
"allow"
的优先级高于"block"
和"redirect"
。 - 导航到 https://google.com/12345
- 四条规则都与此网址匹配。系统会应用 ID 为 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
是您的扩展程序的 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 且采用任何架构的请求。"transform"
中的 "scheme"
键用于指定重定向到子网域的将始终使用“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"
]
}
}
标头
以下示例从主框架和所有子框架中移除所有 Cookie。
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [{ "header": "cookie", "operation": "remove" }]
},
"condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}
类型
DomainType
此属性用于说明请求是发起请求的帧的第一方还是第三方请求。如果请求与发起请求的帧具有相同的域名 (eTLD+1),则该请求称为第一方请求。
枚举
"firstParty"
网络请求是其来源帧的第一方。
"thirdParty"
网络请求是其来源帧的第三方。
ExtensionActionOptions
属性
-
displayActionCountAsBadgeText
布尔值(可选)
是否自动将某网页的操作数显示为扩展程序的标志文字。此偏好设置在不同会话之间保持不变。
-
tabUpdateChrome 89 及更高版本
有关如何调整标签页操作数的详细信息。
GetDisabledRuleIdsOptions
属性
-
rulesetId
字符串
与静态
Ruleset
对应的 ID。
GetRulesFilter
属性
-
ruleIds
number[](选填)
如果指定,则仅包括具有匹配 ID 的规则。
HeaderInfo
属性
-
excludedValues
string[] 选填
如果指定,则当标头存在但其值至少包含此列表中的一个元素时,此条件不匹配。它使用的匹配模式语法与
values
相同。 -
标头
字符串
标头的名称。仅当
values
和excludedValues
均未指定时,此条件才与名称匹配。 -
值
string[] 选填
指定后,如果标头的值与此列表中的至少一个模式匹配,则此条件匹配。这支持不区分大小写的标头值匹配以及以下结构:
'*':匹配任意数量的字符。
'?':匹配 0 个或 1 个字符。
“*”和“?”可以使用反斜杠进行转义,例如“\*”和“\?”
HeaderOperation
它描述了“modifyHeaders”规则。
枚举
"append"
为指定的标头添加新条目。请求标头不支持此操作。
"set"
为指定的标头设置新值,并移除任何同名的现有标头。
"remove"
移除指定标头的所有条目。
IsRegexSupportedResult
属性
-
isSupported
布尔值
-
reason
说明正则表达式不受支持的原因。仅当
isSupported
为 false 时提供。
MatchedRule
属性
-
ruleId
number
匹配规则的 ID。
-
rulesetId
字符串
此规则所属的
Ruleset
的 ID。对于源自一组动态规则的规则,此值等于DYNAMIC_RULESET_ID
。
MatchedRuleInfo
属性
-
规则
-
tabId
number
从中发起请求的标签页的 tabId(如果标签页仍处于活动状态)。否则 -1。
-
timeStamp
number
规则的匹配时间。时间戳将对应于 JavaScript 的时间惯例,即从公元纪年开始计算的毫秒数。
MatchedRuleInfoDebug
属性
-
request
与规则匹配的请求的详细信息。
-
规则
MatchedRulesFilter
属性
-
minTimeStamp
编号(选填)
如果指定,则仅匹配给定时间戳之后的规则。
-
tabId
编号(选填)
指定后,将仅匹配指定标签页的规则。如果设置为 -1,则匹配未与任何活跃标签页关联的规则。
ModifyHeaderInfo
属性
-
标头
字符串
要修改的标头的名称。
-
要对标头执行的操作。
-
值
字符串(可选)
标头的新值。必须为
append
和set
操作指定。
QueryKeyValue
属性
-
键
字符串
-
replaceOnly
布尔值(可选)
Chrome 94 及更高版本如果为 true,则仅替换已存在的查询键。否则,如果缺少该密钥,系统也会添加该密钥。默认值为 false。
-
值
字符串
QueryTransform
属性
-
addOrReplaceParams
QueryKeyValue[] 选填
要添加或替换的查询键值对的列表。
-
removeParams
string[] 选填
要移除的查询键的列表。
Redirect
属性
-
extensionPath
字符串(可选)
相对于扩展程序目录的路径。应以“/”开头。
-
regexSubstitution
字符串(可选)
指定
regexFilter
的规则的替代模式。网址中第一个regexFilter
匹配项将替换为此格式。在regexSubstitution
中,可以使用反斜杠转义的数字(\1 到 \9)插入相应的捕获组。\0 是指整个匹配的文本。 -
转换
URLTransform 可选
要执行的网址转换。
-
网址
字符串(可选)
重定向网址。不允许重定向到 JavaScript 网址。
RegexOptions
属性
-
isCaseSensitive
布尔值(可选)
指定的
regex
是否区分大小写。默认值为 true。 -
regex
字符串
要检查的常规 Expresson。
-
requireCapturing
布尔值(可选)
指定的
regex
是否需要捕获。只有指定regexSubstition
操作的重定向规则才需要捕获。默认值为 false。
RequestDetails
属性
-
documentId
字符串(可选)
Chrome 106 及更高版本帧文档的唯一标识符(如果此请求针对的是帧)。
-
documentLifecycleChrome 106 及更高版本
帧文档的生命周期(如果此请求针对的是帧)。
-
frameId
number
值 0 表示请求发生在主帧中;正值表示请求发生所在的子帧的 ID。如果(子)帧的文档已加载(
type
为main_frame
或sub_frame
),则frameId
表示此帧的 ID,而不是外帧的 ID。帧 ID 在标签页中是唯一的。 -
frameType
FrameType 可选
Chrome 106 及更高版本帧的类型(如果此请求针对的是帧)。
-
发起者
字符串(可选)
发起请求的来源。这一点不会因为重定向而改变。如果此原点是不透明的,则字符串“null”。
-
method
字符串
标准 HTTP 方法。
-
parentDocumentId
字符串(可选)
Chrome 106 及更高版本框架的父级文档的唯一标识符(如果此请求针对的是框架并且有父级)。
-
parentFrameId
number
封装发送请求的帧的帧的 ID。如果不存在父帧,则设置为 -1。
-
requestId
字符串
请求的 ID。请求 ID 在浏览器会话中是唯一的。
-
tabId
number
发生请求的标签页的 ID。如果请求与标签页无关,请将其设为 -1。
-
类型
请求的资源类型。
-
网址
字符串
请求的网址。
RequestMethod
它描述了网络请求的 HTTP 请求方法。
枚举
"连接"
“删除”
"get"
"head"
"选项"
"补丁"
“post”
“put”
“其他”
ResourceType
它描述了网络请求的资源类型。
枚举
“main_frame”
“sub_frame”
“stylesheet”
"script"
“图片”
"字体"
“对象”
"xmlhttprequest"
“ping”
"csp_report"
“media”
"websocket"
"webtransport"
"webbundle"
“其他”
Rule
属性
-
action
规则匹配时要执行的操作。
-
condition
触发此规则的条件。
-
id
number
唯一标识规则的 ID。必需属性,应 >= 1。
-
优先级
编号(选填)
规则优先级。默认为1。指定时,应大于等于 1。
RuleAction
属性
-
重定向
重定向(可选)
用于说明应如何执行重定向。仅对重定向规则有效。
-
requestHeaders
ModifyHeaderInfo[] 可选
Chrome 86 及更高版本要为请求修改的请求标头。仅在 RuleActionType 为“modifyHeaders”时有效。
-
responseHeaders
ModifyHeaderInfo[] 可选
Chrome 86 及更高版本要为请求修改的响应标头。仅在 RuleActionType 为“modifyHeaders”时有效。
-
要执行的操作类型。
RuleActionType
描述给定 RuleCondition 匹配时要执行的操作类型。
枚举
"block"
屏蔽网络请求。
"redirect"
重定向网络请求。
"allow"
允许网络请求。如果有匹配的允许规则,该请求不会被拦截。
"upgradeScheme"
如果请求是 http 或 FTP,请将网络请求网址的架构升级到 https。
"modifyHeaders"
修改网络请求中的请求/响应标头。
"allowAllRequests"
允许框架层次结构中的所有请求,包括框架请求本身。
RuleCondition
属性
-
domainType
DomainType 选填
指定网络请求是来自其来源网域的第一方还是第三方请求。如果省略,则会接受所有请求。
-
网域
string[] 选填
<ph type="x-smartling-placeholder"></ph> 自 Chrome 101 起弃用该规则将仅匹配来自
domains
列表的网络请求。 -
excludedDomains
string[] 选填
<ph type="x-smartling-placeholder"></ph> 自 Chrome 101 起弃用该规则不会匹配来自
excludedDomains
列表的网络请求。 -
excludedInitiatorDomains
string[] 选填
Chrome 浏览器 101 及以上版本该规则不会匹配来自
excludedInitiatorDomains
列表的网络请求。如果列表为空或被省略,系统不会排除任何网域。它的优先级高于initiatorDomains
。注意:
- 类似“a.example.com”的子网域。
- 条目必须仅包含 ASCII 字符。
- 对国际化域名使用 Punycode 编码。
- 此值与请求发起者匹配,与请求网址不匹配。
- 所列网域的子网域也会被排除在外。
-
excludedRequestDomains
string[] 选填
Chrome 浏览器 101 及以上版本当网域与
excludedRequestDomains
列表中的某个网域匹配时,规则不会与网络请求匹配。如果列表为空或被省略,系统不会排除任何网域。它的优先级高于requestDomains
。注意:
- 类似“a.example.com”的子网域。
- 条目必须仅包含 ASCII 字符。
- 对国际化域名使用 Punycode 编码。
- 所列网域的子网域也会被排除在外。
-
excludedRequestMethods
RequestMethod[] 可选
Chrome 91 及更高版本规则不匹配的请求方法列表。只应指定
requestMethods
和excludedRequestMethods
中的一个。如果二者均未指定,则匹配所有请求方法。 -
excludedResourceTypes
ResourceType[] 选填
规则不匹配的资源类型列表。只应指定
resourceTypes
和excludedResourceTypes
中的一个。如果两者均未指定,则使用除“main_frame”以外的所有资源类型已被屏蔽。 -
excludedResponseHeaders
HeaderInfo[] 选填
Chrome 128 及更高版本如果请求符合此列表中的任何响应标头条件(如果已指定),则规则不匹配。如果同时指定了
excludedResponseHeaders
和responseHeaders
,则excludedResponseHeaders
属性优先。 -
excludedTabIds
number[](选填)
Chrome 92 及更高版本规则不匹配的
tabs.Tab.id
的列表。ID 为tabs.TAB_ID_NONE
会排除并非来自标签页的请求。仅适用于会话级范围的规则。 -
initiatorDomains
string[] 选填
Chrome 浏览器 101 及以上版本该规则将仅匹配来自
initiatorDomains
列表的网络请求。如果省略此列表,规则会应用于来自所有网域的请求。不允许使用空列表。注意:
- 类似“a.example.com”的子网域。
- 条目必须仅包含 ASCII 字符。
- 对国际化域名使用 Punycode 编码。
- 此值与请求发起者匹配,与请求网址不匹配。
- 系统还会匹配所列网域的子网域。
-
isUrlFilterCaseSensitive
布尔值(可选)
urlFilter
或regexFilter
(所指定的值)是否区分大小写。默认值为 false。 -
regexFilter
字符串(可选)
用于与网络请求网址匹配的正则表达式。这遵循 RE2 语法。
注意:只能指定
urlFilter
和regexFilter
中的一个。注意:
regexFilter
只能包含 ASCII 字符。这会与主机以 Punycode 格式编码(如果是国际化域名)的网址相匹配,而任何其他非 ASCII 字符都将以 UTF-8 编码的网址进行匹配。 -
requestDomains
string[] 选填
Chrome 浏览器 101 及以上版本只有当网域与
requestDomains
列表中的某个网域匹配时,该规则才会匹配网络请求。如果省略此列表,规则会应用于来自所有网域的请求。不允许使用空列表。注意:
- 类似“a.example.com”的子网域。
- 条目必须仅包含 ASCII 字符。
- 对国际化域名使用 Punycode 编码。
- 系统还会匹配所列网域的子网域。
-
requestMethods
RequestMethod[] 可选
Chrome 91 及更高版本规则可以匹配的 HTTP 请求方法列表。不允许使用空列表。
注意:指定
requestMethods
规则条件也会排除非 HTTP(s) 请求,而指定excludedRequestMethods
不会排除。 -
resourceTypes
ResourceType[] 选填
规则可以匹配的资源类型列表。不允许使用空列表。
注意:必须为
allowAllRequests
规则指定此字段,并且只能包含sub_frame
和main_frame
资源类型。 -
responseHeaders
HeaderInfo[] 选填
Chrome 128 及更高版本如果请求符合此列表中的任何响应标头条件(如果已指定),则规则匹配。
-
tabIds
number[](选填)
Chrome 92 及更高版本规则应匹配的
tabs.Tab.id
的列表。IDtabs.TAB_ID_NONE
与并非来自标签页的请求匹配。不允许使用空列表。仅适用于会话级范围的规则。 -
urlFilter
字符串(可选)
与网络请求网址匹配的格式。支持的构造:
'*':通配符:匹配任意数量的字符。
'|':左侧/右侧定位点:如果在图案的任意一端使用,则分别指定网址的开头/结尾。
'||':域名锚:如果在格式开头使用,则指定网址的(子)域名的开头。
'^':分隔符:匹配除字母、数字或以下项之一以外的任何内容:
_
、-
、.
或%
。它还与网址的结尾部分相匹配。因此,
urlFilter
由以下部分组成:(可选的左侧/域名定位符)+ 模式 +(可选的右侧定位符)。如果省略,则会匹配所有网址。不允许使用空字符串。
不允许使用以
||*
开头的格式。请改用*
。注意:只能指定
urlFilter
和regexFilter
中的一个。注意:
urlFilter
只能包含 ASCII 字符。这会与主机以 Punycode 格式编码(如果是国际化域名)的网址相匹配,而任何其他非 ASCII 字符都将以 UTF-8 编码的网址进行匹配。例如,如果请求网址为 http://abc.р雅?q=的最新动态,urlFilter
将与网址 http://abc.xn--p1ai/?q=%D1%84 匹配。
Ruleset
属性
-
已启用
布尔值
规则集是否默认处于启用状态。
-
id
字符串
唯一标识规则集的非空字符串。以“_”开头的 ID预留供内部使用。
-
路径
字符串
JSON 规则集相对于扩展程序目录的路径。
RulesMatchedDetails
属性
-
rulesMatchedInfo
符合指定过滤条件的规则。
TabActionCountUpdate
属性
-
递增
number
标签操作数要增加的数值。负值将减少计数。
-
tabId
number
要为其更新操作数的标签页。
TestMatchOutcomeResult
属性
-
matchedRules
与假设请求匹配的规则(如果有)。
TestMatchRequestDetails
属性
-
发起者
字符串(可选)
假设请求的发起者网址(如果有)。
-
method
假设请求的标准 HTTP 方法。默认为“get”对于 HTTP 请求,此参数会被忽略;对于非 HTTP 请求,此参数会被忽略。
-
responseHeaders
对象(可选)
待处理如果请求在发送之前未被屏蔽或重定向,则由假设响应提供的标头。表示为将标头名称映射到字符串值列表的对象。如果未指定,假设响应将返回空的响应标头,该标头可以匹配匹配标头不存在的规则。例如
{"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}
-
tabId
编号(选填)
发生假设请求的标签页的 ID。无需与真实的标签页 ID 相对应。默认值为 -1,表示请求与标签页无关。
-
类型
假设请求的资源类型。
-
网址
字符串
假设请求的网址。
UnsupportedRegexReason
说明给定正则表达式不受支持的原因。
枚举
UpdateRuleOptions
属性
-
addRules
Rule[](可选)
要添加的规则。
-
removeRuleIds
number[](选填)
要移除的规则的 ID。所有无效 ID 都将被忽略。
UpdateRulesetOptions
属性
UpdateStaticRulesOptions
属性
URLTransform
属性
-
Fragment
字符串(可选)
请求的新 fragment。应为空,此时系统会清除现有的 fragment;或以“#”开头。
-
主机
字符串(可选)
请求的新主机。
-
密码
字符串(可选)
请求的新密码。
-
路径
字符串(可选)
请求的新路径。如果为空,则清除现有路径。
-
端口
字符串(可选)
请求的新端口。如果留空,系统会清除现有端口。
-
查询
字符串(可选)
请求的新查询。应为空,此时系统会清除现有查询;或应以“?”开头。
-
queryTransform
添加、移除或替换查询键值对。
-
方案
字符串(可选)
请求的新架构。允许的值为“http”、“https”和“ftp”和“chrome-extension”
-
username
字符串(可选)
请求的新用户名。
属性
DYNAMIC_RULESET_ID
扩展程序添加的动态规则的规则集 ID。
值
"_dynamic"
GETMATCHEDRULES_QUOTA_INTERVAL
可以进行 MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
调用的时间间隔,以分钟为单位指定。其他调用将立即失败并设置为 runtime.lastError
。注意:与用户手势关联的 getMatchedRules
调用不受配额限制。
值
10
值
30,000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
在 GETMATCHEDRULES_QUOTA_INTERVAL
时间段内可以调用 getMatchedRules
的次数。
值
20
MAX_NUMBER_OF_DYNAMIC_RULES
附加信息可添加的动态规则数量上限。
值
30,000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
扩展程序每次可启用的静态Rulesets
数量上限。
值
50
MAX_NUMBER_OF_REGEX_RULES
扩展程序可以添加的正则表达式规则的数量上限。系统会针对一组动态规则和规则资源文件中指定的规则单独评估此限制。
值
1000
MAX_NUMBER_OF_SESSION_RULES
扩展程序可以添加的会话级范围的规则数量上限。
值
5000
MAX_NUMBER_OF_STATIC_RULESETS
扩展程序可以在 "rule_resources"
清单键中指定的静态 Rulesets
数量上限。
值
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
“不安全”事件的最大数量扩展程序可添加的动态规则
值
5000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
“不安全”事件的最大数量扩展程序可以添加的会话级范围的规则。
值
5000
SESSION_RULESET_ID
扩展程序添加的会话级范围的规则的规则集 ID。
值
"_session"
方法
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
返回在达到全局静态规则限制之前扩展程序可以启用的静态规则的数量。
参数
-
callback
函数(可选)
callback
参数如下所示:(count: number) => void
-
计数
number
-
返回
-
Promise<number>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
返回给定 Ruleset
中当前已停用的静态规则的列表。
参数
-
指定要查询的规则集。
-
callback
函数(可选)
callback
参数如下所示:(disabledRuleIds: number[]) => void
-
disabledRuleIds
数值 []
-
返回
-
Promise<数字 []>
Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
返回扩展程序当前的一组动态规则。调用方可以选择通过指定 filter
来过滤提取的规则列表。
参数
返回
-
Chrome 91 及更高版本
Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
返回当前已启用的一组静态规则集的 ID。
参数
-
callback
函数(可选)
callback
参数如下所示:(rulesetIds: string[]) => void
-
rulesetIds
字符串[]
-
返回
-
Promise<string[]>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
返回与该扩展程序匹配的所有规则。调用方可以选择通过指定 filter
来过滤匹配规则列表。此方法仅适用于具有 "declarativeNetRequestFeedback"
权限的扩展程序,或已针对 filter
中指定的 tabId
授予 "activeTab"
权限的扩展程序。注意:系统不会返回与超过五分钟前匹配完毕的有效文档无关的规则。
参数
-
filter
用于过滤匹配规则列表的对象。
-
callback
函数(可选)
callback
参数如下所示:(details: RulesMatchedDetails) => void
-
详细信息
-
返回
-
Promise<RulesMatchedDetails>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
返回扩展程序当前的一组会话级范围的规则。调用方可以选择通过指定 filter
来过滤提取的规则列表。
参数
返回
-
Chrome 91 及更高版本
Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
检查给定正则表达式是否支持作为 regexFilter
规则条件。
参数
-
regexOptions
要检查的正则表达式。
-
callback
函数(可选)
callback
参数如下所示:(result: IsRegexSupportedResult) => void
返回
-
Promise<IsRegexSupportedResult>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
配置是否应将标签页的操作数显示为扩展程序操作的标记文字,并提供该操作计数的递增方式。
参数
-
callback
函数(可选)
Chrome 89 及更高版本callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
检查扩展程序的任何 declarativeNetRequest 规则是否与假设的请求匹配。注意:仅适用于未封装的扩展程序,因为这只能在扩展程序开发期间使用。
参数
-
request
-
callback
函数(可选)
callback
参数如下所示:(result: TestMatchOutcomeResult) => void
返回
-
Promise<TestMatchOutcomeResult>
Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
修改扩展程序的当前一组动态规则。系统会先移除 options.removeRuleIds
中列出的 ID 规则,然后再添加 options.addRules
中指定的规则。注意:
- 此更新作为单个原子操作进行:要么添加和移除所有指定的规则,要么返回错误。
- 无论浏览器会话还是扩展程序更新,这些规则都保持不变。
- 无法使用此函数移除指定为扩展程序软件包一部分的静态规则。
MAX_NUMBER_OF_DYNAMIC_RULES
是扩展程序可以添加的动态规则数量上限。不安全规则的数量不得超过MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
。
参数
-
Chrome 87 及更高版本
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
更新扩展程序的已启用静态规则集。系统首先会移除 options.disableRulesetIds
中列出的 ID 规则集,然后再添加 options.enableRulesetIds
中列出的规则集。
请注意,一组已启用的静态规则集会在各会话之间保持不变,但在扩展程序更新中则不会。也就是说,rule_resources
清单键将决定每次扩展程序更新时已启用的静态规则集集。
参数
-
Chrome 87 及更高版本
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
修改扩展程序的当前会话级范围规则集。系统会先移除 options.removeRuleIds
中列出的 ID 规则,然后再添加 options.addRules
中指定的规则。注意:
- 此更新作为单个原子操作进行:要么添加和移除所有指定的规则,要么返回错误。
- 这些规则不会在会话之间持久保留,并且会支持在内存中。
MAX_NUMBER_OF_SESSION_RULES
是扩展程序可以添加的会话规则数量上限。
参数
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
参数
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
承诺<void>
Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
事件
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
在规则与请求匹配时触发。仅适用于具有 "declarativeNetRequestFeedback"
权限的解压扩展程序,因为此权限仅用于调试目的。
参数
-
callback
函数
callback
参数如下所示:(info: MatchedRuleInfoDebug) => void