说明
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 进行管理。
- 动态规则会在浏览器会话和扩展程序升级后保持不变。
- 关闭浏览器以及安装新版扩展程序时,系统会清除会话规则。
每种规则集类型只有 1 个。扩展程序可以通过调用 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"
键进行定义。
如需启用或停用静态rulesets,请调用 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"]
}
}
urlFilter 匹配字符
规则的 "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://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 |
规则优先级
规则由网页发送的请求触发。如果多条规则与特定请求相匹配,那么必须优先处理这些规则。本部分介绍了它们的优先级。确定优先级分两个阶段进行。
- 优先级由扩展程序中的规则决定。
- 如果一条规则可应用于多个扩展程序,则与特定请求匹配的所有扩展程序的优先级将确定。
关于匹配方式:这样一来,特定扩展程序优先处理的任何规则都将优先于其他扩展程序的规则。
扩展程序中的规则优先级
在单个扩展程序中,可按照以下流程确定优先级:
- 返回开发者定义的优先级最高的规则(即
"priority"
字段)。 如果有多条规则具有最高的开发者定义的优先级,则系统会使用
"action"
字段按以下顺序确定规则的优先级:allow
allowAllRequests
block
upgradeScheme
redirect
如果操作类型不是
block
或redirect
,则评估所有匹配的modifyHeaders
规则。请注意,如果开发者定义的优先级低于为allow
和allowAllRequests
指定的优先级,此类规则将被忽略。如果多条规则修改了同一个标头,则修改操作取决于开发者定义的
"priority"
字段和指定的操作。- 如果某条规则是附加到某个标头,那么优先级较低的规则只能附加到该标头。不允许执行设置和移除操作。
- 如果规则设置了标头,则优先级较低的规则只能附加到该标头。不允许进行其他修改。
- 如果规则移除了某个标题,那么优先级较低的规则将无法进一步修改该标题。
扩展程序之间的规则优先级
如果只有一个扩展程序具有与请求匹配的规则,则系统会应用该规则。但是,如果有多个扩展程序与请求匹配,系统会采用以下流程:
使用
"action"
字段按以下顺序确定规则的优先级:block
redirect
或upgradeScheme
allow
或allowAllRequests
如果有多条规则匹配,最新安装的扩展程序会优先。
规则限制
在浏览器中加载和评估规则会产生性能开销,因此在使用 API 时需要遵守一些限制。具体限制取决于您使用的规则类型。
静态规则
静态规则是指在清单文件中声明的规则文件中指定的规则。一个扩展程序最多可以指定 100 个静态rulesets作为 "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 开始,安全动态规则可使用的规则数量上限为 30,000 条,显示为 MAX_NUMBER_OF_DYNAMIC_RULES
。安全规则定义为操作为 block
、allow
、allowAllRequests
或 upgradeScheme
的规则。在 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()
调用。
可通过 Web 访问的资源
declarativeNetRequest 规则无法从公开资源请求重定向到无法通过 Web 访问的资源。这样做会触发错误。即使重定向扩展程序拥有指定的网络可访问资源也是如此。如需为 declarativeNetRequest 声明资源,请使用清单的 "web_accessible_resources"
数组。
示例
代码示例
更新动态规则
以下示例展示了如何调用 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 如何确定扩展程序中规则的优先级。查看这些规则时,您可以在单独的窗口中打开优先级规则。
“Priority”键
这些示例需要 *://*.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
string
与静态
Ruleset
对应的 ID。
GetRulesFilter
属性
-
ruleIds
number[] 选填
如果指定,则只包含具有匹配 ID 的规则。
HeaderOperation
描述“modifyHeaders”规则可能执行的操作。
枚举
"append"
为指定标头添加新条目。请求标头不支持此操作。
"set"
为指定的标头设置新值,并移除任何同名的现有标头。
"remove"
移除指定标头的所有条目。
IsRegexSupportedResult
属性
-
isSupported
boolean
-
原因
指定正则表达式不受支持的原因。仅当
isSupported
为 false 时提供。
MatchedRule
属性
-
ruleId
number
匹配规则的 ID。
-
rulesetId
string
此规则所属
Ruleset
的 ID。对于源自该组动态规则的规则,此值将为DYNAMIC_RULESET_ID
。
MatchedRuleInfo
属性
-
规则
-
tabId
number
发出请求的标签页的 tabId(如果标签页仍然有效)。否则 -1。
-
timeStamp
number
规则的匹配时间。时间戳对应于 JavaScript 的时间惯例,即从公元纪年开始计算的毫秒数。
MatchedRuleInfoDebug
属性
-
request
与规则匹配的请求的详细信息。
-
规则
MatchedRulesFilter
属性
-
minTimeStamp
数字可选
如果指定,则仅匹配指定时间戳之后的规则。
-
tabId
数字可选
如果指定,则仅匹配给定标签页的规则。如果设为 -1,系统会匹配未与任何活动标签页关联的规则。
ModifyHeaderInfo
属性
-
标头
string
要修改的标头的名称。
-
要在标头上执行的操作。
-
值
字符串(可选)
标头的新值。必须为
append
和set
操作指定此参数。
QueryKeyValue
属性
-
key
string
-
replaceOnly
布尔值 选填
Chrome 94 及更高版本如果为 true,则仅当查询键已存在时才会进行替换。否则,如果缺少该键,系统也会添加该键。默认值为 false。
-
值
string
QueryTransform
属性
-
addOrReplaceParams
QueryKeyValue[] 可选
要添加或替换的查询键值对列表。
-
removeParams
string[] 可选
要移除的查询键的列表。
Redirect
属性
-
extensionPath
字符串(可选)
相对于扩展程序目录的路径。应以“/”开头。
-
regexSubstitution
字符串(可选)
指定
regexFilter
的规则的替代格式。该网址中regexFilter
的第一个匹配项将替换为此格式。在regexSubstitution
中,可以使用反斜杠转义的数字(\1 到 \9)插入相应的捕获组。\0 是指整个匹配的文本。 -
它会将相应的
URLTransform 可选
要执行的网址转换。
-
网址
字符串(可选)
重定向网址。不允许重定向到 JavaScript 网址。
RegexOptions
属性
-
isCaseSensitive
布尔值 选填
指定的
regex
是否区分大小写。默认值为 True。 -
regex
string
要检查的常规 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
string
标准 HTTP 方法。
-
parentDocumentId
字符串(可选)
Chrome 106 及更高版本框架的父文档的唯一标识符(如果此请求是针对一个框架并且有父文档)。
-
parentFrameId
number
用于封装发送请求的帧的帧的 ID。如果不存在父框架,则设置为 -1。
-
requestId
string
请求的 ID。在浏览器会话中,请求 ID 是唯一的。
-
tabId
number
发出请求的标签页的 ID。如果请求与标签页无关,则设为 -1。
-
类型
请求的资源类型。
-
网址
string
请求的网址。
RequestMethod
这介绍了网络请求的 HTTP 请求方法。
枚举
"head"
"options"
"put"
ResourceType
描述网络请求的资源类型。
枚举
"main_frame"
"sub_frame"
"stylesheet"
"script"
"xmlhttprequest"
"ping"
"csp_report"
"media"
"websocket"
"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[] 可选
从 Chrome 101 开始已废弃该规则将仅匹配源自
domains
列表的网络请求。 -
excludedDomains
string[] 可选
从 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”以外的所有资源类型。 -
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
资源类型。 -
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
属性
-
已启用
boolean
是否默认启用规则集。
-
id
string
唯一标识规则集的非空字符串。以“_”开头的 ID 已预留供内部使用。
-
path
string
相对于扩展程序目录的 JSON 规则集路径。
RulesMatchedDetails
属性
-
rulesMatchedInfo
与指定过滤条件匹配的规则。
TabActionCountUpdate
属性
-
递增
number
标签页的操作数增加的金额。负值会减少计数。
-
tabId
number
要更新操作数的标签页。
TestMatchOutcomeResult
属性
-
matchedRules
与假设请求匹配的规则(如有)。
TestMatchRequestDetails
属性
-
发起方
字符串(可选)
假设请求的发起者网址(如有)。
-
method
RequestMethod(可选)
假设请求的标准 HTTP 方法。对于 HTTP 请求,默认为“get”,对于非 HTTP 请求,则将其忽略。
-
tabId
数字可选
发生假设请求的标签页的 ID。无需与真实的标签页 ID 对应。默认值为 -1,表示请求与标签页无关。
-
类型
假设请求的资源类型。
-
网址
string
假设请求的网址。
UnsupportedRegexReason
说明给定正则表达式不受支持的原因。
枚举
UpdateRuleOptions
属性
-
addRules
Rule[] 可选
要添加的规则。
-
removeRuleIds
number[] 选填
要移除的规则的 ID。所有无效 ID 都将被忽略。
UpdateRulesetOptions
属性
UpdateStaticRulesOptions
属性
URLTransform
属性
-
fragment
字符串(可选)
请求的新 fragment。应该为空(此时现有的片段会被清除);或者应以“#”开头。
-
主办方
字符串(可选)
请求的新主机。
-
密码
字符串(可选)
请求的新密码。
-
path
字符串(可选)
请求的新路径。如果为空,则清除现有路径。
-
端口
字符串(可选)
请求的新端口。如果为空,系统会清除现有端口。
-
个查询
字符串(可选)
请求的新查询。应该为空(此时现有查询会被清除);或者应以“?”开头。
-
queryTransform
添加、移除或替换查询键值对。
-
方案
字符串(可选)
请求的新架构。允许的值为“http”“https”“ftp”和“chrome-extension”。
-
用户名
字符串(可选)
请求的新用户名。
属性
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<数字>
Chrome 91 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
返回给定 Ruleset
中当前已停用的静态规则列表。
参数
-
指定要查询的规则集。
-
callback
函数(可选)
callback
参数如下所示:(disabledRuleIds: number[])=>void
-
disabledRuleIds
数值 []
-
返回
-
Promise<number[]>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
返回附加信息的当前动态规则集。调用方可以选择通过指定 filter
来过滤提取的规则列表。
参数
返回
-
Promise<规则[]>
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
来过滤提取的规则列表。
参数
返回
-
Promise<规则[]>
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
返回
-
Promise<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_AND_SESSION_RULES
是扩展程序可以添加的动态规则和会话规则总数上限。
参数
-
Chrome 87 及更高版本
-
callback
函数(可选)
callback
参数如下所示:()=>void
返回
-
Promise<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
返回
-
Promise<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
修改扩展程序当前的会话级范围规则集。系统会先移除 options.removeRuleIds
中所列 ID 的规则,然后添加 options.addRules
中指定的规则。注意:
- 此更新作为单个原子操作进行:添加和移除所有指定的规则,或者返回错误。
- 这些规则不会跨会话持久保留,而是存储在内存中。
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
是扩展程序可以添加的动态规则和会话规则总数上限。
参数
-
callback
函数(可选)
callback
参数如下所示:()=>void
返回
-
Promise<void>
Chrome 91 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
参数
-
callback
函数(可选)
callback
参数如下所示:()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
活动
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
在规则与请求匹配时触发。仅适用于具有 "declarativeNetRequestFeedback"
权限的已解压的扩展程序,因为此权限仅用于调试目的。
参数
-
callback
功能
callback
参数如下所示:(info: MatchedRuleInfoDebug)=>void