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

  • 封鎖網路要求。
  • 升級結構定義 (從 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。

如要啟用或停用靜態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. 如有多項規則相符，系統會優先安裝最新安裝的擴充功能。

安全規則

安全規則可定義為具有 block、allow、allowAllRequests 或 upgradeScheme 動作的規則。這些規則必須增加動態規則配額。

規則限制

在瀏覽器中載入及評估規則會產生效能負擔，因此使用 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。凡是在 5,000 個限制內加入的不安全規則，也都會計入這個限制中。

在 Chrome 120 之前的版本中，動態與工作階段規則的合計有 5, 000 個上限。

使用規則運算式的規則

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

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

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 相符的規則。

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

    號碼

    如果分頁仍為有效狀態，產生請求的分頁編號。其他 -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"

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 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 資源類型。

  • 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

屬性

  • 已啟用

    boolean

    是否預設為啟用規則集。

  • ID

    字串

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

  • path

    字串

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

RulesMatchedDetails

屬性

TabActionCountUpdate

Chrome 89 以上版本

屬性

  • 增加

    號碼

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

  • tabId

    號碼

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

TestMatchOutcomeResult

Chrome 103 以上版本

屬性

  • matchedRules

    MatchedRule[] (比對規則)，

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

TestMatchRequestDetails

Chrome 103 以上版本

屬性

  • 發起者

    string optional

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

  • method

    RequestMethod 選用

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

  • 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

    要求的新密碼。

  • path

    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

    • 數量

      號碼

傳回

  • 承諾<數字>

    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[]

傳回

  • 承諾<string[]>

    Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

getMatchedRules()

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

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

參數

傳回

  • 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 規則條件。

參數

傳回

  • Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

setExtensionActionOptions()

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

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

參數

  • 回呼

    函式 選用

    Chrome 89 以上版本

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

testMatchOutcome()

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

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

參數

傳回

  • 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

傳回

  • Promise<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

傳回

  • Promise<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

傳回

  • Promise<void>

    Chrome 91 以上版本

    Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

updateStaticRules()

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

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

參數

傳回

  • Promise<void>

    Promise 適用於 Manifest V3 及以上版本，但為了回溯相容性，提供回呼。您無法在同一函式呼叫中同時使用兩者。保證會以傳遞至回呼的類型來解析。

活動

onRuleMatchedDebug

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

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

參數