chrome.declarativeNetRequest

說明

chrome.declarativeNetRequest API 可讓您指定宣告規則，藉此封鎖或修改網路要求。這可讓擴充功能在不攔截及查看網路要求的情況下，修改網路要求，進而加強隱私保護。

權限

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

可用性

Chrome 84 以上版本

資訊清單

除了上述權限以外，特定類型的規則集 (具體來說是靜態規則集) 需要宣告 "declarative_net_request" 資訊清單鍵，該鍵應使用名為 "rule_resources" 的單一索引鍵的字典。這個鍵是包含 Ruleset 類型的字典陣列，如下所示。(請注意，「Ruleset」這個名稱只是一個陣列，因此不會出現在資訊清單的 JSON 中。)本文件稍後會說明靜態規則集。

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

概念和用法

如要使用這個 API，請指定一或多個規則集。規則集包含一組規則陣列。單一規則會執行下列其中一項操作：

  • 封鎖網路要求。
  • 升級結構定義 (從 http 升級至 https)。
  • 拒絕任何相符的封鎖規則，即可避免要求遭到封鎖。
  • 重新導向網路要求。
  • 修改要求或回應標頭。

規則集分為三種，管理方式略有不同。

動態
可在瀏覽器工作階段和擴充功能升級期間保留資料，並在使用擴充功能時透過 JavaScript 管理。
工作階段
在瀏覽器關閉及安裝新版擴充功能時清除。在使用擴充功能時，工作階段規則是透過 JavaScript 管理。
靜態
安裝或升級擴充功能時，封裝、安裝及更新。靜態規則會以 JSON 格式的規則檔案儲存在資訊清單檔案中，

以下幾節將詳細說明規則集類型。

動態和以工作階段為範圍的規則集

您可以在使用擴充功能時，透過 JavaScript 管理動態和工作階段規則集。

  • 動態規則會套用至瀏覽器工作階段和擴充功能升級作業。
  • 瀏覽器關閉及安裝新版擴充功能時，系統就會清除工作階段規則。

這些規則集類型只有一個。如果擴充功能未超過規則限制，可以呼叫 updateDynamicRules() 和 updateSessionRules()，動態新增或移除規則。如要進一步瞭解規則限制，請參閱規則限制。您可以在程式碼範例下方查看範例。

靜態規則集

靜態規則與動態規則和工作階段規則不同，會在安裝或升級擴充功能時，封裝、安裝及更新。這類 ID 會以 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。

如要啟用或停用靜態規則集，請呼叫 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" 資訊清單鍵中指定最多 50 個靜態規則集，但一次最多只能啟用 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 complext regex than allowed
as part of the "regexFilter" key.

與服務工作處理程序的互動

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 如何決定擴充功能中的規則優先順序。查看優先順序時，建議您在其他視窗中開啟「優先順序」規則。

「優先順序」鍵

這些範例需要 *://*.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": 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

    布林值

  • 原因

    UnsupportedRegexReason 選用

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

MatchedRule

屬性

  • ruleId

    數字

    相符規則的 ID。

  • rulesetId

    字串

    此規則所屬的 Ruleset ID。如果規則的來源是動態規則，這會等於 DYNAMIC_RULESET_ID。

MatchedRuleInfo

屬性

  • 規則

    MatchedRule

  • tabId

    數字

    如果分頁仍為有效狀態，產生請求的分頁編號。其他 -1.

  • timeStamp

    數字

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

MatchedRuleInfoDebug

屬性

MatchedRulesFilter

屬性

  • minTimeStamp

    編號 選填

    如有指定，系統只會比對特定時間戳記之後的規則。

  • tabId

    編號 選填

    如有指定，系統只會比對特定分頁的規則。如果設為 -1，規則會比對未與任何使用中分頁建立關聯的規則。

ModifyHeaderInfo

Chrome 86 以上版本

屬性

  • 標頭

    字串

    要修改的標頭名稱。

  • 要對標頭執行的作業。

  • 值

    string optional

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

QueryKeyValue

屬性

  • 金鑰

    字串

  • replaceOnly

    布林值 選填

    Chrome 94 以上版本

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

  • 值

    字串

QueryTransform

屬性

  • addOrReplaceParams

    QueryKeyValue[] 選用

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

  • removeParams

    string[] 選填

    要移除的查詢鍵清單。

Redirect

屬性

  • extensionPath

    string optional

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

  • regexSubstitution

    string optional

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

  • transform

    URLTransform 選用

    要執行的網址轉換。

  • 網址

    string optional

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

RegexOptions

Chrome 87 以上版本

屬性

  • isCaseSensitive

    布林值 選填

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

  • 規則運算式

    字串

    要查看的一般表達式。

  • requireCapturing

    布林值 選填

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

RequestDetails

屬性

  • documentId

    string optional

    Chrome 106 以上版本

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

  • documentLifecycle

    DocumentLifecycle 選用

    Chrome 106 以上版本

    頁框文件的生命週期 (如果是針對頁框要求)。

  • frameId

    數字

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

  • frameType

    FrameType 選用

    Chrome 106 以上版本

    影格類型 (如果是影格要求的話)

  • 發起者

    string optional

    發出要求的來源。這不會因為重新導向而改變。如果來源不透明，字串「null」

  • method

    字串

    標準 HTTP 方法。

  • parentDocumentId

    string optional

    Chrome 106 以上版本

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

  • parentFrameId

    數字

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

  • requestId

    字串

    要求的 ID。請求 ID 在單一瀏覽器工作階段中是獨一無二的。

  • tabId

    數字

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

  • 類型

    ResourceType

    要求的資源類型。

  • 網址

    字串

    要求的 URL。

RequestMethod

Chrome 91 以上版本

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

列舉

"連線"

「刪除」

"get"

"head"

"選項"

"patch"

"post"

"put"

「其他」

ResourceType

這會說明網路要求的資源類型。

列舉

"main_frame"

"sub_frame"

"stylesheet"

"script"

"圖片"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"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」以外的所有資源類型已遭封鎖。

  • excludedResponseHeaders

    HeaderInfo[] 選填

    Chrome 128 以上版本

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

  • excludedTabIds

    number[] 選填

    Chrome 92 以上版本

    規則不符的 tabs.Tab.id 清單。tabs.TAB_ID_NONE ID 會排除並非源自分頁的要求。只有以工作階段為範圍的規則支援此屬性。

  • initiatorDomains

    string[] 選填

    Chrome 101 以上版本

    這項規則只會比對源自「initiatorDomains」清單中的網路要求。如果忽略這份清單，系統將對所有網域的要求套用規則。不得留空。

    注意：

    • 子網域，例如「a.example.com」也可使用
    • 項目只能包含 ASCII 字元。
    • 針對國際化網域使用 Punycode 編碼。
    • 這會比對要求發起者，而非要求網址。
    • 清單中所列網域的子網域也會相符。
  • isUrlFilterCaseSensitive

    布林值 選填

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

  • regexFilter

    string optional

    用於比對網路要求網址的規則運算式。這符合 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 與非來自分頁的要求相符。不得留空。只有以工作階段為範圍的規則支援此屬性。

  • urlFilter

    string optional

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

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

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

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

    '^'：分隔字元字元：比對字母、數字或下列任一字元，但比對字元除外：_、-、. 或 %。這也會與網址結尾相符。

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

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

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

    注意：您只能指定 urlFilter 或 regexFilter 的其中一個。

    注意：urlFilter 只能由 ASCII 字元組成。系統會比對網址。網址中的主機是採用 Punycode 格式 (如果是國際化網域) 編碼，所有其他非 ASCII 字元則會以 utf-8 編碼。舉例來說，如果要求網址是 http://abc.рPay?q=地理編碼，系統會將 urlFilter 與這個網址 (http://abc.xn--p1ai/?q=%D1%84) 進行比對。

Ruleset

屬性

  • 已啟用

    布林值

    是否預設為啟用規則集。

  • id

    字串

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

  • 路徑

    字串

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

RulesMatchedDetails

屬性

TabActionCountUpdate

Chrome 89 以上版本

屬性

  • 增加

    數字

    要增加分頁操作次數的量。如果設為負值，數量就會減少。

  • tabId

    數字

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

TestMatchOutcomeResult

Chrome 103 以上版本

屬性

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 以上版本

屬性

  • 發起者

    string optional

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

  • method

    RequestMethod 選用

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

  • responseHeaders

    物件 optional

    待處理

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

  • tabId

    編號 選填

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

  • 類型

    ResourceType

    假想要求的資源類型。

  • 網址

    字串

    假想要求的網址。

UnsupportedRegexReason

Chrome 87 以上版本

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

列舉

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

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

UpdateRuleOptions

Chrome 87 以上版本

屬性

  • addRules

    規則[] 選用

    要新增的規則。

  • removeRuleIds

    number[] 選填

    待移除規則的 ID。系統會忽略任何無效 ID。

UpdateRulesetOptions

Chrome 87 以上版本

屬性

  • disableRulesetIds

    string[] 選填

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

  • enableRulesetIds

    string[] 選填

    與應啟用的靜態 Ruleset 相對應的 ID 組合。

UpdateStaticRulesOptions

Chrome 111 以上版本

屬性

  • disableRuleIds

    number[] 選填

    與 Ruleset 中要停用的規則相對應的 ID 組合。

  • enableRuleIds

    number[] 選填

    與 Ruleset 中的規則相對應的 ID 組合，即可啟用。

  • rulesetId

    字串

    與靜態 Ruleset 相對應的 ID。

URLTransform

屬性

  • fragment

    string optional

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

  • 主機

    string optional

    要求的新主機。

  • 密碼

    string optional

    要求的新密碼。

  • 路徑

    string optional

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

  • 通訊埠

    string optional

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

  • 查詢

    string optional

    要求的新查詢。當此條件留空時，系統會清除現有的查詢；或開頭為「?」。

  • queryTransform

    QueryTransform 選用

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

  • 架構

    string optional

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

  • 使用者名稱

    string optional

    要求的新使用者名稱。

屬性

DYNAMIC_RULESET_ID

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

值

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

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

值

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 以上版本

在已啟用的靜態規則集中，保證擴充功能擁有的靜態規則數量下限。超出這項限制的所有規則都會計入全域靜態規則上限。

值

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

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

值

20

MAX_NUMBER_OF_DYNAMIC_RULES

額外資訊可新增的動態規則數量上限。

值

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 以上版本

每項擴充功能一次可啟用的靜態 Rulesets 數量上限。

值

50

MAX_NUMBER_OF_REGEX_RULES

擴充功能可新增的規則運算式規則數量上限。系統會針對一組在規則資源檔案中指定的動態規則和規則，分別評估此上限。

值

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 以上版本

擴充功能可新增的工作階段範圍規則數量上限。

值

5000

MAX_NUMBER_OF_STATIC_RULESETS

擴充功能可在 "rule_resources" 資訊清單鍵中指定的靜態 Rulesets 數量上限。

值

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 以上版本

「不安全」數量的上限擴充功能可新增的動態規則。

值

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 以上版本

「不安全」數量的上限擴充功能可新增的工作階段範圍規則

值

5000

SESSION_RULESET_ID

Chrome 90 以上版本

針對擴充功能新增的以工作階段為範圍規則的規則集 ID。

值

"_session"

方法

getAvailableStaticRuleCount()

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

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (count: number) => void

    • 數量

      數字

傳回

  • Promise<number>

    Chrome 91 以上版本

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

getDisabledRuleIds()

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

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

參數

  • 指定要查詢的規則集。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      數字 []

傳回

  • 承諾<數字 []>

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

getDynamicRules()

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

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

參數

  • 篩選器

    GetRulesFilter 選用

    Chrome 111 以上版本

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (rules: Rule[]) => void

傳回

  • Promise<規則[]>

    Chrome 91 以上版本

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

getEnabledRulesets()

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

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

傳回

  • Promise&lt;string[]&gt;

    Chrome 91 以上版本

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

getMatchedRules()

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

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

參數

傳回

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome 91 以上版本

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

getSessionRules()

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

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

參數

  • 篩選器

    GetRulesFilter 選用

    Chrome 111 以上版本

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

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (rules: Rule[]) => void

傳回

  • Promise<規則[]>

    Chrome 91 以上版本

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

isRegexSupported()

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

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

參數

傳回

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome 91 以上版本

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

setExtensionActionOptions()

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

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

參數

  • 回呼

    函式 選用

    Chrome 89 以上版本

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

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

testMatchOutcome()

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

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

參數

傳回

  • Promise&lt;TestMatchOutcomeResult&gt;

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

updateDynamicRules()

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

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

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

參數

  • Chrome 87 以上版本
  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

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

updateEnabledRulesets()

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

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

參數

  • Chrome 87 以上版本
  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

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

updateSessionRules()

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

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

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 91 以上版本

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

updateStaticRules()

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

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

參數

傳回

  • 承諾<void>

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

活動

onRuleMatchedDebug

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

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

參數