chrome.declarativeNetRequest

說明

chrome.declarativeNetRequest API 可用於指定宣告式規則，藉此封鎖或修改網路要求。這樣一來，擴充功能就能修改網路要求，而不必攔截並查看內容，進而提供更完善的隱私權保護。

權限

declarativeNetRequest
declarativeNetRequestWithHostAccess

「declarativeNetRequest」和「declarativeNetRequestWithHostAccess」權限提供相同的功能。兩者之間的差異在於權限要求或授予的時間。

"declarativeNetRequest"
會在安裝時觸發權限警告，但會提供對 allow、allowAllRequests 和 block 規則的隱含存取權。盡可能使用這個選項，避免需要要求主機的完整存取權。
"declarativeNetRequestFeedback"
為未封裝的擴充功能啟用偵錯功能，特別是 getMatchedRules() 和 onRuleMatchedDebug。
"declarativeNetRequestWithHostAccess"
系統不會在安裝時顯示權限警告，但您必須先要求主機權限，才能在主機上執行任何動作。在已擁有主機權限的擴充功能中使用宣告式網際要求規則，且不產生額外警告時，這項做法就很適合。

可用性

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"
    },
    ...
    ]
  }
  ...
}

如要測試規則檔案，請載入未解壓縮的擴充功能。只有在解壓縮的擴充功能中，才會顯示無效 Static 規則的錯誤和警告。系統會忽略已封裝擴充功能中的無效靜態規則。

快速審查

您可以將靜態規則集的變更內容提交審查，請參閱適用於符合資格的變更的快速審查服務。

啟用及停用靜態規則和規則集

個別靜態規則和完整的靜態規則集皆可在執行階段啟用或停用。

已啟用的靜態規則和規則集會在瀏覽器工作階段中保留。這兩者都不會在擴充功能更新後保留，也就是說，只有您選擇保留在規則檔案中的規則會在更新後可用。

基於效能考量，一次可啟用的規則和規則集數量也有限制。呼叫 getAvailableStaticRuleCount() 即可查看可啟用的額外規則數量。如要瞭解規則限制，請參閱「規則限制」。

如要啟用或停用靜態規則，請呼叫 updateStaticRules()。這個方法會採用 UpdateStaticRulesOptions 物件，其中包含要啟用或停用的規則 ID 陣列。這些 ID 是使用 Ruleset 字典的 "id" 鍵定義。停用的靜態規則上限為 5000 個。

如要啟用或停用靜態 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"]
  }
}

網址比對

宣告式網際網路要求可讓您使用模式比對語法或規則運算式比對網址。

網址篩選器語法

規則的 "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 會為每個擴充功能，在每個要求中挑選最多一個候選項目。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 時會受到一些限制。限制取決於您使用的規則類型。

靜態規則

靜態規則是指在資訊清單檔案中宣告的規則檔案中指定的規則。擴充功能最多可在 "rule_resources" 資訊清單鍵中指定 100 個靜態規則集，但一次只能啟用其中 50 個。後者稱為 MAX_NUMBER_OF_ENABLED_STATIC_RULESETS。這些規則集合保證至少包含 30,000 個規則。這就是所謂的 GUARANTEED_MINIMUM_STATIC_RULES。

之後可用的規則數量取決於使用者瀏覽器上安裝的所有擴充功能啟用多少規則。您可以在執行階段呼叫 getAvailableStaticRuleCount()，找到這個號碼。您可以在「程式碼範例」下方查看這項功能的範例。

工作階段規則

擴充功能最多可包含 5,000 個工作階段規則。這會以 MAX_NUMBER_OF_SESSION_RULES 的形式公開。

在 Chrome 120 之前，動態和工作階段規則的總數上限為 5000 個。

動態規則

擴充功能至少可包含 5,000 個動態規則。這會以 MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES 的形式公開。

自 Chrome 121 起，安全動態規則的限制已提高至 30,000 個規則，並以 MAX_NUMBER_OF_DYNAMIC_RULES 的形式公開。超過 5000 個限制的任何不安全規則，也會計入這項限制。

在 Chrome 120 之前，動態和工作階段規則的總數上限為 5000 個。

使用規則運算式的規則

所有類型的規則都可以使用規則運算式，但每種類型的規則運算式總數不得超過 1000 個。這就是所謂的 MAX_NUMBER_OF_REGEX_RULES。

此外，每項規則在編譯後的大小不得超過 2 KB。這大致與規則的複雜度相關。如果嘗試載入的規則超過此上限，系統會顯示類似下方的警告，並忽略該規則。

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

與服務工作程式互動

declarativeNetRequest 僅適用於到達網路堆疊的請求。這包括 HTTP 快取的回應，但可能不包括透過服務工作者的 onfetch 處理常式傳送的回應。declarativeNetRequest 不會影響服務工作者產生的回應，或從 CacheStorage 擷取的回應，但會影響服務工作者對 fetch() 所做的呼叫。

網路無障礙資源

declarativeNetRequest 規則無法將公開資源要求重新導向至無法透過網路存取的資源。這麼做會觸發錯誤。即使指定的網頁存取資源由重新導向擴充功能擁有，也是如此。如要為 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 如何為擴充功能中的規則排定優先順序。查看這些規則時，建議您在另一個視窗中開啟優先順序規則。

「priority」鍵

這些範例需要主機權限才能存取 *://*.example.com/*。

如要找出特定網址的優先順序，請查看 (開發人員定義的) "priority" 鍵、"action" 鍵和 "urlFilter" 鍵。這些範例會參照下方顯示的規則檔案範例。

前往 https://google.com
有兩個規則涵蓋這個網址：ID 為 1 和 4 的規則。由於 "block" 動作的優先順序高於 "redirect" 動作，因此會套用 ID 為 1 的規則。其他規則不適用，因為它們適用於較長的網址。
前往 https://google.com/1234
由於網址較長，ID 為 2 的規則現在除了與 ID 為 1 和 4 的規則相符外，也與其他規則相符。系統會套用 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

    boolean 選填

    是否要自動將網頁的動作計數顯示為擴充功能的徽章文字。這項偏好設定會在工作階段之間保留。

  • 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[] 選填

    如果指定此條件，只要標頭值與清單中的至少一個模式相符，就會符合條件。這項功能支援不區分大小寫的標頭值比對，以及下列結構：

    '*'：比對任意數量的字元。

    '?'：比對零或一個字元。

    您可以使用反斜線逸出「*」和「?」，例如「\*」和「\?」

HeaderOperation

Chrome 86 以上版本

這裡說明「modifyHeaders」規則的可能運算。

列舉

"append"
為指定的標頭新增項目。這項作業不支援要求標頭。

"set"
為指定標頭設定新值，並移除所有同名現有標頭。

"remove"
移除指定標頭的所有項目。

IsRegexSupportedResult

Chrome 87 以上版本

屬性

  • isSupported

    布林值

  • reason

    UnsupportedRegexReason 選填

    指出不支援規則運算式的理由。只有在 isSupported 為 false 時才會提供。

MatchedRule

屬性

  • ruleId

    數字

    相符規則的 ID。

  • rulesetId

    字串

    此規則所屬的 Ruleset ID。如果規則源自一組動態規則，則會等同於 DYNAMIC_RULESET_ID。

MatchedRuleInfo

屬性

  • 規則

    MatchedRule

  • tabId

    數字

    如果分頁仍處於活動狀態，則為該分頁的 tabId。否則為 -1。

  • timeStamp

    數字

    符合規則的時間。時間戳記會對應至 JavaScript 時間慣例，也就是自 Epoch 紀元起算的毫秒數。

MatchedRuleInfoDebug

屬性

MatchedRulesFilter

屬性

  • minTimeStamp

    號碼 選填

    如果指定此選項，系統只會比對指定時間戳記之後的規則。

  • tabId

    號碼 選填

    如果指定，則只會比對指定分頁的規則。如果設為 -1，則會比對未與任何有效分頁相關聯的規則。

ModifyHeaderInfo

Chrome 86 以上版本

屬性

  • 標頭

    字串

    要修改的標頭名稱。

  • 要對標頭執行的作業。

  • 值

    string 選填

    標頭的新值。必須為 append 和 set 作業指定。

QueryKeyValue

屬性

  • 金鑰

    字串

  • replaceOnly

    boolean 選填

    Chrome 94 以上版本

    如果為 true，系統只會在查詢鍵已存在的情況下進行替換。否則，如果缺少鍵，系統也會新增該鍵。預設值為 false。

  • 值

    字串

QueryTransform

屬性

  • addOrReplaceParams

    QueryKeyValue[] 選用

    要新增或取代的查詢鍵/值組合清單。

  • removeParams

    string[] 選填

    要移除的查詢鍵清單。

Redirect

屬性

  • extensionPath

    string 選填

    相對於擴充功能目錄的路徑。開頭應為「/」。

  • regexSubstitution

    string 選填

    指定 regexFilter 的規則替換模式。網址中第一個相符的 regexFilter 會替換為這個模式。在 regexSubstitution 中，您可以使用反斜線逸出數字 (\1 到 \9) 插入對應的擷取群組。\0 是指整個相符的文字。

  • transform

    URLTransform 選用

    要執行的網址轉換作業。

  • 網址

    string 選填

    重新導向網址。不允許重新導向至 JavaScript 網址。

RegexOptions

Chrome 87 以上版本

屬性

  • isCaseSensitive

    boolean 選填

    指定的 regex 是否區分大小寫。預設值為 true。

  • 規則運算式

    字串

    要檢查的規則運算式。

  • requireCapturing

    boolean 選填

    指定的 regex 是否需要擷取。只有指定 regexSubstition 動作的重新導向規則需要擷取。預設值為 false。

RequestDetails

屬性

  • documentId

    string 選填

    Chrome 106 以上版本

    如果這項要求是針對框架，則為框架文件的專屬 ID。

  • documentLifecycle

    DocumentLifecycle 選填

    Chrome 106 以上版本

    如果這項要求是針對影格，則為影格文件的生命週期。

  • frameId

    數字

    值為 0 表示要求發生在主框架中；正值則表示要求發生在子框架中的 ID。如果載入 (子)框架的文件 (type 為 main_frame 或 sub_frame)，frameId 會指出此框架的 ID，而非外框架的 ID。一個分頁中，影格 ID 不得重複。

  • frameType

    FrameType 選填

    Chrome 106 以上版本

    如果這項要求是針對影格，則為影格的類型。

  • 發起者

    string 選填

    要求的來源。這項設定不會因重新導向而變更。如果這是不透明來源，系統會使用字串「null」。

  • method

    字串

    標準 HTTP 方法。

  • parentDocumentId

    string 選填

    Chrome 106 以上版本

    如果這項要求是針對框架，且有父項，則為框架父項文件的專屬 ID。

  • parentFrameId

    數字

    包裝傳送要求的框架的 ID。如果不存在上層頁框，請將這個屬性的值設為 -1。

  • requestId

    字串

    要求的 ID。請求 ID 在瀏覽器工作階段中是唯一的。

  • tabId

    數字

    要求發生的索引標籤 ID。如果要求與分頁無關，請設為 -1。

  • 類型

    ResourceType

    要求的資源類型。

  • 網址

    字串

    要求的 URL。

RequestMethod

Chrome 91 以上版本

這會說明網路要求的 HTTP 要求方法。

列舉

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

此值說明網路要求的資源類型。

列舉

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

「ping」

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

屬性

  • 動作

    RuleAction

    符合這項規則時採取的動作。

  • 條件

    RuleCondition

    觸發這項規則的條件。

  • id

    數字

    用於唯一識別規則的 ID。為必要欄位，且應大於或等於 1。

  • 優先順序

    號碼 選填

    規則優先順序。默認為1。如有指定，應為 >= 1。

RuleAction

屬性

  • 重新導向

    Redirect 選填

    說明應如何執行重新導向。僅適用於重新導向規則。

  • 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 版起已淘汰

    改用 initiatorDomains

    這項規則只會比對來自 domains 清單的網路要求。

  • excludedDomains

    string[] 選填

    自 Chrome 101 版起已淘汰

    改用 excludedInitiatorDomains

    規則不會比對來自 excludedDomains 清單的網路要求。

  • excludedInitiatorDomains

    string[] 選填

    Chrome 101 以上版本

    這個規則不會比對來自 excludedInitiatorDomains 清單的網路要求。如果清單為空白或未提供，系統就不會排除任何網域。優先於 initiatorDomains。

    注意：

    • 系統也允許使用「a.example.com」等子網域。
    • 項目只能由 ASCII 字元組成。
    • 使用域名代碼編碼來處理國際化網域。
    • 這項比對會與要求發起者相符，而非要求網址。
    • 系統也會排除所列網域的子網域。
  • excludedRequestDomains

    string[] 選填

    Chrome 101 以上版本

    如果網域與 excludedRequestDomains 清單中的網域相符，則規則不會比對網路要求。如果清單為空白或未提供，系統就不會排除任何網域。優先於 requestDomains。

    注意：

    • 系統也允許使用「a.example.com」等子網域。
    • 項目只能由 ASCII 字元組成。
    • 使用域名代碼編碼來處理國際化網域。
    • 系統也會排除所列網域的子網域。
  • 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 字元組成。
    • 使用域名代碼編碼來處理國際化網域。
    • 這項比對會與要求發起者相符，而非要求網址。
    • 系統也會比對所列網域的子網域。
  • isUrlFilterCaseSensitive

    boolean 選填

    urlFilter 或 regexFilter (視指定的項目而定) 是否區分大小寫。預設值為 false。

  • regexFilter

    string 選填

    用於比對網路要求網址的規則運算式。這會遵循 RE2 語法。

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

    注意：regexFilter 只能由 ASCII 字元組成。這會與網址進行比對，其中主機會以 Punycode 格式編碼 (如果是國際化網域)，而任何其他非 ASCII 字元則會以 UTF-8 編碼。

  • requestDomains

    string[] 選填

    Chrome 101 以上版本

    只有在網域與 requestDomains 清單中的網域相符時，規則才會比對網路要求。如果省略清單，規則就會套用至所有網域的請求。不得留空。

    注意：

    • 系統也允許使用「a.example.com」等子網域。
    • 項目只能由 ASCII 字元組成。
    • 使用域名代碼編碼來處理國際化網域。
    • 系統也會比對所列網域的子網域。
  • 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

    string 選填

    與網路要求網址相符的模式。支援的結構體：

    '*'：萬用字元：可比對任意數量的字元。

    '|'：左/右錨點：如果用於模式的任一端，則分別指定網址的開頭/結尾。

    '||'：網域名稱錨點：如果用於模式開頭，則會指定網址 (子) 網域的開頭。

    '^'：分隔符字元：會比對任何字元，但不包括字母、數字或下列字元：_、-、. 或 %。這也會比對網址結尾。

    因此，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 以上版本

屬性

  • 增加

    數字

    要增加分頁動作計數的值。負值會減少計數。

  • tabId

    數字

    要更新動作計數的分頁。

TestMatchOutcomeResult

Chrome 103 以上版本

屬性

  • matchedRules

    MatchedRule[]

    與假設請求相符的規則 (如有)。

TestMatchRequestDetails

Chrome 103 以上版本

屬性

  • 發起者

    string 選填

    假設要求的啟動器網址 (如有)。

  • method

    RequestMethod 選填

    假設要求的標準 HTTP 方法。對於 HTTP 要求，預設為「get」，對於非 HTTP 要求則會遭到忽略。

  • responseHeaders

    物件 選填

    Chrome 129 以上版本

    如果要求在傳送前未遭到封鎖或重新導向，假設回應會提供的標頭。以物件表示，可將標頭名稱對應至字串值清單。如果未指定，假設的回應會傳回空的回應標頭，而這些標頭可與不存在標頭的規則相符。例如：{"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    號碼 選填

    假設要求發生的分頁 ID。不必對應至實際的分頁 ID。預設值為 -1，表示要求與分頁無關。

  • 類型

    ResourceType

    假設要求的資源類型。

  • 網址

    字串

    假設要求的網址。

UnsupportedRegexReason

Chrome 87 以上版本

說明系統不支援指定規則運算式的理由。

列舉

"syntaxError"
規則運算式的語法不正確，或使用 RE2 語法 不支援的功能。

"memoryLimitExceeded"
規則運算式超出記憶體上限。

UpdateRuleOptions

Chrome 87 以上版本

屬性

  • addRules

    規則[] 選填

    要新增的規則。

  • 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

    string 選填

    請求的新片段。應為空白，在這種情況下，系統會清除現有的片段；或是開頭為「#」。

  • 主機

    string 選填

    請求的新主機。

  • 密碼

    string 選填

    要求的新密碼。

  • 路徑

    string 選填

    要求的新路徑。如果留空，系統會清除現有路徑。

  • 通訊埠

    string 選填

    要求的新通訊埠。如果留空，系統會清除現有的通訊埠。

  • 查詢

    string 選填

    請求的新查詢。應為空白，在這種情況下，系統會清除現有查詢；或應以「?」開頭。

  • queryTransform

    QueryTransform 選填

    新增、移除或取代查詢鍵/值組合。

  • 架構

    string 選填

    請求的新配置。允許的值包括「http」、「https」、「ftp」和「chrome-extension」。

  • 使用者名稱

    string 選填

    要求的新使用者名稱。

屬性

DYNAMIC_RULESET_ID

擴充功能新增的動態規則規則集 ID。

值

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules 通話可進行的時間間隔，以分鐘為單位。其他呼叫會立即失敗，並設定 runtime.lastError。注意：與使用者手勢相關的 getMatchedRules 呼叫不受配額限制。

值

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 以上版本

在啟用的靜態規則集之間，擴充功能可保證的靜態規則數量下限。超過這個上限的規則都會計入全域靜態規則限制。

值

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

GETMATCHEDRULES_QUOTA_INTERVAL 期間內可呼叫 getMatchedRules 的次數。

值

20

MAX_NUMBER_OF_DYNAMIC_RULES

擴充功能可新增的動態規則數量上限。

值

30000

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()

Promise Chrome 89 以上版本 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

在達到全域靜態規則限制之前，傳回擴充功能可啟用的靜態規則數量。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (count: number) => void

    • 數量

      數字

傳回

  • Promise<number>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getDisabledRuleIds()

Promise Chrome 111 以上版本 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

傳回目前已停用的指定 Ruleset 中的靜態規則清單。

參數

  • 指定要查詢的規則集。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

傳回

  • Promise<number[]>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

傳回擴充功能目前的動態規則組合。呼叫端可以選擇指定 filter，藉此篩選擷取的規則清單。

參數

  • 篩選器

    GetRulesFilter 選填

    Chrome 111 以上版本

    用於篩選擷取的規則清單的物件。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (rules: Rule[]) => void

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getEnabledRulesets()

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

傳回目前已啟用靜態規則集的 ID。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

傳回

  • Promise<string[]>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getMatchedRules()

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

傳回擴充功能相符的所有規則。呼叫端可以選擇指定 filter，藉此篩選符合條件的規則清單。這個方法僅適用於具有 "declarativeNetRequestFeedback" 權限的擴充功能，或是針對 filter 中指定的 tabId 授予 "activeTab" 權限的擴充功能。注意：如果規則與超過五分鐘前已啟用的文件不相符，系統就不會傳回該規則。

參數

傳回

  • Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getSessionRules()

Promise Chrome 90 以上版本 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

傳回擴充功能目前的工作階段範圍規則組合。呼叫端可以選擇指定 filter，藉此篩選擷取的規則清單。

參數

  • 篩選器

    GetRulesFilter 選填

    Chrome 111 以上版本

    用於篩選擷取的規則清單的物件。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (rules: Rule[]) => void

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

isRegexSupported()

Promise Chrome 87 以上版本 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

檢查是否支援指定規則運算式做為 regexFilter 規則條件。

參數

傳回

  • Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

setExtensionActionOptions()

Promise Chrome 88 以上版本 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

設定分頁的動作計數是否應顯示為擴充功能動作的徽章文字，並提供增加該動作計數的方法。

參數

  • 回呼

    函式 選填

    Chrome 89 以上版本

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

testMatchOutcome()

Promise Chrome 103 以上版本 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

檢查擴充功能的 declarativeNetRequest 規則是否會與假設要求相符。注意：這項功能僅適用於未封裝的擴充功能，因為這項功能僅供擴充功能開發期間使用。

參數

傳回

  • 承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

updateDynamicRules()

Promise 
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 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

updateEnabledRulesets()

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

更新擴充功能的已啟用靜態規則集。系統會先移除 options.disableRulesetIds 中列出的 ID 規則集，再新增 options.enableRulesetIds 中列出的規則集。請注意，啟用的靜態規則集會在工作階段之間保留，但不會在擴充功能更新之間保留，也就是說，rule_resources 資訊清單鍵會決定每個擴充功能更新的啟用靜態規則集。

參數

  • Chrome 87 以上版本
  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

updateSessionRules()

Promise Chrome 90 以上版本 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

修改擴充功能目前的工作階段範圍規則組合。系統會先移除 options.removeRuleIds 中列出的 ID 規則，再新增 options.addRules 中的規則。注意：

  • 這項更新會以單一原子作業執行：新增和移除所有指定的規則，或傳回錯誤。
  • 這些規則不會在不同工作階段間保留，而是儲存在記憶體中。
  • MAX_NUMBER_OF_SESSION_RULES 是擴充功能可新增的會話規則數量上限。

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

updateStaticRules()

Promise Chrome 111 以上版本 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

在 Ruleset 中停用及啟用個別靜態規則。屬於停用的 Ruleset 規則的變更，會在下次啟用時生效。

參數

傳回

  • Promise<void>

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onRuleMatchedDebug

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

當規則與要求比對成功時觸發。此權限僅適用於具有 "declarativeNetRequestFeedback" 權限的解封擴充功能，因為這項權限僅供偵錯使用。

參數