說明
chrome.declarativeNetRequest
API 可讓您透過指定宣告式規則來封鎖或修改網路要求。這項功能可讓擴充功能修改網路要求,而不會攔截及查看內容,進一步保障隱私權。
權限
declarativeNetRequest
declarativeNetRequestWithHostAccess
「declarativeNetRequest
」和「declarativeNetRequestWithHostAccess
」權限提供相同功能。這兩者的差異在於要求或授予權限時。
"declarativeNetRequest"
- 在安裝時觸發權限警告,但提供
allow
、allowAllRequests
和block
規則的隱含存取權。請盡可能使用此方法,避免需要要求主機的完整存取權。 "declarativeNetRequestFeedback"
- 啟用未封裝擴充功能的偵錯功能,特別是
getMatchedRules()
和onRuleMatchedDebug
。 "declarativeNetRequestWithHostAccess"
- 安裝時不會顯示權限警告,但您必須先要求主機權限,才能在主機上執行任何動作。當您想在已有主機權限的擴充功能中使用宣告式網路要求規則時,且不產生額外警示時,這就非常實用。
適用國家/地區
資訊清單
除了上述權限以外,特定類型的規則集 (具體來說是靜態規則集) 還需宣告 "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 |
排定規則優先順序
規則是由網頁傳送的要求所觸發。如有多項規則符合特定要求,您必須優先執行規則。本節將說明優先順序如何。優先順序分為兩個階段。
- 系統會依據擴充功能中的規則決定優先順序。
- 如有多項擴充功能可對某項要求套用規則,系統會依符合特定要求的所有擴充功能決定優先順序。
比對方式就是這樣:系統會優先採用特定額外資訊所優先套用的規則,再與其他額外資訊中的規則進行比較。
擴充功能中的規則優先順序
在單一擴充功能中,系統會以下列程序決定優先順序:
- 系統會傳回開發人員定義優先順序最高的規則 (也就是
"priority"
欄位)。 如果超過一項規則的優先順序最高,系統會使用
"action"
欄位排定規則的優先順序,並按照下列順序排列:allow
allowAllRequests
block
upgradeScheme
redirect
如果動作類型不是
block
或redirect
,系統會評估任何相符的modifyHeaders
規則。請注意,如有任何規則設定的優先順序低於allow
和allowAllRequests
的指定優先順序,系統就會忽略這類規則。如有多項規則修改同一個標頭,修改內容將取決於開發人員定義的
"priority"
欄位和指定的作業。- 如果規則附加至標頭,則優先順序較低的規則只能附加至該標頭。不允許設定和移除作業。
- 如果規則設定了標頭,優先順序較低的規則就只能附加至該標頭。我們不允許其他修改。
- 如果規則移除標頭,優先順序較低的規則將無法進一步修改標頭。
擴充功能之間的規則優先順序
如果只有一個擴充功能設有與要求相符的規則,系統就會套用該規則。但如果有多個擴充功能與要求相符,便會使用以下程序:
系統會使用
"action"
欄位排定規則的優先順序,依序如下:block
redirect
或upgradeScheme
allow
或allowAllRequests
如果符合多項規則,系統會優先採用最新安裝的擴充功能。
規則限制
在瀏覽器中載入和評估規則會產生效能負擔,因此使用 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
屬性
-
displayActionCountAsBadgeText
布林值 (選用)
是否自動在擴充功能的徽章文字中顯示網頁動作計數。這項偏好設定會在所有工作階段保留。
-
tabUpdateChrome 89 以上版本
分頁動作計數應如何調整的詳細資料。
GetDisabledRuleIdsOptions
屬性
-
rulesetId
字串
與靜態
Ruleset
對應的 ID。
GetRulesFilter
屬性
-
ruleIds
number[] 選填
如有指定,則只會納入 ID 相符的規則。
HeaderOperation
說明「modifyHeaders」規則的可能作業。
列舉
"append"
新增指定標頭的項目。要求標頭不支援這項作業。
"set"
為指定標頭設定新值,並移除任何名稱相同的現有標頭。
"remove"
移除指定標頭的所有項目。
IsRegexSupportedResult
屬性
-
isSupported
boolean
-
原因
說明不支援規則運算式的原因。只有在
isSupported
為 false 時才提供。
MatchedRule
屬性
-
ruleId
號碼
相符規則的 ID。
-
rulesetId
字串
這項規則所屬的
Ruleset
ID。如果規則源自動態規則集,則等於DYNAMIC_RULESET_ID
。
MatchedRuleInfo
屬性
-
規則
-
tabId
號碼
請求的來源分頁 ID (如果分頁還在使用中)。其他 -1.
-
timeStamp
號碼
符合規則的時間。時間戳記會與 JavaScript 的時間慣例相符,例如自 Epoch 紀元時間起算的毫秒數。
MatchedRuleInfoDebug
屬性
-
申請。
與規則比對相符的要求詳細資料。
-
規則
MatchedRulesFilter
屬性
-
minTimeStamp
數字 選填
如果有指定,系統只會比對指定時間戳記之後的規則。
-
tabId
數字 選填
如果有指定,系統只會比對指定分頁的規則。設為 -1 時,符合未與任何使用中分頁相關聯的規則。
ModifyHeaderInfo
屬性
-
標頭
字串
要修改的標頭名稱。
-
要對標頭執行的作業。
-
值
字串 選用
標頭的新值。必須為
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
屬性
-
isCaseSensitive
布林值 (選用)
指定的
regex
是否區分大小寫。預設值為 true。 -
規則運算式
字串
要檢查的一般 Expresson。
-
requireCapturing
布林值 (選用)
指定的
regex
是否需要擷取。只有指定regexSubstition
動作的重新導向規則才需要擷取。預設值為 false。
RequestDetails
屬性
-
documentId
字串 選用
Chrome 106 以上版本影格文件的專屬 ID (如果這個要求適用於影格)。
-
documentLifecycleChrome 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。
-
類型
要求的資源類型。
-
url
字串
要求的 URL。
RequestMethod
這會說明網路要求的 HTTP 要求方法。
列舉
"get"
"head"
"options"
"put"
ResourceType
這是指網路要求的資源類型。
列舉
"main_frame"
"sub_frame"
"stylesheet"
"script"
"font"
"csp_report"
"websocket"
"webbundle"
Rule
屬性
-
動作
比對相符時要採取的動作。
-
觸發這項規則的條件。
-
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 版起已淘汰的項目這項規則只會比對來自
domains
清單的網路要求。 -
excludedDomains
string[] 選填
自 Chrome 101 版起已淘汰的項目這項規則不會比對來自
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
屬性
-
rulesMatchedInfo
符合指定篩選器的規則。
TabActionCountUpdate
屬性
-
增加
號碼
該分頁動作計數的遞增量。負值會減少計數。
-
tabId
號碼
用於更新動作計數的分頁。
TestMatchOutcomeResult
屬性
-
matchedRules
符合假設要求的規則 (如有)。
TestMatchRequestDetails
屬性
-
發起人
字串 選用
假設要求的發起人網址 (如有)。
-
method
假設要求的標準 HTTP 方法。HTTP 要求的預設值是「get」,非 HTTP 要求則會被忽略。
-
tabId
數字 選填
發生假設要求的分頁 ID。不需要對應至實際分頁 ID。預設值為 -1,表示要求與分頁無關。
-
類型
假設要求的資源類型。
-
url
字串
假設要求的網址。
UnsupportedRegexReason
說明不支援指定規則運算式的原因。
列舉
UpdateRuleOptions
屬性
-
addRules
規則[] 選用
要新增的規則。
-
removeRuleIds
number[] 選填
要移除的規則 ID。系統會忽略任何無效 ID。
UpdateRulesetOptions
屬性
UpdateStaticRulesOptions
屬性
URLTransform
屬性
-
fragment
字串 選用
要求的新片段。須為空白,可以清除現有片段;或者,以「#」開頭。
-
主辦方
字串 選用
要求的新主機。
-
密碼
字串 選用
要求的新密碼。
-
path
字串 選用
要求的新路徑。如果留空,系統會清除現有路徑。
-
通訊埠
字串 選用
要求的新通訊埠。如果留空,系統會清除現有的通訊埠。
-
項查詢
字串 選用
要求的新查詢。輸入內容為空白,在此情況下,系統會清除現有查詢;或者,開頭應為「?」。
-
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
在擴充功能已啟用的靜態規則集中,保證享有擴充功能的靜態規則數量下限。超過這項限制的所有規則都將計入全域靜態規則限制。
值
30000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
getMatchedRules
在 GETMATCHEDRULES_QUOTA_INTERVAL
期間內可呼叫的次數。
值
20
MAX_NUMBER_OF_DYNAMIC_RULES
擴充功能可新增的動態規則數量上限。
值
30000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
擴充功能一次可啟用的靜態Rulesets
數量上限。
值
50
MAX_NUMBER_OF_REGEX_RULES
擴充功能可新增的規則運算式規則數量上限。系統會根據一組動態規則和規則資源檔案中指定的規則,分別評估這項限制。
值
1000
MAX_NUMBER_OF_SESSION_RULES
擴充功能可新增的工作階段範圍規則數量上限。
值
5000
MAX_NUMBER_OF_STATIC_RULESETS
擴充功能可在 "rule_resources"
資訊清單鍵中指定的靜態 Rulesets
數量上限。
值
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
擴充功能可新增的「不安全」動態規則數量上限。
值
5000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
擴充功能可新增的「不安全」工作階段範圍規則數量上限。
值
5000
SESSION_RULESET_ID
擴充功能新增的以工作階段為範圍規則的規則集 ID。
值
"_session"
方法
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
傳回在達到全域靜態規則限制前,擴充功能可啟用的靜態規則數量。
參數
-
回呼
函式選用
callback
參數如下所示:(count: number)=>void
-
數量
號碼
-
傳回
-
Promise<number>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
傳回指定 Ruleset
中目前已停用的靜態規則清單。
參數
-
指定要查詢的規則集。
-
回呼
函式選用
callback
參數如下所示:(disabledRuleIds: number[])=>void
-
disabledRuleIds
數字 []
-
傳回
-
Promise<number[]>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
傳回擴充功能目前的動態規則組合。呼叫端可選擇指定 filter
,篩選已擷取的規則清單。
參數
傳回
-
Promise<規則[]>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
傳回目前啟用的靜態規則集的 ID。
參數
-
回呼
函式選用
callback
參數如下所示:(rulesetIds: string[])=>void
-
rulesetIds
string[]
-
傳回
-
Promise<string[]>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
傳回與擴充功能相符的所有規則。呼叫端可選擇指定 filter
,篩選相符規則清單。這個方法僅適用於具備 "declarativeNetRequestFeedback"
權限的擴充功能,或是針對 filter
中指定的 tabId
授予 "activeTab"
權限的擴充功能。注意:系統不會傳回未與有效文件比對相符超過五分鐘的規則。
參數
-
過濾器
MatchedRulesFilter (選用)
用於篩選相符規則清單的物件。
-
回呼
函式選用
callback
參數如下所示:(details: RulesMatchedDetails)=>void
-
詳細資料
-
傳回
-
Promise<RulesMatchedDetails>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
傳回這項擴充功能目前的工作階段範圍規則。呼叫端可選擇指定 filter
,篩選已擷取的規則清單。
參數
傳回
-
Promise<規則[]>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
檢查是否能將指定的規則運算式做為 regexFilter
規則條件。
參數
-
regexOptions
要檢查的規則運算式。
-
回呼
函式選用
callback
參數如下所示:(result: IsRegexSupportedResult)=>void
傳回
-
Promise<IsRegexSupportedResult>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
設定是否應將分頁的動作計數顯示為擴充功能動作的徽章文字,並提供遞增該動作計數的方法。
參數
-
回呼
函式選用
Chrome 89 以上版本callback
參數如下所示:()=>void
傳回
-
Promise<void>
Chrome 91 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
檢查擴充功能的宣告式 NetRequest 規則是否符合假設要求。注意:僅適用於未封裝的擴充功能,因為這項功能僅適用於擴充功能開發期間。
參數
-
回呼
函式選用
callback
參數如下所示:(result: TestMatchOutcomeResult)=>void
傳回
-
Promise<TestMatchOutcomeResult>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
updateDynamicRules()
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()
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()
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()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
參數
-
回呼
函式選用
callback
參數如下所示:()=>void
傳回
-
Promise<void>
Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
與要求比對相符的規則時觸發。僅適用於具有 "declarativeNetRequestFeedback"
權限的未封裝擴充功能,因此僅供偵錯使用。
參數
-
回呼
功能
callback
參數如下所示:(info: MatchedRuleInfoDebug)=>void