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，請指定一或多個規則集。規則集包含規則陣列。單一規則會執行下列其中一項操作：

  • 封鎖網路要求。
  • 將結構定義升級為 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 陣列。系統會使用 Ruleset 字典的 "id" 鍵定義 ID。

如要啟用或停用靜態rulesets，請呼叫 updateEnabledRulesets()。這個方法使用 UpdateRulesetOptions 物件，其中包含要啟用或停用的規則集 ID 陣列。系統會使用 Ruleset 字典的 "id" 鍵定義 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 時會受到一些限制。限制取決於您使用的規則類型。

靜態規則

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

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

工作階段規則

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

在 Chrome 120 之前的版本中，動態規則和工作階段規則的加總上限是 5, 000 個。

動態規則

一項擴充功能可以有至少 5000 項動態規則。這會以 MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES 的形式公開。

從 Chrome 121 版開始，安全動態規則可用的規則上限是 30,000 個，並以 MAX_NUMBER_OF_DYNAMIC_RULES 的形式公開。安全規則定義為動作為 block、allow、allowAllRequests 或 upgradeScheme 的規則。在 5,000 以下的用量上限內新增的任何不安全的規則也都會計入這個上限。

在 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.

與 Service Worker 的互動

宣告式 NetRequest 僅適用於到達網路堆疊的要求。這包括來自 HTTP 快取的回應，但可能不會包含經由 Service Worker 的 onfetch 處理常式所發出的回應。宣告式 NetRequest 不會影響 Service Worker 產生或從 CacheStorage 擷取的回應，但會影響對 Service Worker 中對 fetch() 的呼叫。

可透過網路存取的資源

宣告式 NetRequest 規則無法從公開資源要求重新導向至不開放網路存取的資源。否則會觸發錯誤。即使指定的可存取網路資源是由重新導向的擴充功能所擁有也一樣。如要宣告 larativeNetRequest 的資源，請使用資訊清單的 "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 的規則。系統會套用 ID 1 的規則，因為 "block" 項動作的優先順序高於 "redirect" 項動作。其餘規則不適用，因為這些規則適用於較長網址。
瀏覽至 https://google.com/1234
由於網址較長，因此除了 ID 1 和 4 的規則外，ID 為 2 的規則現在也已更新。系統會套用 ID 2 的規則，因為 "allow" 的優先順序高於 "block" 和 "redirect"。
瀏覽至 https://google.com/12345
這四項規則都與這個網址相符。ID 3 的規則會套用，因為 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 相符的規則。

HeaderOperation

Chrome 86 以上版本

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

列舉

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

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

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

IsRegexSupportedResult

Chrome 87 以上版本

屬性

  • isSupported

    boolean

  • 原因

    UnsupportedRegexReason (選用)

    說明不支援規則運算式的原因。只有在 isSupported 為 false 時才提供。

MatchedRule

屬性

  • ruleId

    號碼

    相符規則的 ID。

  • rulesetId

    字串

    這項規則所屬的 Ruleset ID。如果規則源自動態規則集，則等於 DYNAMIC_RULESET_ID。

MatchedRuleInfo

屬性

  • 規則

    MatchedRule

  • tabId

    號碼

    請求的來源分頁 ID (如果分頁還在使用中)。其他 -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 選用

    要執行的網址轉換。

  • url

    字串 選用

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

RegexOptions

Chrome 87 以上版本

屬性

  • isCaseSensitive

    布林值 (選用)

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

  • 規則運算式

    字串

    要檢查的一般 Expresson。

  • 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

    字串

    要求的 URL。

RequestMethod

Chrome 91 以上版本

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

列舉

"get"

"head"

"options"

"put"

ResourceType

這是指網路要求的資源類型。

列舉

"main_frame"

"sub_frame"

"stylesheet"

"script"

"font"

"csp_report"

"websocket"

"webbundle"

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」以外的所有資源類型。

  • excludedTabIds

    number[] 選填

    Chrome 92 以上版本

    不應比對規則的 tabs.Tab.id 清單。tabs.TAB_ID_NONE 會排除非源自分頁的要求。僅支援以工作階段為範圍的規則。

  • initiatorDomains

    string[] 選填

    Chrome 101 以上版本

    這項規則只會比對來自 initiatorDomains 清單的網路要求。如果省略清單，規則就會套用至所有網域提出的要求。不可使用空白清單。

    注意：

    • 子網域也允許「a.example.com」等子網域。
    • 項目只能包含 ASCII 字元。
    • 針對國際化網域使用 Punycode 編碼。
    • 這個值會與要求發起者進行比對，而不是要求網址。
    • 所列網域的子網域也會相符。
  • isUrlFilterCaseSensitive

    布林值 (選用)

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

  • regexFilter

    字串 選用

    要與網路要求網址比對的規則運算式。此做法符合 RE2 語法。

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

    注意：regexFilter 只能由 ASCII 字元組成。系統會比對主機採用 Punycode 格式 (適用於國際化網域) 的網址，以及其他使用 utf-8 編碼的網址。

  • requestDomains

    string[] 選填

    Chrome 101 以上版本

    網域必須與 requestDomains 清單中的網路要求相符，這項規則才會比對網路要求。如果省略清單，規則就會套用至所有網域提出的要求。不可使用空白清單。

    注意：

    • 子網域也允許「a.example.com」等子網域。
    • 項目只能包含 ASCII 字元。
    • 針對國際化網域使用 Punycode 編碼。
    • 所列網域的子網域也會相符。
  • requestMethods

    RequestMethod[] 選用

    Chrome 91 以上版本

    規則可比對的 HTTP 要求方法清單。不可使用空白清單。

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

  • resourceTypes

    ResourceType[] 選用

    規則可比對的資源類型清單。不可使用空白清單。

    注意：必須為 allowAllRequests 規則指定這個值，且只能包含 sub_frame 和 main_frame 資源類型。

  • tabIds

    number[] 選填

    Chrome 92 以上版本

    應符合規則的 tabs.Tab.id 清單。ID 為 tabs.TAB_ID_NONE 會比對並非源自分頁的要求。不可使用空白清單。僅支援以工作階段為範圍的規則。

  • urlFilter

    字串 選用

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

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

    「|」：左/右錨點：如果在模式任一結尾使用，請分別指定網址的開頭/結尾。

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

    '^'：分隔符字元：比對出字母、數字或下列任一項目除外：_、-、. 或 %。同樣與網址的結尾也是一樣。

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

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

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

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

    注意：urlFilter 只能由 ASCII 字元組成。系統會比對主機採用 Punycode 格式 (適用於國際化網域) 的網址，以及其他使用 utf-8 編碼的網址。舉例來說，如果請求網址是 http://abc.р?q=在」)。urlFilter

Ruleset

屬性

  • 已啟用

    boolean

    預設啟用規則集。

  • id

    字串

    非空白字串，用於識別規則集。開頭為「_」的 ID 已保留供內部使用。

  • path

    字串

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

RulesMatchedDetails

屬性

TabActionCountUpdate

Chrome 89 以上版本

屬性

  • 增加

    號碼

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

  • tabId

    號碼

    用於更新動作計數的分頁。

TestMatchOutcomeResult

Chrome 103 以上版本

屬性

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 以上版本

屬性

  • 發起人

    字串 選用

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

  • method

    RequestMethod 選用

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

  • tabId

    數字 選填

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

  • 類型

    ResourceType

    假設要求的資源類型。

  • url

    字串

    假設要求的網址。

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

    字串 選用

    要求的新片段。須為空白，可以清除現有片段；或者，以「#」開頭。

  • 主辦方

    字串 選用

    要求的新主機。

  • 密碼

    字串 選用

    要求的新密碼。

  • path

    字串 選用

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

  • 通訊埠

    字串 選用

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

  • 項查詢

    字串 選用

    要求的新查詢。輸入內容為空白，在此情況下，系統會清除現有查詢；或者，開頭應為「?」。

  • 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,
)

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

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (count: number)=>void

    • 數量

      號碼

傳回

  • Promise<number>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getDisabledRuleIds()

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

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

參數

  • 指定要查詢的規則集。

  • 回呼

    函式選用

    callback 參數如下所示： 

    (disabledRuleIds: number[])=>void

    • disabledRuleIds

      數字 []

傳回

  • Promise<number[]>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getDynamicRules()

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

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

參數

  • 過濾器

    GetRulesFilter 選用

    Chrome 111 以上版本

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    (rules: Rule[])=>void

傳回

  • Promise<規則[]>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getEnabledRulesets()

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

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

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    (rulesetIds: string[])=>void

    • rulesetIds

      string[]

傳回

  • Promise<string[]>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getMatchedRules()

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

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

參數

傳回

  • Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getSessionRules()

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

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

參數

  • 過濾器

    GetRulesFilter 選用

    Chrome 111 以上版本

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    (rules: Rule[])=>void

傳回

  • Promise<規則[]>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

isRegexSupported()

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

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

參數

傳回

  • Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setExtensionActionOptions()

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

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

參數

  • 回呼

    函式選用

    Chrome 89 以上版本

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

testMatchOutcome()

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

檢查擴充功能的宣告式 NetRequest 規則是否符合假設要求。注意：僅適用於未封裝的擴充功能，因為這項功能僅適用於擴充功能開發期間。

參數

傳回

  • Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

updateDynamicRules()

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

修改擴充功能目前的動態規則組合。系統會先移除 ID 列在 options.removeRuleIds 中的規則，然後再新增 options.addRules 中指定的規則。注意：

  • 更新是在單一作業中發生：一次新增和移除所有指定的規則，或是傳回錯誤。
  • 無論瀏覽器工作階段或擴充功能更新，這些規則都會保留。
  • 您無法使用這個函式移除擴充功能套件中指定的靜態規則。
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES 是擴充功能可新增的合併動態規則和工作階段規則數量上限。

參數

  • Chrome 87 以上版本
  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

updateEnabledRulesets()

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

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

參數

  • Chrome 87 以上版本
  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

updateSessionRules()

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

修改這項擴充功能目前以工作階段為範圍的規則。系統會先移除 ID 列在 options.removeRuleIds 中的規則，然後再新增 options.addRules 中指定的規則。注意：

  • 更新是在單一作業中發生：一次新增和移除所有指定的規則，或是傳回錯誤。
  • 這些規則不會跨工作階段保存，並且會備份在記憶體中。
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES 是擴充功能可新增的合併動態規則和工作階段規則數量上限。

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

updateStaticRules()

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

停用及啟用 Ruleset 中的個別靜態規則。對屬於已停用 Ruleset 的規則所做的變更將在下次啟用時生效。

參數

傳回

  • Promise<void>

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onRuleMatchedDebug

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

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

參數