chrome.declarativeNetRequest

說明

chrome.declarativeNetRequest API 可透過指定宣告式規則，封鎖或修改網路要求。擴充功能可藉此修改網路要求，不必攔截要求或查看內容，因此能提供更多隱私權保障。

權限

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

可用性

Chrome 84 以上版本

資訊清單

除了上述權限外，特定類型的規則集 (尤其是靜態規則集) 必須宣告 "declarative_net_request" 資訊清單鍵，該鍵應為具有單一鍵 (稱為 "rule_resources") 的字典。這個鍵是包含 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()，取得這個號碼。您可以在程式碼範例中查看這項功能的範例。

動態和工作階段規則

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

使用規則運算式的規則

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

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

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 規則無法將公開資源要求重新導向至無法透過網路存取的資源。否則會觸發錯誤。即使指定的網頁可存取資源屬於重新導向的擴充功能，也是如此。如要為 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」鍵

這些範例需要 host 權限才能存取 *://*.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
這四條規則都與這個網址相符。由於規則 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

    字串陣列 選用

    如果指定了這項條件，但標頭存在，且標頭值包含這個清單中的至少一個元素，則不符合條件。這項功能使用的比對模式語法與 values 相同。

  • 標頭

    字串

    標題名稱。如果未指定 values 和 excludedValues，這個條件只會比對名稱。

  • 值

    字串陣列 選用

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

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

    「?」：比對零或一個字元。

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

HeaderOperation

Chrome 86 以上版本

說明「modifyHeaders」規則的可能作業。

列舉

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

「set」
為指定標頭設定新值，並移除任何同名的現有標頭。

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

IsRegexSupportedResult

Chrome 87 以上版本

屬性

  • isSupported

    布林值

  • 原因

    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

    字串陣列 選用

    要移除的查詢鍵清單。

Redirect

屬性

  • extensionPath

    字串 選填

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

  • regexSubstitution

    字串 選填

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

  • transform

    URLTransform 選用

    要執行的網址轉換。

  • 網址

    字串 選填

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

RegexOptions

Chrome 87 以上版本

屬性

  • isCaseSensitive

    布林值 選填

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

  • 規則運算式

    字串

    要檢查的規則運算式。

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

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

  • 發起者

    字串 選填

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

  • method

    字串

    標準 HTTP 方法。

  • parentDocumentId

    字串 選填

    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

屬性

  • 重新導向

    重新導向 選用

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

  • requestHeaders

    ModifyHeaderInfo[] 選用

    Chrome 86 以上版本

    要為要求修改的要求標頭。只有在 RuleActionType 為「modifyHeaders」時才有效。

  • responseHeaders

    ModifyHeaderInfo[] 選用

    Chrome 86 以上版本

    要為要求修改的回應標頭。只有在 RuleActionType 為「modifyHeaders」時才有效。

  • 要執行的動作類型。

RuleActionType

說明在特定 RuleCondition 相符時要採取的動作類型。

列舉

「封鎖」
封鎖網路要求。

「redirect」
重新導向網路要求。

「allow」
允許網路要求。如果存在與要求相符的允許規則，系統就不會攔截要求。

「upgradeScheme」
如果要求是 http 或 ftp，請將網路要求網址的協定升級為 https。

「modifyHeaders」
修改網路要求的請求/回應標頭。

「allowAllRequests」
允許影格階層中的所有要求，包括影格要求本身。

RuleCondition

屬性

  • domainType

    DomainType 選用

    指定網路要求是來自原始網域的第一方或第三方。如果省略，系統會接受所有要求。

  • 網域

    字串陣列 選用

    Chrome 101 版起已淘汰

    請改用 initiatorDomains

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

  • excludedDomains

    字串陣列 選用

    Chrome 101 版起已淘汰

    請改用 excludedInitiatorDomains

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

  • excludedInitiatorDomains

    字串陣列 選用

    Chrome 101 以上版本

    這項規則不會比對來自 excludedInitiatorDomains 清單的網路要求。如果清單為空白或省略，系統不會排除任何網域。優先順序高於 initiatorDomains。

    注意：

    • 也允許使用子網域，例如「a.example.com」。
    • 輸入內容只能包含 ASCII 字元。
    • 如果是國際化網域，請使用域名代碼編碼。
    • 這項比對是針對要求發起人，而非要求網址。
    • 列出網域的子網域也會排除。
  • excludedRequestDomains

    字串陣列 選用

    Chrome 101 以上版本

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

    注意：

    • 也允許使用子網域，例如「a.example.com」。
    • 輸入內容只能包含 ASCII 字元。
    • 如果是國際化網域，請使用域名代碼編碼。
    • 列出網域的子網域也會排除。
  • excludedRequestMethods

    RequestMethod[] 選填

    Chrome 91 以上版本

    規則不會比對的要求方法清單。只能指定 requestMethods 和 excludedRequestMethods 其中之一。如果兩者皆未指定，系統會比對所有要求方法。

  • excludedResourceTypes

    ResourceType[] optional

    規則不會比對的資源類型清單。只能指定 resourceTypes 和 excludedResourceTypes 其中之一。如果兩者皆未指定，系統會封鎖「main_frame」以外的所有資源類型。

  • excludedResponseHeaders

    HeaderInfo[] 選用

    Chrome 128 以上版本

    如果要求符合這個清單中的任何回應標頭條件 (如有指定)，規則就不會相符。如果同時指定 excludedResponseHeaders 和 responseHeaders，系統會優先採用 excludedResponseHeaders 屬性。

  • excludedTabIds

    number[] 選填

    Chrome 92 以上版本

    規則不應相符的 tabs.Tab.id 清單。ID 為 tabs.TAB_ID_NONE 時，系統會排除並非源自分頁的要求。僅支援工作階段範圍規則。

  • initiatorDomains

    字串陣列 選用

    Chrome 101 以上版本

    這項規則只會比對來自 initiatorDomains 清單的網路要求。如果省略清單，規則會套用至來自所有網域的請求。清單不得留空。

    注意：

    • 也允許使用子網域，例如「a.example.com」。
    • 輸入內容只能包含 ASCII 字元。
    • 如果是國際化網域，請使用域名代碼編碼。
    • 這項比對是針對要求發起人，而非要求網址。
    • 系統也會比對所列網域的子網域。
  • isUrlFilterCaseSensitive

    布林值 選填

    urlFilter 或 regexFilter (指定的屬性) 是否區分大小寫。預設值為 false。

  • regexFilter

    字串 選填

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

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

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

  • requestDomains

    字串陣列 選用

    Chrome 101 以上版本

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

    注意：

    • 也允許使用子網域，例如「a.example.com」。
    • 輸入內容只能包含 ASCII 字元。
    • 如果是國際化網域，請使用域名代碼編碼。
    • 系統也會比對所列網域的子網域。
  • requestMethods

    RequestMethod[] 選填

    Chrome 91 以上版本

    規則可比對的 HTTP 要求方法清單。清單不得留空。

    注意：指定 requestMethods 規則條件也會排除非 HTTP(s) 要求，但指定 excludedRequestMethods 則不會。

  • resourceTypes

    ResourceType[] optional

    規則可比對的資源類型清單。清單不得留空。

    注意：這必須為 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 以上版本

屬性

  • 增加

    數字

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

  • tabId

    數字

    要更新動作計數的分頁。

TestMatchOutcomeResult

Chrome 103 以上版本

屬性

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 以上版本

屬性

  • 發起者

    字串 選填

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

  • method

    RequestMethod 選填

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

  • responseHeaders

    object 選填

    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

    字串陣列 選用

    應停用的靜態 Ruleset 對應 ID 集。

  • enableRulesetIds

    字串陣列 選用

    應啟用的靜態 Ruleset 對應 ID 集。

UpdateStaticRulesOptions

Chrome 111 以上版本

屬性

  • disableRuleIds

    number[] 選填

    與要停用的 Ruleset 中的規則對應的 ID 集。

  • enableRuleIds

    number[] 選填

    要啟用的 Ruleset 中規則對應的 ID 集。

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

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

參數

  • callback

    函式 選用

    callback 參數如下： 

    (count: number) => void

    • 數量

      數字

傳回

  • Promise<number>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getDisabledRuleIds()

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

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

參數

  • 指定要查詢的規則集。

  • callback

    函式 選用

    callback 參數如下： 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

傳回

  • Promise<number[]>

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getDynamicRules()

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

傳回擴充功能的目前動態規則集。來電者可以指定 filter，選擇性地篩選擷取的規則清單。

參數

  • 篩選

    GetRulesFilter optional

    Chrome 111 以上版本

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

  • callback

    函式 選用

    callback 參數如下： 

    (rules: Rule[]) => void

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getEnabledRulesets()

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

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

參數

  • callback

    函式 選用

    callback 參數如下： 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

傳回

  • Promise<string[]>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getMatchedRules()

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

傳回擴充功能的所有相符規則。來電者可以選擇指定 filter，篩選相符規則清單。只有具備 "declarativeNetRequestFeedback" 權限的擴充功能，或已獲授權可存取 filter 中指定的 tabId 的擴充功能，才能使用這個方法。"activeTab"注意：系統不會傳回與有效文件無關，且在五分鐘前比對成功的規則。

參數

傳回

  • Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

getSessionRules()

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

傳回擴充功能目前的一組工作階段範圍規則。來電者可以指定 filter，選擇性地篩選擷取的規則清單。

參數

  • 篩選

    GetRulesFilter optional

    Chrome 111 以上版本

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

  • callback

    函式 選用

    callback 參數如下： 

    (rules: Rule[]) => void

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

isRegexSupported()

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

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

參數

傳回

  • Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

setExtensionActionOptions()

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

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

參數

  • callback

    函式 選用

    Chrome 89 以上版本

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

testMatchOutcome()

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

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

參數

傳回

  • 只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

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

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

updateEnabledRulesets()

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

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

參數

  • Chrome 87 以上版本
  • callback

    函式 選用

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

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

傳回

  • Promise<void>

    Chrome 91 以上版本

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

updateStaticRules()

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

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

參數

傳回

  • Promise<void>

    只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

onRuleMatchedDebug

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

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

參數