chrome.declarativeNetRequest

说明

chrome.declarativeNetRequest API 用于通过指定声明式规则来屏蔽或修改网络请求。这样一来，扩展程序就能够修改网络请求，而不会拦截这类请求并查看其中的内容，从而更好地保护用户隐私。

权限

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

可用性

Chrome 84 及更高版本

清单

除了上述权限之外，某些类型的规则集（具体来说是静态规则集）还要求声明 "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" 键进行定义。

如需启用或停用静态规则集，请调用 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

规则优先级

规则由从网页发送的请求触发。如果多条规则与特定请求相匹配，则必须优先处理这些规则。本部分介绍了这些事件的优先次序。优先级的确定分两个阶段完成。

  1. 扩展程序内规则的优先级是确定的。
  2. 如果有多个扩展程序可以将规则应用于某个请求，系统会为匹配特定请求的所有扩展程序确定优先级。

考虑这样进行匹配：系统会优先考虑某条特定附加信息所优先考虑的规则，而优先于其他附加信息的规则。

扩展程序中的规则优先级

在单个扩展程序中，优先级的确定过程如下：

  1. 系统将返回开发者定义优先级最高的规则（即 "priority" 字段）。

  2. 如果多条规则具有开发者定义的优先级最高，则系统会使用 "action" 字段按以下顺序确定规则的优先级：

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. 如果操作类型不是 block 或 redirect，则评估所有匹配的 modifyHeaders 规则。请注意，如果任何规则的优先级低于为 allow 和 allowAllRequests 指定的优先级，系统会忽略此类规则。

  4. 如果多个规则修改了同一个标头，则修改由开发者定义的 "priority" 字段和指定的操作决定。

    • 如果规则附加到标头，则优先级较低的规则只能附加到该标头。不允许执行“设置”和“移除”操作。
    • 如果规则设置了标头，则优先级较低的规则只能附加到该标头。不允许进行其他修改。
    • 如果某条规则移除了某个标头，那么优先级较低的规则将无法进一步修改该标头。

在扩展程序之间设置规则优先级

如果只有一个扩展程序具有与请求匹配的规则，系统会应用该规则。但是，如果有多个扩展程序与请求匹配，系统会采用以下流程：

  1. 系统使用 "action" 字段确定规则的优先级，顺序如下：

    1. block
    2. redirect 或 upgradeScheme
    3. allow 或 allowAllRequests

  2. 如果多条规则匹配，以最近安装的扩展程序为准。

规则限制

在浏览器中加载和评估规则会产生性能开销， 因此在使用 API 时有一些限制具体限制取决于 您使用的规则

静态规则

静态规则是在清单文件中声明的规则文件中指定的规则。一个扩展程序最多可以指定 50 个静态规则集作为 "rule_resources" 清单键的一部分，但一次只能启用 10 个规则集。后者称为 MAX_NUMBER_OF_ENABLED_STATIC_RULESETS。这些规则集总共保证至少 30,000 条规则。这称为 GUARANTEED_MINIMUM_STATIC_RULES。

之后可用的规则数量取决于用户浏览器中安装的所有扩展程序启用的规则数量。您可以在运行时通过调用 getAvailableStaticRuleCount() 找到此数字。您可以在代码示例下查看相关示例。

动态规则和会话规则

应用于动态规则和会话规则的限制比静态规则更简单。两者的总数不得超过 5000。这称为 MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES。

使用正则表达式的规则

所有类型的规则都可以使用正则表达式；不过，每种类型的正则表达式规则的总数不能超过 1000 个。这称为 MAX_NUMBER_OF_REGEX_RULES。

此外，每条规则在编译后必须小于 2KB。这与规则的复杂程度大致相关。如果您尝试加载的规则超出此限制，则会看到如下所示的警告，并忽略该规则。

rules_1.json: Rule with id 1 specified a more complext 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" 数组。

示例

代码示例

更新动态规则

以下示例展示了如何调用 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

Chrome 88 及更高版本

属性

  • displayActionCountAsBadgeText

    布尔值（可选）

    是否自动将某网页的操作数显示为扩展程序的标志文字。此偏好设置在不同会话之间保持不变。

  • tabUpdate

    TabActionCountUpdate 可选

    Chrome 89 及更高版本

    有关如何调整标签页操作数的详细信息。

GetDisabledRuleIdsOptions

Chrome 111 及更高版本

属性

  • rulesetId

    字符串

    与静态 Ruleset 对应的 ID。

GetRulesFilter

Chrome 111 及更高版本

属性

  • ruleIds

    number[]（选填）

    如果指定，则仅包括具有匹配 ID 的规则。

HeaderInfo

Chrome 128 及更高版本

属性

  • excludedValues

    string[] 选填

    如果指定，则当标头存在但其值至少包含此列表中的一个元素时，此条件不匹配。它使用的匹配模式语法与 values 相同。

  • 标头

    字符串

    标头的名称。仅当 values 和 excludedValues 均未指定时，此条件才与名称匹配。

  • 值

    string[] 选填

    指定后，如果标头的值与此列表中的至少一个模式匹配，则此条件匹配。这支持不区分大小写的标头值匹配以及以下结构：

    '*'：匹配任意数量的字符。

    '?'：匹配 0 个或 1 个字符。

    “*”和“?”可以使用反斜杠进行转义，例如“\*”和“\?”

HeaderOperation

Chrome 86 及更高版本

它描述了“modifyHeaders”规则。

枚举

"append"
为指定的标头添加新条目。请求标头不支持此操作。

"set"
为指定的标头设置新值，并移除任何同名的现有标头。

"remove"
移除指定标头的所有条目。

IsRegexSupportedResult

Chrome 87 及更高版本

属性

  • isSupported

    布尔值

  • reason

    UnsupportedRegexReason（可选）

    说明正则表达式不受支持的原因。仅当 isSupported 为 false 时提供。

MatchedRule

属性

  • ruleId

    number

    匹配规则的 ID。

  • rulesetId

    字符串

    此规则所属的 Ruleset 的 ID。对于源自一组动态规则的规则，此值等于 DYNAMIC_RULESET_ID。

MatchedRuleInfo

属性

  • 规则

    MatchedRule

  • tabId

    number

    从中发起请求的标签页的 tabId（如果标签页仍处于活动状态）。否则 -1。

  • timeStamp

    number

    规则的匹配时间。时间戳将对应于 JavaScript 的时间惯例，即从公元纪年开始计算的毫秒数。

MatchedRuleInfoDebug

属性

MatchedRulesFilter

属性

  • minTimeStamp

    编号（选填）

    如果指定，则仅匹配给定时间戳之后的规则。

  • tabId

    编号（选填）

    指定后，将仅匹配指定标签页的规则。如果设置为 -1，则匹配未与任何活跃标签页关联的规则。

ModifyHeaderInfo

Chrome 86 及更高版本

属性

  • 标头

    字符串

    要修改的标头的名称。

  • 要对标头执行的操作。

  • 值

    字符串（可选）

    标头的新值。必须为 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

Chrome 87 及更高版本

属性

  • isCaseSensitive

    布尔值（可选）

    指定的 regex 是否区分大小写。默认值为 true。

  • regex

    字符串

    要检查的常规 Expresson。

  • requireCapturing

    布尔值（可选）

    指定的 regex 是否需要捕获。只有指定 regexSubstition 操作的重定向规则才需要捕获。默认值为 false。

RequestDetails

属性

  • documentId

    字符串（可选）

    Chrome 106 及更高版本

    帧文档的唯一标识符（如果此请求针对的是帧）。

  • documentLifecycle

    DocumentLifecycle 可选

    Chrome 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。

  • 类型

    ResourceType

    请求的资源类型。

  • 网址

    字符串

    请求的网址。

RequestMethod

Chrome 91 及更高版本

它描述了网络请求的 HTTP 请求方法。

枚举

"连接"

“删除”

"get"

"head"

"选项"

"补丁"

“post”

“put”

“其他”

ResourceType

它描述了网络请求的资源类型。

枚举

“main_frame”

“sub_frame”

“stylesheet”

"script"

“图片”

"字体"

“对象”

"xmlhttprequest"

“ping”

"csp_report"

“media”

"websocket"

"webtransport"

"webbundle"

“其他”

Rule

属性

  • action

    RuleAction

    规则匹配时要执行的操作。

  • condition

    RuleCondition

    触发此规则的条件。

  • 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 起弃用

    改用 initiatorDomains

    该规则将仅匹配来自 domains 列表的网络请求。

  • excludedDomains

    string[] 选填

    <ph type="x-smartling-placeholder"></ph> 自 Chrome 101 起弃用

    改用 excludedInitiatorDomains

    该规则不会匹配来自 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 的列表。ID tabs.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

属性

TabActionCountUpdate

Chrome 89 及更高版本

属性

  • 递增

    number

    标签操作数要增加的数值。负值将减少计数。

  • tabId

    number

    要为其更新操作数的标签页。

TestMatchOutcomeResult

Chrome 浏览器 103 或更高版本

属性

  • matchedRules

    MatchedRule[]

    与假设请求匹配的规则（如果有）。

TestMatchRequestDetails

Chrome 浏览器 103 或更高版本

属性

  • 发起者

    字符串（可选）

    假设请求的发起者网址（如果有）。

  • method

    RequestMethod 可选

    假设请求的标准 HTTP 方法。默认为“get”对于 HTTP 请求，此参数会被忽略；对于非 HTTP 请求，此参数会被忽略。

  • responseHeaders

    对象（可选）

    待处理

    如果请求在发送之前未被屏蔽或重定向，则由假设响应提供的标头。表示为将标头名称映射到字符串值列表的对象。如果未指定，假设响应将返回空的响应标头，该标头可以匹配匹配标头不存在的规则。例如 {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    编号（选填）

    发生假设请求的标签页的 ID。无需与真实的标签页 ID 相对应。默认值为 -1，表示请求与标签页无关。

  • 类型

    ResourceType

    假设请求的资源类型。

  • 网址

    字符串

    假设请求的网址。

UnsupportedRegexReason

Chrome 87 及更高版本

说明给定正则表达式不受支持的原因。

枚举

"syntaxError"
正则表达式的语法不正确，或者使用了 RE2 语法不支持的功能。

&quot;memoryLimitExceeded&quot;
正则表达式超出了内存限制。

UpdateRuleOptions

Chrome 87 及更高版本

属性

  • addRules

    Rule[]（可选）

    要添加的规则。

  • removeRuleIds

    number[]（选填）

    要移除的规则的 ID。所有无效 ID 都将被忽略。

UpdateRulesetOptions

Chrome 87 及更高版本

属性

  • disableRulesetIds

    string[] 选填

    与应停用的静态 Ruleset 对应的一组 ID。

  • enableRulesetIds

    string[] 选填

    与应启用的静态 Ruleset 对应的一组 ID。

UpdateStaticRulesOptions

Chrome 111 及更高版本

属性

  • disableRuleIds

    number[]（选填）

    与要停用的 Ruleset 中的规则对应的 ID 集。

  • enableRuleIds

    number[]（选填）

    与要启用的 Ruleset 中的规则对应的 ID 集。

  • rulesetId

    字符串

    与静态 Ruleset 对应的 ID。

URLTransform

属性

  • Fragment

    字符串（可选）

    请求的新 fragment。应为空，此时系统会清除现有的 fragment；或以“#”开头。

  • 主机

    字符串（可选）

    请求的新主机。

  • 密码

    字符串（可选）

    请求的新密码。

  • 路径

    字符串（可选）

    请求的新路径。如果为空，则清除现有路径。

  • 端口

    字符串（可选）

    请求的新端口。如果留空，系统会清除现有端口。

  • 查询

    字符串（可选）

    请求的新查询。应为空，此时系统会清除现有查询；或应以“?”开头。

  • queryTransform

    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

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 及更高版本

为扩展程序启用的静态规则集保证的静态规则数量下限。超过此限制的所有规则都将计入全局静态规则限制。

值

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

Chrome 94 及更高版本

扩展程序每次可启用的静态Rulesets数量上限。

值

50

MAX_NUMBER_OF_REGEX_RULES

扩展程序可以添加的正则表达式规则的数量上限。系统会针对一组动态规则和规则资源文件中指定的规则单独评估此限制。

值

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 及更高版本

扩展程序可以添加的会话级范围的规则数量上限。

值

5000

MAX_NUMBER_OF_STATIC_RULESETS

扩展程序可以在 "rule_resources" 清单键中指定的静态 Rulesets 数量上限。

值

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 及更高版本

“不安全”事件的最大数量扩展程序可添加的动态规则

值

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 及更高版本

“不安全”事件的最大数量扩展程序可以添加的会话级范围的规则。

值

5000

SESSION_RULESET_ID

Chrome 90 及更高版本

扩展程序添加的会话级范围的规则的规则集 ID。

值

"_session"

方法

getAvailableStaticRuleCount()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 89 及更高版本 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

返回在达到全局静态规则限制之前扩展程序可以启用的静态规则的数量。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (count: number) => void

    • 计数

      number

返回

  • Promise&lt;number&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getDisabledRuleIds()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 111 及更高版本 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

返回给定 Ruleset 中当前已停用的静态规则的列表。

参数

  • 指定要查询的规则集。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      数值 []

返回

  • Promise<数字 []>

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getDynamicRules()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

返回扩展程序当前的一组动态规则。调用方可以选择通过指定 filter 来过滤提取的规则列表。

参数

  • filter

    GetRulesFilter 可选

    Chrome 111 及更高版本

    用于过滤提取的规则列表的对象。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (rules: Rule[]) => void

返回

  • Promise<规则 []>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getEnabledRulesets()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

返回当前已启用的一组静态规则集的 ID。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (rulesetIds: string[]) => void

    • rulesetIds

      字符串[]

返回

  • Promise&lt;string[]&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getMatchedRules()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

返回与该扩展程序匹配的所有规则。调用方可以选择通过指定 filter 来过滤匹配规则列表。此方法仅适用于具有 "declarativeNetRequestFeedback" 权限的扩展程序，或已针对 filter 中指定的 tabId 授予 "activeTab" 权限的扩展程序。注意：系统不会返回与超过五分钟前匹配完毕的有效文档无关的规则。

参数

返回

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getSessionRules()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 90 及更高版本 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

返回扩展程序当前的一组会话级范围的规则。调用方可以选择通过指定 filter 来过滤提取的规则列表。

参数

  • filter

    GetRulesFilter 可选

    Chrome 111 及更高版本

    用于过滤提取的规则列表的对象。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (rules: Rule[]) => void

返回

  • Promise<规则 []>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

isRegexSupported()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 87 及更高版本 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

检查给定正则表达式是否支持作为 regexFilter 规则条件。

参数

返回

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setExtensionActionOptions()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 88 及更高版本 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

配置是否应将标签页的操作数显示为扩展程序操作的标记文字，并提供该操作计数的递增方式。

参数

  • callback

    函数（可选）

    Chrome 89 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 91 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

testMatchOutcome()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 103 及更高版本 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

检查扩展程序的任何 declarativeNetRequest 规则是否与假设的请求匹配。注意：仅适用于未封装的扩展程序，因为这只能在扩展程序开发期间使用。

参数

返回

  • Promise&lt;TestMatchOutcomeResult&gt;

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

updateDynamicRules()

<ph type="x-smartling-placeholder"></ph> 承诺 
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，其他平台需要使用回调。

updateEnabledRulesets()

<ph type="x-smartling-placeholder"></ph> 承诺 
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，其他平台需要使用回调。

updateSessionRules()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 90 及更高版本 
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，其他平台需要使用回调。

updateStaticRules()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 111 及更高版本 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

停用和启用 Ruleset 中的个别静态规则。对已停用的Ruleset的规则所做的更改将在下次启用时生效。

参数

返回

  • 承诺<void>

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onRuleMatchedDebug

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

在规则与请求匹配时触发。仅适用于具有 "declarativeNetRequestFeedback" 权限的解压扩展程序，因为此权限仅用于调试目的。

参数