chrome.declarativeNetRequest

Description

chrome.declarativeNetRequest API 用于通过指定声明性规则来阻止或修改网络请求。这让扩展程序可以修改网络请求，而无需拦截它们并查看其内容，从而提供更多隐私。

Permissions

declarativeNetRequest declarativeNetRequestWithHostAccess declarativeNetRequestFeedback host permissions

Availability

Chrome 84+

# Manifest

扩展程序必须在扩展程序清单中声明 declarativeNetRequest 或 declarativeNetRequestWithHostAccess（自 Chrome 96 起可用）权限才能使用此 API。前者允许扩展在没有任何主机权限(host permissions)的情况下阻止和升级请求。如果扩展程序想要重定向请求或修改其上的标头，则仍需要主机权限。declarativeNetRequestWithHostAccess 权限始终需要对请求 URL 和发起程序的主机权限才能对请求进行操作。

需要 declarativeNetRequestFeedback 权限才能访问返回有关匹配的声明性规则的信息的函数和事件。

要指定静态规则集（Rulesets），扩展还必须声明“declarative_net_request”清单键，它应该是一个字典，其中包含一个名为“rule_resources”的键。它应该是一个包含规则集（Ruleset）类型字典的列表，如下所示。

{
  "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",
    "*://example.com/*"
  ],
  ...
}

# Rule Resources（规则资源）

扩展最多可以指定 MAX_NUMBER_OF_STATIC_RULESETS 规则集rulesets作为“rule_resources”清单键的一部分。假设不超过静态规则限制，一次只能启用 MAX_NUMBER_OF_ENABLED_STATIC_RULESETS 这些规则集。

允许扩展至少启用 GUARANTEED_MINIMUM_STATIC_RULES 静态规则。根据可用的全局静态规则限制global static rule limit，可能会或可能不会启用其他静态规则集。

注意：有关无效静态规则的错误和警告仅针对未打包的扩展显示。打包扩展中的无效静态规则将被忽略。因此，通过使用扩展的解压缩版本进行测试来验证您的静态规则集是否有效非常重要。

# Global Static Rule Limit(全局静态规则限制)

除了为每个扩展保证的 GUARANTEED_MINIMUM_STATIC_RULES 静态规则之外，扩展可以根据可用的全局静态规则限制启用额外的静态规则集。此全局限制在所有扩展程序之间共享，并且可以按先到先得的原则由扩展程序使用。扩展不应依赖于具有特定值的全局限制，而应使用 getAvailableStaticRuleCount API 方法来查找对它们可用的附加规则限制。

# Rules(规则)

单个声明性规则Rule由四个字段组成：id、priority、condition 和 action。有以下几种规则：

  • 阻止网络请求的规则。
  • 通过否定任何匹配的阻止规则来防止请求被阻止的规则。
  • 重定向网络请求的规则。
  • 修改来自网络请求的标头的规则。

一个示例规则：

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

上述规则将阻止所有来自“foo.com”的脚本请求到任何以“abc”作为子字符串的 URL。

规则条件的 urlFilter 字段用于指定与请求 URL 匹配的模式。它记录在下面的 RuleCondition 类型中。 URL 过滤器的一些示例：

**urlFilter** Matches Does not match
"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

# Dynamic and session-scoped rules(动态和会话范围的规则)

扩展可以使用 updateDynamicRules 和 updateSessionRules API 方法动态添加或删除规则。

# Updating enabled rulesets(更新启用的规则集)

扩展可以使用 updateEnabledRulesets API 方法更新启用的静态规则集集。

  • 一次启用的静态规则集的数量不得超过 MAX_NUMBER_OF_ENABLED_STATIC_RULESETS。
  • 跨所有扩展的已启用静态规则集的规则数量不得超过全局限制global limit。建议调用 getAvailableStaticRuleCount 来检查扩展在达到全局限制之前仍然可以启用的规则数量。
  • 启用的静态规则集集跨会话保留，但不跨扩展更新保留。 rule_resources 清单键将确定在初始扩展安装和每个后续扩展更新时启用的静态规则集集。

# Implementation details(实施细则)

# Matching algorithm(匹配算法)

在发送请求之前，会查询每个扩展以获取要执行的操作。在此阶段考虑以下行动：

  • 阻止类型块block请求的操作
  • 重定向类型为 redirect 或 upgradeScheme 的请求的操作
  • 允许类型为 allow 或 allowAllRequests 的请求的操作

如果多个扩展返回一个动作，则动作类型在上面列表中排在第一位的扩展获得优先权。如果多个扩展返回具有相同优先级（列表中的位置）的操作，则最近安装的扩展获得优先级。

当查询扩展如何处理请求时，返回最高优先级的匹配规则。如果多个匹配规则具有最高优先级，则根据操作类型按以下优先级递减顺序打破平局：

  • allow
  • allowAllRequests
  • block
  • upgradeScheme
  • redirect

如果请求没有被阻止或重定向，匹配的 modifyHeaders 规则将使用最近安装的扩展获得优先级进行评估。在每个扩展中，优先级低于匹配的 allow 或 allowAllRequests 规则的所有 modifyHeaders 规则都将被忽略。

如果多个 modifyHeaders 规则指定相同的标头，则根据每个规则的优先级和指定的操作确定对标头的最终修改。

  • 如果规则已附加到标头，则优先级较低的规则只能附加到该标头。不允许set和remove操作。
  • 如果规则设置了标头，则较低优先级的规则不能进一步修改标头，除非append来自同一扩展的规则。
  • 如果规则已删除标头，则较低优先级的规则无法进一步修改标头。

# Comparison with the webRequest API(与 webRequest API 的比较)

  • declarativeNetRequest API 允许在浏览器本身中评估网络请求。这使得它比 webRequest API 的性能更高，后者在扩展过程中使用 JavaScript 评估每个网络请求。
  • 由于请求没有被扩展进程拦截，declarativeNetRequest 消除了扩展有后台页面的需要；从而减少内存消耗。
  • 与 webRequest API 不同，当与 declarativeNetRequest 权限一起使用时，使用 declarativeNetRequest API 阻止或升级请求不需要主机权限。
  • declarativeNetRequest API 为用户提供了更好的隐私，因为扩展实际上无法读取代表用户发出的网络请求。
  • 与 webRequest API 不同，使用 declarativeNetRequest API 阻止的任何图像或 iframe 都会在 DOM 中自动折叠。
  • 在决定是阻止还是重定向请求时，declarativeNetRequest API 的优先级高于 webRequest API，因为它允许同步拦截。同样，通过 declarativeNetRequest API 删除的任何标头都不会对 Web 请求扩展可见。
  • 与 declarativeNetRequest API 相比，webRequest API 更灵活，因为它允许扩展程序以编程方式评估请求。

# Example

manifest.json

{
  "name": "declarativeNetRequest extension",
  "version": "1",
  "declarative_net_request": {
    "rule_resources": [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules.json"
    }]
  },
  "permissions": [
    "*://*.google.com/*",
    "*://*.abcd.com/*",
    "*://*.example.com/*",
    "https://*.xyz.com/*",
    "*://*.headers.com/*",
    "declarativeNetRequest"
  ],
  "manifest_version": 2
}

rules.json

[
  {
    "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"] }
  },
  {
    "id": 5,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
    "condition": { "urlFilter": "abcd.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 6,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": {
        "transform": { "scheme": "https", "host": "new.example.com" }
      }
    },
    "condition": { "urlFilter": "||example.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 7,
    "priority": 1,
    "action": {
      "type": "redirect",
      "redirect": {
        "regexSubstitution": "https://\\1.xyz.com/"
      }
    },
    "condition": {
      "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
      "resourceTypes": [
        "main_frame"
      ]
    }
  },
  {
    "id" : 8,
    "priority": 2,
    "action" : {
      "type" : "allowAllRequests"
    },
    "condition" : {
      "urlFilter" : "||b.com/path",
      "resourceTypes" : ["sub_frame"]
    }
  },
  {
    "id" : 9,
    "priority": 1,
    "action" : {
      "type" : "block"
    },
    "condition" : {
      "urlFilter" : "script.js",
      "resourceTypes" : ["script"]
    }
  },
  {
    "id": 10,
    "priority": 2,
    "action": {
      "type": "modifyHeaders",
      "responseHeaders": [
        { "header": "h1", "operation": "remove" },
        { "header": "h2", "operation": "set", "value": "v2" },
        { "header": "h3", "operation": "append", "value": "v3" }
      ]
    },
    "condition": { "urlFilter": "headers.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 11,
    "priority": 1,
    "action": {
      "type": "modifyHeaders",
      "responseHeaders": [
        { "header": "h1", "operation": "set", "value": "v4" },
        { "header": "h2", "operation": "append", "value": "v5" },
        { "header": "h3", "operation": "append", "value": "v6" }
      ]
    },
    "condition": { "urlFilter": "headers.com/12345", "resourceTypes": ["main_frame"] }
  },
]
  • 考虑使用响应标头{ "h1": "initial_1", "h2": "initial_2" } 导航到“https://headers.com/12345”。 id 为 (10) 和 (11) 的规则匹配。请求的响应头将修改为 { "h2": "v2", "h2": "v5", "h3": "v3", "h3": "v6" }。头h1被（10）删除，h2被（10）设置，然后被（11）附加，h3被（10）和（11）附加。

Summary

Types

DomainType

这描述了请求是发起它的帧的第一方还是第三方。如果请求与发起请求的帧具有相同的域 (eTLD+1)，则该请求被称为第一方。

TYPE

"firstParty", or "thirdParty"

ExtensionActionOptions

Chrome 88+

PROPERTIES

  • displayActionCountAsBadgeText

    boolean optional

    是否自动将页面的操作计数显示为扩展程序的徽章文本。此首选项在会话之间保持不变。

  • tabUpdate

    TabActionCountUpdate optional

    Chrome 89+

    应如何调整选项卡的操作计数的详细信息。

HeaderOperation

Chrome 86+

这描述了“modifyHeaders”规则的可能操作。

TYPE

"append", "set", or "remove"

IsRegexSupportedResult

Chrome 87+

PROPERTIES

  • isSupported

    boolean

  • reason

    UnsupportedRegexReason optional

    指定不支持正则表达式的原因。仅在 isSupported 为 false 时提供。

MatchedRule

PROPERTIES

  • ruleId

    number

    匹配规则的 ID。

  • rulesetId

    string

    此规则所属的规则集Ruleset的 ID。对于源自动态规则集的规则，这将等于 DYNAMIC_RULESET_ID。

MatchedRuleInfo

PROPERTIES

  • rule

    MatchedRule

  • tabId

    number

    如果选项卡仍处于活动状态，则为发起请求的选项卡的 tabId。否则-1。

  • timeStamp

    number

    规则匹配的时间。时间戳将对应于 Javascript 约定的时间，即自纪元以来的毫秒数。

MatchedRuleInfoDebug

PROPERTIES

MatchedRulesFilter

PROPERTIES

  • minTimeStamp

    number optional

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

  • tabId

    number optional

    如果指定，则仅匹配给定选项卡的规则。如果设置为 -1，则匹配与任何活动选项卡无关的规则。

ModifyHeaderInfo

Chrome 86+

PROPERTIES

  • header

    string

    要修改的标头的名称。

  • operation

    HeaderOperation

    要对标头执行的操作。

  • value

    string optional

    标头的新值。必须为追加append和设置set操作指定。

QueryKeyValue

PROPERTIES

  • key

    string

  • replaceOnly

    boolean optional

    Chrome 94+

    如果为 true，则仅当查询键已经存在时才替换它。否则，如果缺少密钥，也会添加该密钥。默认为false。

  • value

    string

QueryTransform

PROPERTIES

  • addOrReplaceParams

    QueryKeyValue[] optional

    要添加或替换的查询键值对列表。

  • removeParams

    string[] optional

    要删除的查询键列表。

Redirect

PROPERTIES

  • extensionPath

    string optional

    相对于扩展目录的路径。应该以'/'开头。

  • regexSubstitution

    string optional

    指定正则表达式过滤器的规则的替换模式regexFilter。url 中 regexFilter 的第一个匹配项将替换为此模式。在 regexSubstitution 中，反斜杠转义的数字（\1 到 \9）可用于插入相应的捕获组。 \0 指的是整个匹配文本。

  • transform

    URLTransform optional

    要执行的 URL 转换。

  • url

    string optional

    重定向网址。不允许重定向到 JavaScript url。

RegexOptions

Chrome 87+

PROPERTIES

  • isCaseSensitive

    boolean optional

    指定的正则表达式是否区分大小写。默认为true。

  • regex

    string

    要检查的正则表达式。

  • requireCapturing

    boolean optional

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

RequestDetails

PROPERTIES

  • frameId

    number

    值 0 表示请求发生在主框架中；正值表示发生请求的子帧的 ID。如果加载了（子）框架的文档（type为main_frame或sub_frame），frameId表示该框架的ID，而不是外框架的ID。框架 ID 在选项卡中是唯一的。

  • initiator

    string optional

    发起请求的来源。这不会通过重定向改变。如果这是一个不透明的原点，则将使用字符串 'null'。

  • method

    string

    标准 HTTP 方法。

  • parentFrameId

    number

    包装发送请求的帧的帧 ID。如果不存在父框架，则设置为 -1。

  • requestId

    string

    请求的 ID。请求 ID 在浏览器会话中是唯一的。

  • tabId

    number

    发生请求的选项卡的 ID。如果请求与选项卡无关，则设置为 -1。

  • type

    ResourceType

    请求的资源类型。

  • url

    string

    请求的 URL。

RequestMethod

Chrome 91+

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

TYPE

"connect", "delete", "get", "head", "options", "patch", "post", or "put"

ResourceType

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

TYPE

"main_frame", "sub_frame", "stylesheet", "script", "image", "font", "object", "xmlhttprequest", "ping", "csp_report", "media", "websocket", "webtransport", "webbundle", or "other"

Rule

PROPERTIES

  • action

    RuleAction

    如果此规则匹配，则采取的操作。

  • condition

    RuleCondition

    触发此规则的条件。

  • id

    number

    唯一标识规则的 id。必须的并且应该 >= 1。

  • priority

    number optional

    规则优先。默认为 1。指定时，应 >= 1。

RuleAction

PROPERTIES

  • redirect

    Redirect optional

    描述应该如何执行重定向。仅对重定向规则有效。

  • requestHeaders

    ModifyHeaderInfo[] optional

    Chrome 86+

    要为请求修改的请求标头。仅当 RuleActionType 为“modifyHeaders”时才有效。

  • responseHeaders

    ModifyHeaderInfo[] optional

    Chrome 86+

    要为请求修改的响应标头。仅当 RuleActionType 为“modifyHeaders”时才有效。

  • type

    RuleActionType

    要执行的操作类型。

RuleActionType

描述在给定 RuleCondition 匹配时要采取的操作类型。

TYPE

"block", "redirect", "allow", "upgradeScheme", "modifyHeaders", or "allowAllRequests"

RuleCondition

PROPERTIES

  • domainType

    DomainType optional

    指定网络请求是发起它的域的第一方还是第三方。如果省略，则接受所有请求。

  • domains

    string[] optional

    该规则将仅匹配源自域domains列表的网络请求。如果省略该列表，则该规则将应用于来自所有域的请求。不允许使用空列表。

    笔记：

    • 也允许使用像“a.example.com”这样的子域。
    • 条目必须仅包含 ascii 字符。
    • 对国际化域使用 punycode 编码。
    • 这与请求发起者匹配，而不是请求 url。

  • excludedDomains

    string[] optional

    该规则将不匹配源自排除域excludedDomains列表的网络请求。如果列表为空或省略，则不排除任何域。这优先于域domains。

    笔记：

    • 也允许使用像“a.example.com”这样的子域。
    • 条目必须仅包含 ascii 字符。
    • 对国际化域使用 punycode 编码。
    • 这与请求发起者匹配，而不是请求 url。

  • excludedRequestMethods

    RequestMethod[] optional

    Chrome 91+

    规则不匹配的请求方法列表。只应指定 requestMethods 和 excludeRequestMethods 之一。如果两者均未指定，则匹配所有请求方法。

  • excludedResourceTypes

    ResourceType[] optional

    规则不匹配的资源类型列表。只应指定 resourceTypes 和 excludeResourceTypes 之一。如果两者均未指定，则阻塞除“main_frame”之外的所有资源类型。

  • excludedTabIds

    number[] optional

    Chrome 92+

    规则不应匹配的 tabs.Tab.id 列表。 tabs.TAB_ID_NONE 的 ID 排除了不是来自选项卡的请求。仅支持会话范围的规则。

  • isUrlFilterCaseSensitive

    boolean optional

    urlFilter 或 regexFilter（以指定者为准）是否区分大小写。默认为true。

  • regexFilter

    string optional

    匹配网络请求 url 的正则表达式。这遵循 RE2 语法)。

    注意：只能指定 urlFilter 或 regexFilter 之一。

    注意：regexFilter 必须仅由 ASCII 字符组成。这与主机以 punycode 格式编码的 url 匹配（在国际化域的情况下），并且任何其他非 ascii 字符以 utf-8 编码的 url。

  • requestMethods

    RequestMethod[] optional

    Chrome 91+

    规则可以匹配的 HTTP 请求方法列表。不允许使用空列表。

    注意：指定 requestMethods 规则条件也将排除非 HTTP(s) 请求，而指定 excludeRequestMethods 则不会。

  • resourceTypes

    ResourceType[] optional

    规则可以匹配的资源类型列表。不允许使用空列表。

    注意：这必须为 allowAllRequests 规则指定，并且可能仅包括 sub_frame 和 main_frame 资源类型。

  • tabIds

    number[] optional

    Chrome 92+

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

  • urlFilter

    string optional

    与网络请求 url 匹配的模式。支持的构造：

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

    '|' : 左/右锚点：如果在模式的任一端使用，则分别指定 url 的开头/结尾。

    '||' : 域名锚点：如果在模式的开头使用，则指定 URL 的（子）域的开头。

    '^' ：分隔符：这匹配除字母、数字或以下之一之外的任何内容：_ - 。 %。这也可以匹配 URL 的结尾。

    因此 urlFilter 由以下部分组成：（可选的左/域名锚点）+模式+（可选的右锚点）。

    如果省略，则匹配所有 url。不允许使用空字符串。

    不允许以 || 开头的模式。使用 代替。

    注意：只能指定 urlFilter 或 regexFilter 之一。

    注意：urlFilter 必须仅由 ASCII 字符组成。这与主机以 punycode 格式编码的 url 匹配（在国际化域的情况下），并且任何其他非 ascii 字符以 utf-8 编码的 url。例如，当请求url为http://abc.рф?q=ф时，urlFilter会匹配url http://abc.xn--p1ai/?q=%D1%84

Ruleset

PROPERTIES

  • enabled

    boolean

    默认情况下是否启用规则集。

  • id

    string

    唯一标识规则集的非空字符串。以“_”开头的 ID 保留供内部使用。

  • path

    string

    JSON 规则集相对于扩展目录的路径。

RulesMatchedDetails

PROPERTIES

TabActionCountUpdate

Chrome 89+

PROPERTIES

  • increment

    number

    增加选项卡操作计数的数量。负值将减少计数。

  • tabId

    number

    要为其更新操作计数的选项卡。

UnsupportedRegexReason

Chrome 87+

描述不支持给定正则表达式的原因。

TYPE

"syntaxError", or "memoryLimitExceeded"

UpdateRuleOptions

Chrome 87+

PROPERTIES

  • addRules

    Rule[] optional

    要添加的规则。

  • removeRuleIds

    number[] optional

    要删除的规则的 ID。任何无效的 ID 都将被忽略。

UpdateRulesetOptions

Chrome 87+

PROPERTIES

  • disableRulesetIds

    string[] optional

    对应于应禁用的静态规则集Ruleset的一组 id。

  • enableRulesetIds

    string[] optional

    对应于应启用的静态规则集Ruleset的一组 id。

URLTransform

PROPERTIES

  • fragment

    string optional

    请求的新片段。应该是空的，在这种情况下，现有的片段被清除；或者应该以“#”开头。

  • host

    string optional

    请求的新主机。

  • password

    string optional

    请求的新密码。

  • path

    string optional

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

  • port

    string optional

    请求的新端口。如果为空，则清除现有端口。

  • query

    string optional

    请求的新查询。应该是空的，在这种情况下，现有的查询被清除；或者应该以“?”开头。

  • queryTransform

    QueryTransform optional

    添加、删除或替换查询键值对。

  • scheme

    string optional

    请求的新方案（scheme）。允许的值为“http”、“https”、“ftp”和“chrome-extension”。

  • username

    string optional

    请求的新用户名。

Properties

DYNAMIC_RULESET_ID

扩展程序添加的动态规则的规则集 ID。

VALUE

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

可以进行 MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules 调用的时间间隔，以分钟为单位指定。其他调用将立即失败并设置 runtime.lastError。注意：与用户手势关联的 getMatchedRules 调用不受配额限制。

VALUE

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+

保证跨其启用的静态规则集的扩展的最小静态规则数。任何高于此限制的规则都将计入全局规则限制global rule limit。

VALUE

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

在 GETMATCHEDRULES_QUOTA_INTERVAL 时间内可以调用 getMatchedRules 的次数。

VALUE

20

MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES

Chrome 90+

扩展可以添加的组合动态和会话范围规则的最大数量。

VALUE

5000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94+

扩展在任何时候可以启用的静态规则集Rulesets的最大数量。

VALUE

10

MAX_NUMBER_OF_REGEX_RULES

扩展可以添加的最大正则表达式规则数。此限制是针对动态规则集和规则资源文件中指定的规则单独评估的。

VALUE

1000

MAX_NUMBER_OF_STATIC_RULESETS

扩展可以指定为“rule_resources”清单键的一部分的最大静态规则集Rulesets数。

VALUE

50

SESSION_RULESET_ID

Chrome 90+

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

VALUE

"_session"

Methods

getAvailableStaticRuleCount 

chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

Promise Chrome 89+

返回在达到全局静态规则限制global static rule limit之前扩展可以启用的静态规则数。

PARAMETERS

  • callback

    function optional

    The callback parameter looks like:

    (count: number) => void

    • count

      number

RETURNS

  • Promise<number>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getDynamicRules 

chrome.declarativeNetRequest.getDynamicRules(
  callback?: function,
)

Promise

返回扩展的当前动态规则集。

PARAMETERS

  • callback

    function optional

    The callback parameter looks like:

    (rules: Rule[]) => void

RETURNS

  • Promise<Rule[]>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getEnabledRulesets 

chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Promise

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

PARAMETERS

  • callback

    function optional

    The callback parameter looks like:

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

RETURNS

  • Promise<string[]>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getMatchedRules

chrome.declarativeNetRequest.getMatchedRules( filter?: MatchedRulesFilter, callback?: function, )

Promise

返回与扩展匹配的所有规则。调用者可以选择通过指定过滤器filter来过滤匹配规则的列表。此方法仅适用于具有 declarativeNetRequestFeedback 权限或为过滤器filter中指定的 tabId 授予 activeTab 权限的扩展。注意：不会返回与活动文档无关且匹配时间超过 5 分钟的规则。

PARAMETERS

RETURNS

  • Promise<RulesMatchedDetails>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

getSessionRules 

chrome.declarativeNetRequest.getSessionRules(
  callback?: function,
)

Promise Chrome 90+

返回扩展的当前会话范围规则集。

PARAMETERS

  • callback

    function optional

    The callback parameter looks like:

    (rules: Rule[]) => void

RETURNS

  • Promise<Rule[]>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

isRegexSupported

chrome.declarativeNetRequest.isRegexSupported( regexOptions: RegexOptions, callback?: function, )

Promise Chrome 87+

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

PARAMETERS

RETURNS

  • Promise<IsRegexSupportedResult>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

setExtensionActionOptions

chrome.declarativeNetRequest.setExtensionActionOptions( options: ExtensionActionOptions, callback?: function, )

Promise Chrome 88+

配置选项卡的操作计数是否应显示为扩展操作的标记文本，并提供一种增加该操作计数的方法。

PARAMETERS

RETURNS

  • Promise<void>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

updateDynamicRules

chrome.declarativeNetRequest.updateDynamicRules( options: UpdateRuleOptions, callback?: function, )

Promise

修改扩展的当前动态规则集。具有在 options.removeRuleIds 中列出的 ID 的规则首先被删除，然后在 options.addRules 中给出的规则被添加。笔记：

  • 此更新作为单个原子操作发生：添加和删除所有指定的规则，或者返回错误。
  • 这些规则在浏览器会话和扩展程序更新之间保持不变。
  • 不能使用此功能删除作为扩展包一部分指定的静态规则。
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES 是扩展可以添加的组合动态和会话规则的最大数量。

PARAMETERS

  • options

    UpdateRuleOptions

    Chrome 87+

  • callback

    function optional

    The callback parameter looks like:

    () => void

RETURNS

  • Promise<void>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

updateEnabledRulesets

chrome.declarativeNetRequest.updateEnabledRulesets( options: UpdateRulesetOptions, callback?: function, )

Promise

更新扩展的已启用静态规则集集。具有在 options.disableRulesetIds 中列出的 ID 的规则集首先被删除，然后在 options.enableRulesetIds 中列出的规则集被添加。请注意，已启用的静态规则集集跨会话保留，但不会跨扩展程序更新保留，即 rule_resources 清单键将确定每次扩展更新时启用的静态规则集集。

PARAMETERS

  • options

    UpdateRulesetOptions

    Chrome 87+

  • callback

    function optional

    The callback parameter looks like:

    () => void

RETURNS

  • Promise<void>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

updateSessionRules

chrome.declarativeNetRequest.updateSessionRules( options: UpdateRuleOptions, callback?: function, )

Promise Chrome 90+

修改扩展的当前会话范围规则集。具有在 options.removeRuleIds 中列出的 ID 的规则首先被删除，然后在 options.addRules 中给出的规则被添加。笔记：

  • 此更新作为单个原子操作发生：添加和删除所有指定的规则，或者返回错误。
  • 这些规则不会跨会话持续存在，而是在内存中提供支持。
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES 是扩展可以添加的组合动态和会话规则的最大数量。

PARAMETERS

  • options

    UpdateRuleOptions

  • callback

    function optional

    The callback parameter looks like:

    () => void

RETURNS

  • Promise<void>

    Pending

    这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

Events

onRuleMatchedDebug 

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

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

PARAMETERS

By.一粒技术服务

results matching ""

    No results matching ""