chrome.declarativeNetRequest

列舉

屬性

• displayActionCountAsBadgeText

  布林值 選填

  是否要自動顯示網頁的動作次數，做為擴充功能的徽章文字。這項偏好設定會在不同工作階段之間保留。

• tabUpdate

  TabActionCountUpdate 選用

  Chrome 89 以上版本

  說明如何調整分頁動作計數的詳細資料。

屬性

• rulesetId

  字串

  與靜態 Ruleset 對應的 ID。

屬性

• ruleIds

  number[] 選填

  如果指定，系統只會納入 ID 相符的規則。

屬性

• excludedValues

  字串陣列 選用

  如果指定了這個條件，但標頭存在，且標頭值包含這個清單中的至少一個元素，則不符合條件。這項功能使用的比對模式語法與 values 相同。

• 標頭

  字串

  標題名稱。只有在未指定 values 和 excludedValues 時，這個條件才會比對名稱。

• 值

  字串陣列 選用

  如果指定了這項條件，只要標頭值符合這份清單中的至少一個模式，就會視為相符。這支援不區分大小寫的標頭值比對，以及下列建構項目：

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

  「?」：比對零或一個字元。

  「*」和「?」可使用反斜線逸出，例如「\*」和「\?」

列舉

屬性

• isSupported

  布林值

• 原因

  UnsupportedRegexReason 選用

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

屬性

• ruleId

  數字

  相符規則的 ID。

• rulesetId

  字串

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

屬性

• 規則

  MatchedRule

• tabId

  數字

  如果分頁仍處於啟用狀態，則為提出要求的來源分頁 tabId。Else -1。

• timeStamp

  數字

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

屬性

• 申請。

  RequestDetails

  與規則相符的要求詳細資料。

• 規則

  MatchedRule

屬性

• minTimeStamp

  數字 選填

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

• tabId

  數字 選填

  如有指定，系統只會比對指定分頁的規則。如果設為 -1，則會比對未與任何有效索引標籤建立關聯的規則。

屬性

• 標頭

  字串

  要修改的標頭名稱。

• 作業

  HeaderOperation

  要對標頭執行的作業。

• 值

  字串 選填

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

屬性

• 金鑰

  字串

• replaceOnly

  布林值 選填

  Chrome 94 以上版本

  如為 true，只有在查詢鍵已存在時才會替換。否則，如果缺少金鑰，系統也會新增。預設值為 false。

• 值

  字串

屬性

• addOrReplaceParams

  QueryKeyValue[] optional

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

• removeParams

  字串陣列 選用

  要移除的查詢鍵清單。

屬性

• extensionPath

  字串 選填

  相對於擴充功能目錄的路徑。開頭應為「/」。

• regexSubstitution

  字串 選填

  指定 regexFilter 的規則替代模式。網址中第一個相符的 regexFilter 會被這個模式取代。在 regexSubstitution 中，反斜線逸出數字 (\1 到 \9) 可用於插入對應的擷取群組。\0 是指完整的相符文字。

• transform

  URLTransform 選用

  要執行的網址轉換。

• 網址

  字串 選填

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

屬性

• isCaseSensitive

  布林值 選填

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

• regex

  字串

  要檢查的規則運算式。

• requireCapturing

  布林值 選填

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

屬性

• 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」。

• 方法

  字串

  標準 HTTP 方法。

• parentDocumentId

  字串 選填

  Chrome 106 以上版本

  如果這項要求適用於框架且有父項，則為框架父項文件的專屬 ID。

• parentFrameId

  數字

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

• requestId

  字串

  要求的 ID。要求 ID 在瀏覽器工作階段中不得重複。

• tabId

  數字

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

• 類型

  ResourceType

  要求的資源類型。

• 網址

  字串

  要求的 URL。

列舉

列舉

屬性

• 動作

  RuleAction

  符合這項規則時要採取的動作。

• 條件

  RuleCondition

  觸發這項規則的條件。

• id

  數字

  可明確識別規則的 ID。這是必要屬性，且值應大於或等於 1。

• 優先順序

  數字 選填

  規則優先順序。默認為1。指定時，應 >= 1。

屬性

• 重新導向

  重新導向 選用

  說明應如何執行重新導向。僅適用於重新導向規則。

• requestHeaders

  ModifyHeaderInfo[] 選用

  Chrome 86 以上版本

  要為要求修改的要求標頭。只有在 RuleActionType 為「modifyHeaders」時才有效。

• responseHeaders

  ModifyHeaderInfo[] 選用

  Chrome 86 以上版本

  要為要求修改的回應標頭。只有在 RuleActionType 為「modifyHeaders」時才有效。

• 類型

  RuleActionType

  要執行的動作類型。

列舉

屬性

• domainType

  DomainType 選用

  指定網路要求是來自原始網域的第一方或第三方。如果省略，系統會接受所有要求。

• 網域

  字串陣列 選用

  Chrome 101 版起已淘汰

  請改用 initiatorDomains

  這項規則只會比對來自 domains 清單的網路要求。

• excludedDomains

  字串陣列 選用

  Chrome 101 版起已淘汰

  請改用 excludedInitiatorDomains

  這項規則不會比對來自 excludedDomains 清單的網路要求。

• excludedInitiatorDomains

  字串陣列 選用

  Chrome 101 以上版本

  這項規則不會比對來自 excludedInitiatorDomains 清單的網路要求。如果清單為空白或省略，則不會排除任何網域。優先順序高於 initiatorDomains。

  注意：

  • 也允許使用子網域，例如「a.example.com」。
  • 輸入內容只能包含 ASCII 字元。
  • 如果是國際化網域，請使用域名代碼編碼。
  • 這項比對是針對要求發起人，而非要求網址。
  • 列出網域的子網域也會排除。
• excludedRequestDomains

  字串陣列 選用

  Chrome 101 以上版本

  如果網域與 excludedRequestDomains 清單中的網域相符，規則就不會比對網路要求。如果清單為空白或省略，則不會排除任何網域。優先順序高於 requestDomains。

  注意：

  • 也允許使用子網域，例如「a.example.com」。
  • 輸入內容只能包含 ASCII 字元。
  • 如果是國際化網域，請使用域名代碼編碼。
  • 列出網域的子網域也會排除。
• excludedRequestMethods

  RequestMethod[] 選填

  Chrome 91 以上版本

  規則不會比對的要求方法清單。請只指定 requestMethods 或 excludedRequestMethods 其中之一。如果兩者皆未指定，系統會比對所有要求方法。

• excludedResourceTypes

  ResourceType[] optional

  規則不會比對的資源類型清單。請只指定 resourceTypes 或 excludedResourceTypes 其中之一。如果兩者皆未指定，系統會封鎖「main_frame」以外的所有資源類型。

• excludedResponseHeaders

  HeaderInfo[] 選用

  Chrome 128 以上版本

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

• excludedTabIds

  number[] 選填

  Chrome 92 以上版本

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

• excludedTopDomains

  字串陣列 選用

  Chrome 145 以上版本

  如果相關聯頂層影格的網域與 excludedTopDomains 清單中的網域相符，規則就不會比對網路要求。如果清單為空白或省略，則不會排除任何網域。優先順序高於 topDomains。

  注意：

  • 也允許使用子網域，例如「a.example.com」。
  • 輸入內容只能包含 ASCII 字元。
  • 如果是國際化網域，請使用域名代碼編碼。
  • 列出網域的子網域也會排除。
  • 如果要求沒有相關聯的頂層框架 (例如 ServiceWorker 啟動的要求)，系統會改為考量要求發起者的網域。
• initiatorDomains

  字串陣列 選用

  Chrome 101 以上版本

  這項規則只會比對來自 initiatorDomains 清單的網路要求。如果省略這份清單，規則會套用至來自所有網域的請求。清單不得留空。

  注意：

  • 也允許使用子網域，例如「a.example.com」。
  • 輸入內容只能包含 ASCII 字元。
  • 如果是國際化網域，請使用域名代碼編碼。
  • 這項比對是針對要求發起人，而非要求網址。
  • 系統也會比對所列網域的子網域。
• isUrlFilterCaseSensitive

  布林值 選填

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

• regexFilter

  字串 選填

  用於比對網路要求網址的規則運算式。這符合 RE2 語法。

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

  注意：regexFilter只能由 ASCII 字元組成。這會與網址進行比對，其中主機是以 Punycode 格式編碼 (適用於國際化網域)，任何其他非 ASCII 字元則是以 UTF-8 格式進行網址編碼。

• requestDomains

  字串陣列 選用

  Chrome 101 以上版本

  只有在網域與 requestDomains 清單中的網域相符時，這項規則才會比對網路要求。如果省略這份清單，規則會套用至來自所有網域的請求。清單不得留空。

  注意：

  • 也允許使用子網域，例如「a.example.com」。
  • 輸入內容只能包含 ASCII 字元。
  • 如果是國際化網域，請使用域名代碼編碼。
  • 系統也會比對所列網域的子網域。
• requestMethods

  RequestMethod[] 選填

  Chrome 91 以上版本

  規則可比對的 HTTP 要求方法清單。清單不得留空。

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

• resourceTypes

  ResourceType[] optional

  規則可比對的資源類型清單。清單不得留空。

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

• responseHeaders

  HeaderInfo[] 選用

  Chrome 128 以上版本

  如果要求符合這個清單中的任何回應標頭條件 (如有指定)，規則就會相符。

• tabIds

  number[] 選填

  Chrome 92 以上版本

  規則應比對的 tabs.Tab.id 清單。ID 為 tabs.TAB_ID_NONE 的要求，表示要求並非來自分頁。清單不得留空。僅支援以工作階段為範圍的規則。

• topDomains

  字串陣列 選用

  Chrome 145 以上版本

  只有當相關聯頂層框架的網域與 topDomains 清單中的網域相符時，規則才會比對網路要求。如果省略清單，規則會套用至與所有頂層框架網域相關聯的要求。清單不得留空。

  注意：

  • 也允許使用子網域，例如「a.example.com」。
  • 輸入內容只能包含 ASCII 字元。
  • 如果是國際化網域，請使用域名代碼編碼。
  • 系統也會比對所列網域的子網域。
  • 如果要求沒有相關聯的頂層框架 (例如 ServiceWorker 啟動的要求)，系統會改為考量要求發起者的網域。
• urlFilter

  字串 選填

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

  「*」：萬用字元，可比對任意數量的字元。

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

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

  「^」：分隔符號字元。比對字母、數字或下列字元以外的任何內容：_、-、. 或 %。這也會比對網址結尾。

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

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

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

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

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

列舉

屬性

• 已啟用

  布林值

  規則集是否預設為啟用。

• id

  字串

  不為空白的字串，可唯一識別規則集。以「_」開頭的 ID 保留供內部使用。

• 路徑

  字串

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

屬性

• rulesMatchedInfo

  MatchedRuleInfo[]

  符合指定篩選條件的規則。

屬性

• 增加

  數字

  要增加分頁動作計數的量。負值會減少計數。

• tabId

  數字

  要更新動作計數的分頁。

屬性

• matchedRules

  MatchedRule[]

  與假設請求相符的規則 (如有)。

屬性

• 發起者

  字串 選填

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

• 方法

  RequestMethod 選填

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

• responseHeaders

  object 選填

  Chrome 129 以上版本

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

• tabId

  數字 選填

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

• topUrl

  字串 選填

  Chrome 145 以上版本

  要求的相關聯頂層頁框網址 (如有)。

• 類型

  ResourceType

  假設要求的資源類型。

• 網址

  字串

  假設要求的網址。

列舉

屬性

• addRules

  規則[] 選用

  要新增的規則。

• removeRuleIds

  number[] 選填

  要移除的規則 ID。系統會忽略無效的 ID。

屬性

• disableRulesetIds

  字串陣列 選用

  應停用的靜態 Ruleset 對應 ID 集。

• enableRulesetIds

  字串陣列 選用

  應啟用的靜態 Ruleset 對應 ID 集。

屬性

• disableRuleIds

  number[] 選填

  要停用的規則 ID 集，對應於 Ruleset 中的規則。

• enableRuleIds

  number[] 選填

  要啟用的 Ruleset 規則對應 ID 集。

• rulesetId

  字串

  與靜態 Ruleset 對應的 ID。

屬性

• fragment

  字串 選填

  要求的新片段。應為空白 (現有片段會清除)，或以「#」開頭。

• 主機

  字串 選填

  要求的新主機。

• 密碼

  字串 選填

  要求的新密碼。

• 路徑

  字串 選填

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

• 通訊埠

  字串 選填

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

• 查詢

  字串 選填

  要求的新查詢。應為空白 (現有查詢會清除)，或以「?」開頭。

• queryTransform

  QueryTransform 選用

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

• 架構

  字串 選填

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

• 使用者名稱

  字串 選填

  要求的新使用者名稱。

值

值

值

值

值

值

值

值

值

值

值

值

參數

• callback

  函式 選填

  callback 參數如下：

  (count: number) => void

  • 數量

    數字

傳回

• Promise<number>

  Chrome 91 以上版本

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 選項

  GetDisabledRuleIdsOptions

  指定要查詢的規則集。

• callback

  函式 選填

  callback 參數如下：

  (disabledRuleIds: number[]) => void

  • disabledRuleIds

    number[]

傳回

• Promise<number[]>

  Promise 會解析為與該規則集中已停用規則相應的 ID 清單。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 篩選

  GetRulesFilter optional

  Chrome 111 以上版本

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

• callback

  函式 選填

  callback 參數如下：

  (rules: Rule[]) => void

  • 規則

    規則[]

傳回

• Promise<Rule[]>

  Chrome 91 以上版本

  Promise，會使用動態規則集解析。如果發生暫時性內部錯誤，系統可能會拒絕 Promise。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• callback

  函式 選填

  callback 參數如下：

  (rulesetIds: string[]) => void

  • rulesetIds

    string[]

傳回

• Promise<string[]>

  Chrome 91 以上版本

  Promise 會以 ID 清單解析，其中每個 ID 都對應至已啟用的靜態 Ruleset。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 篩選

  MatchedRulesFilter 選填

  用於篩選相符規則清單的物件。

• callback

  函式 選填

  callback 參數如下：

  (details: RulesMatchedDetails) => void

  • 詳細資料

    RulesMatchedDetails

傳回

• Promise<RulesMatchedDetails>

  Chrome 91 以上版本

  擷取相符規則清單後，系統會解析這個 Promise。如果發生錯誤，Promise 會遭到拒絕。這可能是因為權限不足或超出配額等原因。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 篩選

  GetRulesFilter optional

  Chrome 111 以上版本

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

• callback

  函式 選填

  callback 參數如下：

  (rules: Rule[]) => void

  • 規則

    規則[]

傳回

• Promise<Rule[]>

  Chrome 91 以上版本

  承諾會使用一組工作階段範圍規則來解析。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• regexOptions

  RegexOptions

  要檢查的規則運算式。

• callback

  函式 選填

  callback 參數如下：

  (result: IsRegexSupportedResult) => void

  • 結果

    IsRegexSupportedResult

傳回

• Promise<IsRegexSupportedResult>

  Chrome 91 以上版本

  Promise 會解析為詳細資料，包括是否支援規則運算式，以及不支援的原因 (如有)。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 選項

  ExtensionActionOptions

• callback

  函式 選填

  Chrome 89 以上版本

  callback 參數如下：

  () => void

傳回

• Promise<void>

  Chrome 91 以上版本

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 申請。

  TestMatchRequestDetails

• callback

  函式 選填

  callback 參數如下：

  (result: TestMatchOutcomeResult) => void

  • 結果

    TestMatchOutcomeResult

傳回

• Promise<TestMatchOutcomeResult>

  Promise，會使用相符規則的詳細資料解析。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 選項

  UpdateRuleOptions

  Chrome 87 以上版本
• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• Promise<void>

  Chrome 91 以上版本

  更新完成後，系統會解析這個 Promise。如果發生錯誤，系統會拒絕 Promise，且不會對規則集進行任何變更。可能原因有很多，例如規則格式無效、規則 ID 重複、超出規則數量上限，以及內部錯誤等。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 選項

  UpdateRulesetOptions

  Chrome 87 以上版本
• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• Promise<void>

  Chrome 91 以上版本

  更新完成後，系統會解析這個 Promise。如果發生錯誤，系統會拒絕 Promise，且不會變更已啟用規則集的集合。可能原因很多，例如規則集 ID 無效、超過規則數量上限或發生內部錯誤。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 選項

  UpdateRuleOptions

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• Promise<void>

  Chrome 91 以上版本

  更新完成後，系統會解析這個 Promise。如果發生錯誤，系統會拒絕 Promise，且不會對規則集進行任何變更。可能原因有很多，例如規則格式無效、規則 ID 重複、超出規則數量上限等。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• 選項

  UpdateStaticRulesOptions

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• Promise<void>

  更新完成時會解析的 Promise。如果發生錯誤，系統會拒絕 Promise，且不會變更已啟用的靜態規則。

  只有資訊清單 V3 以上版本支援 Promise，其他平台則需使用回呼。

參數

• callback

  函式

  callback 參數如下：

  (info: MatchedRuleInfoDebug) => void

  • 資訊

    MatchedRuleInfoDebug