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 類型字典的陣列，如下所示。(請注意，由於「規則集」只是陣列，因此不會出現在資訊清單的 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" 鍵定義。最多只能停用 5000 個靜態規則。

如要啟用或停用靜態規則集，請呼叫 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"]
  }
}

網址比對

Declarative Net Request 可讓您使用模式比對語法或規則運算式比對網址。

網址篩選器語法

規則的 "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:\/\/p.rizon.top:443\/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 時會受到一些限制。限制取決於您使用的規則類型。

靜態規則

靜態規則是指資訊清單檔案中宣告的規則檔案所指定的規則。擴充功能最多可指定 100 個靜態規則集，做為 "rule_resources" 資訊清單鍵的一部分，但一次只能啟用 50 個規則集。後者稱為「MAX_NUMBER_OF_ENABLED_STATIC_RULESETS」。這些規則集加總起來，保證至少有 30,000 條規則。這就是所謂的 GUARANTEED_MINIMUM_STATIC_RULES。

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

工作階段規則

擴充功能最多可有 5000 項工作階段規則。這會以 MAX_NUMBER_OF_SESSION_RULES 形式公開。

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

動態規則

擴充功能至少要有 5000 條動態規則。這會以 MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES 形式公開。

自 Chrome 121 起，安全動態規則的上限將提高至 30,000 條，並以 MAX_NUMBER_OF_DYNAMIC_RULES 形式公開。在 5000 條規則的限制內新增任何不安全的規則，也會計入這項限制。

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

使用規則運算式的規則

所有類型的規則都可以使用規則運算式，但每種類型的規則運算式規則總數不得超過 1, 000 個。這稱為「MAX_NUMBER_OF_REGEX_RULES」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" 陣列。

修改標頭

附加作業僅支援下列標頭：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」鍵

這些範例需要 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()

Chrome 89 以上版本 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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

傳回

  • Promise<number>

    Chrome 91 以上版本

getDisabledRuleIds()

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

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

參數

傳回

  • Promise<number[]>

getDynamicRules()

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

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

參數

  • 篩選

    GetRulesFilter optional

    Chrome 111 以上版本

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

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

getEnabledRulesets()

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

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

傳回

  • Promise<string[]>

    Chrome 91 以上版本

getMatchedRules()

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

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

參數

傳回

getSessionRules()

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

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

參數

  • 篩選

    GetRulesFilter optional

    Chrome 111 以上版本

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

傳回

  • Promise<Rule[]>

    Chrome 91 以上版本

isRegexSupported()

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

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

參數

傳回

setExtensionActionOptions()

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

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

參數

傳回

  • Promise<void>

    Chrome 91 以上版本

testMatchOutcome()

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

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

參數

傳回

updateDynamicRules()

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

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

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

參數

傳回

  • Promise<void>

    Chrome 91 以上版本

updateEnabledRulesets()

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

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

參數

傳回

  • Promise<void>

    Chrome 91 以上版本

updateSessionRules()

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

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

  • 這項更新會以單一不可分割的操作進行：新增及移除所有指定規則，或傳回錯誤。
  • 這些規則不會跨工作階段保留，而是備份在記憶體中。
  • 擴充功能最多可新增 MAX_NUMBER_OF_SESSION_RULES 個工作階段規則。

參數

傳回

  • Promise<void>

    Chrome 91 以上版本

updateStaticRules()

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

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

參數

傳回

  • Promise<void>

事件

onRuleMatchedDebug

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

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

參數