chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

說明

chrome.declarativeNetRequest API 可透過指定宣告式規則，封鎖或修改網路要求。這樣一來，擴充功能就能修改網路要求，而不必攔截要求並查看內容，進一步保障隱私。

權限

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

可用性

Chrome 84 以上版本

資訊清單

除了上述權限外，某些類型的規則集 (尤其是靜態規則集) 需要宣告 "declarative_net_request" 資訊清單鍵，該鍵應為包含單一鍵 "rule_resources" 的字典。這個鍵是包含 Ruleset 類型字典的陣列，如下所示。(請注意，資訊清單的 JSON 中不會顯示「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",
  ],
  "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()，找出這個數字。請參閱程式碼範例中的範例。

動態和工作階段規則

動態和工作階段規則的限制比靜態規則簡單。兩者總數不得超過 5,000。這稱為 MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES。

使用規則運算式的規則

所有類型的規則都可以使用規則運算式，但每種類型的規則運算式規則總數不得超過 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.

與 Service Worker 互動

declarativeNetRequest 僅適用於到達網路堆疊的要求。這包括來自 HTTP 快取的回應，但不一定包括透過 Service Worker 的 onfetch 處理常式傳送的回應。declarativeNetRequest 不會影響 Service Worker 產生的回應，或從 CacheStorage 擷取的回應，但會影響在 Service Worker 中對 fetch() 的呼叫。

可透過網路存取的資源

declarativeNetRequest 規則無法將公開資源要求重新導向至無法透過網路存取的資源。否則會發生錯誤。即使指定的網頁可存取資源屬於重新導向擴充功能，也是如此。如要宣告 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 的規則。由於「"block"」動作的優先順序高於「"redirect"」動作，因此系統會套用 ID 為 1 的規則。其餘規則不適用，因為這些規則適用於較長的網址。
前往 https://google.com/1234
由於網址較長，除了 ID 為 1 和 4 的規則外，現在 ID 為 2 的規則也符合條件。由於 "allow" 的優先順序高於 "block" 和 "redirect"，因此系統會套用 ID 為 2 的規則。
前往 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[] 選填

    如果指定這項條件，只要標頭值符合這份清單中的至少一個模式，即視為符合條件。這項功能支援不區分大小寫的標頭值比對，以及下列建構項目：

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

    ?：比對零或一個字元。

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

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

屬性

  • 標頭

    字串

    要修改的標頭名稱。

  • 要對標頭執行的作業。

  • 值

    字串 選填

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

QueryKeyValue

屬性

  • 金鑰

    字串

  • replaceOnly

    布林值 選填

    Chrome 94 以上版本

    如果設為 true，只有在查詢鍵已存在時，才會替換查詢鍵。否則，如果缺少金鑰，系統也會新增金鑰。預設值為 false。

  • 值

    字串

QueryTransform

屬性

  • addOrReplaceParams

    QueryKeyValue[] 選用

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

  • removeParams

    string[] 選填

    要移除的查詢鍵清單。

Redirect

屬性

  • extensionPath

    字串 選填

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

  • regexSubstitution

    字串 選填

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

  • transform

    URLTransform 選用

    要執行的網址轉換。

  • 網址

    字串 選填

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

RegexOptions

Chrome 87 以上版本

屬性

  • isCaseSensitive

    布林值 選填

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

  • regex

    字串

    要檢查的規則運算式。

  • requireCapturing

    布林值 選填

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

RequestDetails

屬性

  • documentId

    字串 選填

    Chrome 106 以上版本

    頁框文件的專屬 ID (如果這是頁框要求)。

  • documentLifecycle

    DocumentLifecycle 選填

    Chrome 106 以上版本

    如果要求是針對頁框，則為頁框文件的生命週期。

  • frameId

    數字

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

  • frameType

    FrameType 選填

    Chrome 106 以上版本

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

  • initiator

    字串 選填

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

  • 方法

    字串

    標準 HTTP 方法。

  • parentDocumentId

    字串 選填

    Chrome 106 以上版本

    頁框上層文件的專屬 ID (如果這項要求是針對頁框，且有上層文件)。

  • parentFrameId

    數字

    包裝傳送要求頁框的頁框 ID。如果沒有上層頁框，請設為 -1。

  • requestId

    字串

    要求的 ID。在瀏覽器工作階段中，要求 ID 不得重複。

  • tabId

    數字

    要求所在分頁的 ID。如果要求與分頁無關，請設為 -1。

  • 類型

    ResourceType

    要求的資源類型。

  • 網址

    字串

    要求的 URL。

RequestMethod

Chrome 91 以上版本

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

列舉

"connect"

「刪除」

"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

屬性

  • 重新導向

    重新導向 選填

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

  • 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 字元。
    • 如果是國際化網域，請使用 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 清單。tabs.TAB_ID_NONE ID 會排除並非來自特定分頁的要求。僅支援以工作階段為範圍的規則。

  • excludedTopDomains

    string[] 選填

    Chrome 145 以上版本

    如果相關聯頂層框架的網域與 excludedTopDomains 清單中的網域相符，規則就不會比對網路要求。如果清單空白或省略，則不會排除任何網域。這項設定的優先順序高於 topDomains。

    注意：

    • 也可以使用「a.example.com」等子網域。
    • 項目只能包含 ASCII 字元。
    • 如果是國際化網域，請使用 Punycode 編碼。
    • 所列網域的子網域也會一併排除。
    • 如果要求沒有相關聯的頂層框架 (例如 ServiceWorker 啟動的要求)，系統會改為考量要求啟動器的網域。
  • 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 清單。tabs.TAB_ID_NONE 的 ID 會比對並非來自特定分頁的要求。清單不得留空。僅支援以工作階段為範圍的規則。

  • topDomains

    string[] 選填

    Chrome 145 以上版本

    只有在相關聯頂層框架的網域與 topDomains 清單中的網域相符時，規則才會比對網路要求。如果省略清單，規則會套用至與所有頂層框架網域相關聯的要求。清單不得留空。

    注意：

    • 也可以使用「a.example.com」等子網域。
    • 項目只能包含 ASCII 字元。
    • 如果是國際化網域，請使用 Punycode 編碼。
    • 列出網域的子網域也符合條件。
    • 如果要求沒有相關聯的頂層框架 (例如 ServiceWorker 啟動的要求)，系統會改為考量要求啟動器的網域。
  • urlFilter

    字串 選填

    與網路要求網址比對的模式。支援的建構：

    「*」：萬用字元，可比對任意數量的字元。

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

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

    '^'：分隔符字元：比對任何非字母、數字或下列任一字元的字元：_、-、. 或 %。這也符合網址結尾。

    因此，urlFilter 是由下列部分組成：(選用的左側/網域名稱錨定標記) + 模式 + (選用的右側錨定標記)。

    如果省略，則會比對所有網址。不得留空。

    不得使用開頭為 ||* 的模式。改用 *。

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

    注意：urlFilter 只能由 ASCII 字元組成。系統會比對網址，其中主機以 punycode 格式編碼 (如果是國際化網域)，任何其他非 ASCII 字元則以 UTF-8 網址編碼。舉例來說，如果要求網址是 http://abc.рф?q=ф，系統會比對 urlFilter 和網址 http://abc.xn--p1ai/?q=%D1%84。

RuleConditionKeys

Chrome 145 以上版本

列舉

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

屬性

  • 已啟用

    布林值

    規則集是否預設為啟用。

  • id

    字串

    不重複識別規則集的非空白字串。開頭為「_」的 ID 已預留供內部使用。

  • 路徑

    字串

    JSON 規則集的路徑 (相對於擴充功能目錄)。

RulesMatchedDetails

屬性

TabActionCountUpdate

Chrome 89 以上版本

屬性

  • 增加

    數字

    分頁動作次數的增量。負值會減少計數。

  • tabId

    數字

    要更新動作次數的分頁。

TestMatchOutcomeResult

Chrome 103 以上版本

屬性

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 以上版本

屬性

  • initiator

    字串 選填

    假設要求的發起者網址 (如有)。

  • 方法

    RequestMethod 選填

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

  • responseHeaders

    物件 選填

    Chrome 129 以上版本

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

  • tabId

    數字 選填

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

  • topUrl

    字串 選填

    Chrome 145 以上版本

    與要求相關聯的頂層頁框網址 (如有)。

  • 類型

    ResourceType

    假設要求的資源類型。

  • 網址

    字串

    假設要求的網址。

UnsupportedRegexReason

Chrome 87 以上版本

說明不支援指定規則運算式的原因。

列舉

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

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

UpdateRuleOptions

Chrome 87 以上版本

屬性

  • addRules

    Rule[] 選填

    要新增的規則。

  • removeRuleIds

    number[] 選填

    要移除的規則 ID。系統會忽略無效的 ID。

UpdateRulesetOptions

Chrome 87 以上版本

屬性

  • disableRulesetIds

    string[] 選填

    對應至應停用的靜態 Ruleset 的 ID 組合。

  • enableRulesetIds

    string[] 選填

    一組 ID，對應至應啟用的靜態 Ruleset。

UpdateStaticRulesOptions

Chrome 111 以上版本

屬性

  • disableRuleIds

    number[] 選填

    一組 ID，對應 Ruleset 中要停用的規則。

  • enableRuleIds

    number[] 選填

    一組 ID，對應至 Ruleset 中要啟用的規則。

  • rulesetId

    字串

    與靜態 Ruleset 對應的 ID。

URLTransform

屬性

  • fragment

    字串 選填

    要求的新片段。必須為空白 (現有片段會清除)，或以「#」開頭。

  • 主機

    字串 選填

    要求的新主機。

  • 密碼

    字串 選填

    要求的新密碼。

  • 路徑

    字串 選填

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

  • 通訊埠

    字串 選填

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

  • 查詢

    字串 選填

    要求的新查詢。必須為空白 (現有查詢會清除)，或開頭為「?」。

  • queryTransform

    QueryTransform 選填

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

  • 架構

    字串 選填

    要求的新配置。允許的值為「http」、「https」、「ftp」和「chrome-extension」。

  • 使用者名稱

    字串 選填

    要求的新使用者名稱。

屬性

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 在 GETMATCHEDRULES_QUOTA_INTERVAL 內可呼叫的次數。

值

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,
): Promise<number>

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

參數

  • callback

    函式 選填

    callback 參數如下： 

    (count: number) => void

    • 數量

      數字

傳回

  • Promise<number>

    Chrome 91 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getDisabledRuleIds()

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

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

參數

  • 指定要查詢的規則集。

  • callback

    函式 選填

    callback 參數如下： 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

傳回

  • Promise<number[]>

    Promise 會解析為與該規則集中停用規則相對應的 ID 清單。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getDynamicRules()

Promise 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

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

參數

  • 篩選器

    GetRulesFilter 選填

    Chrome 111 以上版本

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

  • callback

    函式 選填

    callback 參數如下： 

    (rules: Rule[]) => void

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

    Promise，會解析為一組動態規則。如果發生暫時性內部錯誤，Promise 可能會遭到拒絕。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getEnabledRulesets()

Promise 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

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

參數

  • callback

    函式 選填

    callback 參數如下： 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

傳回

  • Promise<string[]>

    Chrome 91 以上版本

    Promise 會解析為 ID 清單，其中每個 ID 都對應至已啟用的靜態 Ruleset。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getMatchedRules()

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

傳回與擴充功能相符的所有規則。呼叫端可以選擇指定 filter，篩選相符規則清單。這個方法僅適用於具備 "declarativeNetRequestFeedback" 權限，或已針對 filter 中指定的 tabId 授予 "activeTab" 權限的擴充功能。注意：如果規則未與有效文件建立關聯，且比對時間超過五分鐘，系統就不會傳回這類規則。

參數

傳回

  • Chrome 91 以上版本

    擷取相符規則清單後，Promise 就會解析。如果發生錯誤，Promise 會遭到拒絕。這可能是因為權限不足或超出配額等原因。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getSessionRules()

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

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

參數

  • 篩選器

    GetRulesFilter 選填

    Chrome 111 以上版本

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

  • callback

    函式 選填

    callback 參數如下： 

    (rules: Rule[]) => void

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

    Promise，會解析為一組工作階段範圍規則。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

isRegexSupported()

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

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

參數

傳回

  • Chrome 91 以上版本

    Promise 會解析為詳細資料，包括是否支援規則運算式，以及不支援的原因。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

setExtensionActionOptions()

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

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

參數

  • callback

    函式 選填

    Chrome 89 以上版本

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

testMatchOutcome()

Promise Chrome 103+ 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

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

參數

傳回

  • Promise，可解析為相符規則的詳細資料。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

updateDynamicRules()

Promise 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

修改擴充功能目前的動態規則集。系統會先移除 options.removeRuleIds 中列出的 ID 規則，然後新增 options.addRules 中提供的規則。注意：

  • 這項更新會以單一不可分割作業的形式執行：系統會新增及移除所有指定規則，或傳回錯誤。
  • 這些規則會在瀏覽器工作階段和擴充功能更新期間保留。
  • 這項函式無法移除擴充功能套件中指定的靜態規則。
  • MAX_NUMBER_OF_DYNAMIC_RULES 是擴充功能可新增的動態規則數量上限。不安全規則數量不得超過 MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES。

參數

  • Chrome 87 以上版本
  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

    更新完成後會解析的 Promise。如果發生錯誤，系統會拒絕 promise，且不會對規則集進行任何變更。可能原因包括規則格式無效、規則 ID 重複、超出規則數量上限、內部錯誤等。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

updateEnabledRulesets()

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

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

參數

  • Chrome 87 以上版本
  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

    更新完成後會解析的 Promise。如果發生錯誤，系統會拒絕 promise，且不會變更已啟用的規則集。可能原因包括規則集 ID 無效、超過規則數量上限，或發生內部錯誤。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

updateSessionRules()

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

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

  • 這項更新會以單一不可分割作業的形式執行：系統會新增及移除所有指定規則，或傳回錯誤。
  • 這些規則不會在工作階段之間保留，而是備份在記憶體中。
  • MAX_NUMBER_OF_SESSION_RULES 是擴充功能可新增的工作階段規則數量上限。

參數

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

    更新完成後會解析的 Promise。如果發生錯誤，系統會拒絕 promise，且不會對規則集進行任何變更。可能原因包括規則格式無效、規則 ID 重複、超出規則數量上限等。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

updateStaticRules()

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

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

參數

傳回

  • 承諾<void>

    更新完成後會解析的 Promise。如果發生錯誤，系統會拒絕 Promise，且不會變更已啟用的靜態規則。

    Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

事件

onRuleMatchedDebug

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

規則與要求相符時觸發。僅適用於具備 "declarativeNetRequestFeedback" 權限的未封裝擴充功能，因為這項功能僅供偵錯使用。

參數