Opis
Interfejs API chrome.declarativeNetRequest
służy do blokowania lub modyfikowania żądań sieciowych przez określenie reguł deklaratywne. Dzięki temu rozszerzenia mogą modyfikować żądania sieciowe bez ich przechwytywania i wyświetlania treści, co zwiększa prywatność.
Uprawnienia
declarativeNetRequest
declarativeNetRequestWithHostAccess
declarativeNetRequestFeedback
host_permissions
Dostępność
Plik manifestu
Oprócz opisanych powyżej uprawnień niektóre typy zestawów reguł (w szczególności statyczne zestawy reguł) wymagają zadeklarowania klucza manifestu "declarative_net_request"
, który powinien być słownikiem z pojedynczym kluczem o nazwie "rule_resources"
. Ten klucz to tablica zawierająca słowniki typu Ruleset
, jak pokazano poniżej. (Zwróć uwagę, że nazwa „Zestaw reguł” nie pojawia się w pliku JSON pliku manifestu, ponieważ jest to jedynie tablica). Statyczne zestawy reguł zostały objaśnione w dalszej części tego dokumentu.
{
"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/*"
],
...
}
Pojęcia i zastosowanie
Aby użyć tego interfejsu API, określ co najmniej 1 zestaw reguł. Zestaw reguł zawiera tablicę reguł. Pojedyncza reguła ma jeden z tych parametrów:
- Zablokuj żądanie sieciowe.
- Uaktualnij schemat (http do https).
- Aby zapobiec blokowaniu żądania, neguj pasujące reguły zablokowane.
- Przekieruj żądanie sieciowe.
- Zmodyfikuj nagłówki żądania lub odpowiedzi.
Istnieją 3 typy zestawów reguł, którymi można zarządzać w nieco inny sposób.
- Dynamiczna
- Zostaną zachowane przez wszystkie sesje przeglądarki i uaktualnienia rozszerzeń, a zarządzanie nimi odbywa się za pomocą JavaScriptu, gdy używane jest rozszerzenie.
- Sesja
- Zostaną usunięte, gdy przeglądarka wyłącza się i zainstalowana jest nowa wersja rozszerzenia. Reguły sesji są zarządzane za pomocą JavaScriptu, gdy używane jest rozszerzenie.
- Statyczny
- Pakiety, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Reguły statyczne są przechowywane w plikach reguł w formacie JSON i są wymienione w pliku manifestu.
W kilku następnych sekcjach szczegółowo opisujemy typy zestawów reguł.
Dynamiczne i ograniczone do sesji zestawy reguł
Zestawy reguł dynamicznych i sesji są zarządzane za pomocą JavaScriptu, gdy używane jest rozszerzenie.
- Reguły dynamiczne pozostają aktywne niezależnie od sesji przeglądarki i uaktualnień rozszerzeń.
- Reguły sesji są czyszczone po wyłączeniu przeglądarki i zainstalowaniu nowej wersji rozszerzenia.
Każdy z tych typów zestawów reguł istnieje tylko po jednym. Rozszerzenie może dynamicznie dodawać i usuwać reguły, wywołując updateDynamicRules()
i updateSessionRules()
, o ile limity reguł nie zostaną przekroczone. Informacje o limitach reguł znajdziesz w artykule Ograniczenia reguł. Przykład znajdziesz w sekcji przykładowy kod.
Statyczne zestawy reguł
W odróżnieniu od reguł dynamicznych i reguł dotyczących sesji reguły statyczne są pakowane, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Są one przechowywane w plikach reguł w formacie JSON, które są wskazane rozszerzeniu za pomocą kluczy "declarative_net_request"
i "rule_resources"
jak opisano powyżej, a także co najmniej 1 słownika Ruleset
. Słownik Ruleset
zawiera ścieżkę do pliku reguły, identyfikator zawartego w pliku reguł zestawu reguł oraz informację o tym, czy zestaw reguł jest włączony czy wyłączony. Dwa ostatnie są ważne przy automatycznym włączaniu lub wyłączaniu zestawu reguł.
{
...
"declarative_net_request" : {
"rule_resources" : [{
"id": "ruleset_1",
"enabled": true,
"path": "rules_1.json"
},
...
]
}
...
}
Aby przetestować pliki reguł, załaduj rozszerzenie bez pakietu. Błędy i ostrzeżenia dotyczące nieprawidłowych reguł statycznych są wyświetlane tylko w przypadku rozszerzeń bez pakietu. Nieprawidłowe reguły statyczne w rozszerzeniach w pakiecie są ignorowane.
Włączanie i wyłączanie statycznych reguł i zestawów reguł
Zarówno pojedyncze reguły statyczne, jak i całe zestawy reguł statycznych mogą być włączone lub wyłączone w czasie działania.
Zestaw włączonych reguł statycznych i zestawów reguł jest zachowywany pomiędzy sesjami przeglądarki. Żadna z nich nie jest zachowywana po aktualizacji rozszerzeń, co oznacza, że po aktualizacji dostępne są tylko reguły pozostawione w plikach reguł.
Ze względu na wydajność istnieją też ograniczenia dotyczące liczby reguł i zestawów reguł, które można włączyć jednocześnie. Zadzwoń pod numer getAvailableStaticRuleCount()
, aby sprawdzić liczbę dodatkowych reguł, które można włączyć. Informacje o limitach reguł znajdziesz w artykule Ograniczenia reguł.
Aby włączyć lub wyłączyć statyczne reguły, wywołaj updateStaticRules()
. Ta metoda pobiera obiekt UpdateStaticRulesOptions
zawierający tablice identyfikatorów reguł do włączenia lub wyłączenia. Identyfikatory są definiowane za pomocą klucza "id"
w słowniku Ruleset
.
Aby włączyć lub wyłączyć statyczne rulesets, wywołaj updateEnabledRulesets()
. Ta metoda pobiera obiekt UpdateRulesetOptions
zawierający tablice identyfikatorów zestawów reguł do włączenia lub wyłączenia. Identyfikatory są definiowane za pomocą klucza "id"
w słowniku Ruleset
.
Tworzenie reguł
Niezależnie od typu reguła rozpoczyna się od czterech pól, jak pokazano poniżej. Klawisze "id"
i "priority"
pobierają liczby, ale "action"
i "condition"
mogą zapewniać kilka warunków blokowania i przekierowania. Poniższa reguła blokuje wszystkie żądania skryptu pochodzące z adresu "foo.com"
do dowolnego adresu URL, którego podłańcuch jest "abc"
.
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "abc",
"initiatorDomains" : ["foo.com"],
"resourceTypes" : ["script"]
}
}
Pasujące znaki urlFilter
Klucz "condition"
reguły umożliwia użycie klucza "urlFilter"
do wykonywania działań na adresach URL w określonej domenie. Wzorce możesz tworzyć za pomocą tokenów dopasowywania do wzorców. Poniżej przedstawiamy kilka przykładów.
urlFilter |
Odpowiada | Nie pasuje |
---|---|---|
"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 |
Określanie priorytetów reguł
Reguły są wywoływane przez żądania wysyłane ze stron internetowych. Jeśli do danego żądania pasuje wiele reguł, reguły muszą mieć priorytet. Z tej sekcji dowiesz się, jak są ustalane priorytety. Określanie priorytetów odbywa się dwuetapowo.
- Priorytety są określane w przypadku reguł w rozszerzeniu.
- Jeśli do żądania można zastosować regułę więcej niż jednego rozszerzenia, priorytet jest określany dla wszystkich rozszerzeń, które pasują do konkretnego żądania.
Takie dopasowanie: reguły, które nadają priorytet konkretnemu rozszerzeniu, będą miały wyższy priorytet niż reguły innych rozszerzeń.
Określanie priorytetów reguł w ramach rozszerzenia
W ramach pojedynczego rozszerzenia ustalanie priorytetów jest realizowane w ten sposób:
- Zwracana jest reguła o najwyższym priorytecie zdefiniowanym przez dewelopera (czyli pole
"priority"
). Jeśli istnieje więcej niż 1 reguła o najwyższym priorytecie określonym przez programistę, reguły mają priorytet w polu
"action"
w takiej kolejności:allow
allowAllRequests
block
upgradeScheme
redirect
Jeśli typem działania nie jest
block
aniredirect
, sprawdzane są wszystkie pasujące regułymodifyHeaders
. Pamiętaj, że jeśli istnieją reguły, których priorytet zdefiniowany przez dewelopera jest niższy niż priorytet określony wallow
iallowAllRequests
, zostaną one zignorowane.Jeśli wiele reguł modyfikuje ten sam nagłówek, zmiana zależy od zdefiniowanego przez dewelopera pola
"priority"
i określonych operacji.- Jeśli reguła dołącza do nagłówka, reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Operacje ustawiania i usuwania są niedozwolone.
- Jeśli reguła ustawia nagłówek, wtedy reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Nie są dozwolone żadne inne modyfikacje.
- Jeśli reguła usuwa nagłówek, reguły o niższym priorytecie nie mogą go już modyfikować.
Określanie priorytetów reguł dla rozszerzeń
Jeśli tylko jedno rozszerzenie ma regułę, która pasuje do żądania, jest ona stosowana. Jeśli jednak do żądania pasuje więcej niż jedno rozszerzenie, używany jest następujący proces:
Priorytet reguł jest ustalany w polu
"action"
w takiej kolejności:block
redirect
lubupgradeScheme
allow
luballowAllRequests
Jeśli pasuje więcej niż 1 reguła, priorytet ma ostatnio zainstalowane rozszerzenie.
Ograniczenia reguł
Wczytywanie i ocenianie reguł w przeglądarce wiąże się z zwiększeniem wydajności, dlatego podczas korzystania z interfejsu API obowiązują pewne ograniczenia. Limity zależą od typu reguły.
Reguły statyczne
Reguły statyczne to reguły określone w plikach reguł zadeklarowanych w pliku manifestu. Rozszerzenie może określić w kluczu manifestu "rule_resources"
maksymalnie 50 statycznych rulesets, ale jednocześnie może być włączonych tylko 10 z tych zestawów reguł. Ten drugi rodzaj danych nosi nazwę MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
. Łącznie te zestawy reguł mają gwarancję co najmniej 30 tys. reguł. Nazywa się GUARANTEED_MINIMUM_STATIC_RULES
.
Liczba dostępnych reguł zależy od tego, ile reguł włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Możesz go sprawdzić w czasie działania, dzwoniąc pod numer getAvailableStaticRuleCount()
. Przykład znajdziesz w sekcji przykładowy kod.
Reguły dynamiczne i reguły sesji
Limity obowiązujące w regułach dynamicznych i reguł dotyczących sesji są prostsze niż reguły statyczne. Łączna liczba nie może przekraczać 5000. Nazywa się MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
.
Reguły używające wyrażeń regularnych
Wszystkie typy reguł mogą korzystać z wyrażeń regularnych, jednak łączna liczba reguł każdego typu nie może przekroczyć 1000. Jest to tzw. MAX_NUMBER_OF_REGEX_RULES.
Poza tym każda reguła musi mieć mniej niż 2 KB po skompilowaniu. Odpowiada to złożoności reguły. Jeśli spróbujesz wczytać regułę, która przekracza ten limit, zobaczysz ostrzeżenie podobne do tego poniżej, a reguła zostanie zignorowana.
rules_1.json: Rule with id 1 specified a more complext regex than allowed
as part of the "regexFilter" key.
Interakcje z mechanizmami Service Worker
DeklaratativeNetRequest ma zastosowanie tylko do żądań docierających do stosu sieciowego. Obejmuje to odpowiedzi z pamięci podręcznej HTTP, ale mogą nie zawierać odpowiedzi, które przechodzą przez moduł obsługi onfetch
skryptu service worker. deklarativeNetRequest nie ma wpływu na odpowiedzi generowane przez mechanizm Service Worker lub pobierane z CacheStorage
, ale ma wpływ na wywołania fetch()
wykonywane w skrypcie service worker.
Zasoby dostępne w internecie
Reguła deklarativeNetRequest nie może przekierowywać z żądania zasobu publicznego do zasobu, który nie jest dostępny w internecie. Spowoduje to wyświetlenie błędu. Dzieje się tak nawet wtedy, gdy podany zasób dostępny z internetu należy do rozszerzenia przekierowującego. Aby zadeklarować zasoby na potrzeby żądania deklarativeNetRequest, użyj tablicy "web_accessible_resources"
pliku manifestu.
Przykłady
Przykłady kodu
Aktualizowanie reguł dynamicznych
Poniższy przykład pokazuje, jak wywołać updateDynamicRules()
. Procedura updateSessionRules()
jest taka sama.
// 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
});
Aktualizowanie statycznych zestawów reguł
Poniższy przykład pokazuje, jak włączać i wyłączać zestawy reguł z uwzględnieniem liczby dostępnych i maksymalnej liczby włączonych statycznych zestawów reguł. Należy to zrobić, gdy liczba potrzebnych reguł statycznych przekracza dozwoloną liczbę. Aby te zestawy reguł działały, należy zainstalować niektóre zestawy reguł (w pliku manifestu ustaw "Enabled"
na 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);
}
Przykłady reguł
Poniższe przykłady pokazują, jak Chrome nadaje priorytet regułom w rozszerzeniu. Warto je otworzyć w osobnym oknie z regułami ustalania priorytetów.
Klawisz „Priority”
Te przykłady wymagają uprawnień hosta dla: *://*.example.com/*
.
Aby określić priorytet poszczególnych adresów URL, przeanalizuj następujące klucze: "priority"
(zdefiniowane przez programistę), "action"
i "urlFilter"
. Te przykłady dotyczą przykładowego pliku reguł pokazanego pod nimi.
- Wejdź na https://google.com
- Ten adres URL obejmuje 2 reguły: reguły o identyfikatorach 1 i 4. Obowiązuje reguła o identyfikatorze 1, ponieważ działania
"block"
mają wyższy priorytet niż działania"redirect"
. Pozostałe reguły nie mają zastosowania, ponieważ dotyczą dłuższych adresów URL. - Wejdź na https://google.com/1234
- Z powodu dłuższego adresu URL reguła o identyfikatorze 2 będzie teraz pasować do reguł o identyfikatorach 1 i 4. Obowiązuje reguła o identyfikatorze 2, bo element
"allow"
ma wyższy priorytet niż zasady"block"
i"redirect"
. - Wejdź na https://google.com/12345
- Wszystkie 4 reguły pasują do tego adresu URL. Obowiązuje reguła o identyfikatorze 3, ponieważ jej priorytet zdefiniowany przez programistę ma najwyższy priorytet z grupy.
[
{
"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"] }
},
]
Przekierowania
Poniższy przykład wymaga uprawnień hosta dla użytkownika *://*.example.com/*
.
Z przykładu poniżej dowiesz się, jak przekierować żądanie z example.com na stronę wewnątrz rozszerzenia. Ścieżka rozszerzenia /a.jpg
prowadzi do chrome-extension://EXTENSION_ID/a.jpg
, gdzie EXTENSION_ID
to identyfikator rozszerzenia. Aby to zadziałało, plik manifestu powinien zadeklarować /a.jpg
jako zasób dostępny przez internet.
{
"id": 1,
"priority": 1,
"action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
"condition": {
"urlFilter": "https://www.example.com",
"resourceTypes": ["main_frame"]
}
}
W poniższym przykładzie użyto klucza "transform"
do przekierowania do subdomeny example.com. Wykorzystuje on kotwicę nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z example.com. Klucz "scheme"
w elemencie "transform"
określa, że przekierowania do subdomeny zawsze będą używać „https”.
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": { "scheme": "https", "host": "new.example.com" }
}
},
"condition": {
"urlFilter": "||example.com",
"resourceTypes": ["main_frame"]
}
}
Poniższy przykład pokazuje przekierowanie z https://www.abc.xyz.com/path
do https://abc.xyz.com/path
za pomocą wyrażeń regularnych. Zwróć uwagę, jak w kluczu "regexFilter"
zmienia się znaczenie kropek, a grupa przechwytywania wybiera „abc” lub „def”. Klucz "regexSubstitution"
określa pierwsze zwrócone dopasowanie wyrażenia regularnego z użyciem parametru „\1”. W tym przypadku element „abc” jest przechwytywany z przekierowującego adresu URL i umieszczany w jego podstawie.
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"regexSubstitution": "https://\\1.xyz.com/"
}
},
"condition": {
"regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
"resourceTypes": [
"main_frame"
]
}
}
nagłówków,
Z przykładu poniżej widać wszystkie pliki cookie zarówno z ramki głównej, jak i z ramek podrzędnych.
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [{ "header": "cookie", "operation": "remove" }]
},
"condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}
Typy
DomainType
Określa, czy żądanie pochodzi od Ciebie, czy od strony trzeciej w ramach ramki, z której pochodzi. Żądanie jest uznawane za własne, jeśli ma tę samą domenę (eTLD + 1) co ramka, z której pochodzi żądanie.
Typ wyliczeniowy
„Własne”
Żądanie sieciowe jest własne w ramce, z której pochodzi.
"thirdParty"
Żądanie sieci pochodzi od firmy zewnętrznej do ramki, z której pochodzi.
ExtensionActionOptions
Właściwości
-
displayActionCountAsBadgeText
wartość logiczna opcjonalna
Określa, czy automatycznie wyświetlać liczbę działań na stronie jako tekst plakietki rozszerzenia. To ustawienie jest zachowywane we wszystkich sesjach.
-
tabUpdate
TabActionCountUpdate opcjonalnie
Chrome 89 i nowsze wersjeSzczegóły dotyczące dostosowywania liczby działań na karcie.
GetDisabledRuleIdsOptions
Właściwości
-
rulesetId
string,
Identyfikator odpowiadający statycznemu elementowi
Ruleset
.
GetRulesFilter
Właściwości
-
ruleIds
number[] opcjonalny
Jeśli podasz wartość, uwzględnione zostaną tylko reguły o pasujących identyfikatorach.
HeaderOperation
Opisuje możliwe operacje na regule „modifyHeaders”.
Typ wyliczeniowy
"append"
Dodaje nowy wpis dla określonego nagłówka. Ta operacja nie jest obsługiwana w nagłówkach żądań.
"set"
Ustawia nową wartość dla określonego nagłówka, usuwając wszystkie istniejące nagłówki o tej samej nazwie.
"remove"
Usuwa wszystkie wpisy z określonego nagłówka.
IsRegexSupportedResult
Właściwości
-
isSupported
boolean
-
powód
UnsupportedRegexReason opcjonalnie
Określa przyczynę, dla której wyrażenie regularne nie jest obsługiwane. Podana tylko wtedy, gdy
isSupported
ma wartość false (fałsz).
MatchedRule
Właściwości
-
ruleId
Liczba
Identyfikator pasującej reguły.
-
rulesetId
string,
Identyfikator
Ruleset
, do którego należy ta reguła. W przypadku reguły, która pochodzi ze zbioru reguł dynamicznych, wartość ta będzie równaDYNAMIC_RULESET_ID
.
MatchedRuleInfo
Właściwości
-
reguła
-
tabId
Liczba
Identyfikator tabId karty, z której pochodzi żądanie, jeśli karta jest nadal aktywna. Inne: -1.
-
timeStamp
Liczba
Czas dopasowania reguły. Sygnatury czasowe będą odpowiadać konwencji JavaScriptu dotyczące czasu, tj. liczby milisekund od początku epoki.
MatchedRuleInfoDebug
Właściwości
-
Poproś
Szczegółowe informacje o żądaniu, do którego została dopasowana reguła.
-
reguła
MatchedRulesFilter
Właściwości
-
minTimeStamp
Liczba opcjonalnie
Jeśli jest określony, dopasowuje reguły tylko po podanej sygnaturze czasowej.
-
tabId
Liczba opcjonalnie
Jeśli określono, dopasowuje reguły tylko dla danej karty. Dopasowuje reguły niepowiązane z żadną aktywną kartą, jeśli ma wartość -1.
ModifyHeaderInfo
Właściwości
-
nagłówek
string,
Nazwa nagłówka do modyfikacji.
-
operacja
Operacja do wykonania na nagłówku.
-
value
ciąg znaków opcjonalny
Nowa wartość nagłówka. Należy określić dla operacji
append
iset
.
QueryKeyValue
Właściwości
-
klucz
string,
-
replaceOnly
wartość logiczna opcjonalna
Chrome 94 i nowsze wersjeJeśli ma wartość true (prawda), klucz zapytania jest zastępowany tylko wtedy, gdy już istnieje. W przeciwnym razie zostanie też dodany klucz, jeśli go nie ma. Wartość domyślna to fałsz.
-
value
string,
QueryTransform
Właściwości
-
addOrReplaceParams
QueryKeyValue[] opcjonalny
Lista par klucz-wartość zapytania do dodania lub zastąpienia.
-
removeParams
string[] opcjonalny
Lista kluczy zapytania do usunięcia.
Redirect
Właściwości
-
extensionPath
ciąg znaków opcjonalny
Ścieżka względem katalogu rozszerzeń. Musi zaczynać się od znaku „/”.
-
regexSubstitution
ciąg znaków opcjonalny
Wzorzec zastępowania dla reguł, które określają wartość
regexFilter
. Pierwsze dopasowanie elementuregexFilter
w adresie URL zostanie zastąpione tym wzorcem. WregexSubstitution
do wstawiania odpowiednich grup przechwytywania można używać cyfr z ukośnikiem lewym (\1–\9). \0 oznacza cały pasujący tekst. -
przekształcenie
URLTransform (opcjonalnie)
Przekształcenia adresów URL do wykonania.
-
URL
ciąg znaków opcjonalny
Przekierowanie. Przekierowania do adresów URL JavaScript są niedozwolone.
RegexOptions
Właściwości
-
isCaseSensitive
wartość logiczna opcjonalna
Określa, czy w podanym elemencie
regex
wielkość liter ma znaczenie. Wartość domyślna to true (prawda). -
wyrażenie regularne
string,
Wyrażenie regularne do sprawdzenia.
-
requireCapturing
wartość logiczna opcjonalna
Określa, czy określony obiekt
regex
wymaga przechwytywania. Przechwytywanie jest wymagane tylko w przypadku reguł przekierowania, które określają działanieregexSubstition
. Wartość domyślna to false (fałsz).
RequestDetails
Właściwości
-
documentId
ciąg znaków opcjonalny
Chrome 106 i nowsze wersjeUnikalny identyfikator dokumentu ramki, jeśli żądanie dotyczy ramki.
-
documentLifecycle
DocumentLifecycle opcjonalnie
Chrome 106 i nowsze wersjeCykl życia dokumentu ramki, jeśli żądanie dotyczy ramki.
-
frameId
Liczba
Wartość 0 oznacza, że żądanie jest wysyłane w ramce głównej, a wartość dodatnia wskazuje identyfikator ramki podrzędnej, w której żądanie jest wysyłane. Jeśli wczytany jest dokument (elementu podrzędnego) (
type
tomain_frame
lubsub_frame
), wartośćframeId
wskazuje identyfikator tej ramki, a nie identyfikator ramki zewnętrznej. Identyfikatory klatek są unikalne w obrębie karty. -
frameType
Opcjonalne FrameType.
Chrome 106 i nowsze wersjeTyp ramki, jeśli żądanie dotyczy ramki.
-
inicjator
ciąg znaków opcjonalny
Źródło, z którego zainicjowano żądanie. Nie zmienia się w wyniku przekierowania. Jeśli źródło jest nieprzezroczyste, zostanie użyty ciąg „null”.
-
method
string,
Standardowa metoda HTTP.
-
parentDocumentId
ciąg znaków opcjonalny
Chrome 106 i nowsze wersjeUnikalny identyfikator dokumentu nadrzędnego ramki, jeśli żądanie dotyczy ramki i ma element nadrzędny.
-
parentFrameId
Liczba
Identyfikator ramki, która opakowuje ramkę, która wysłała żądanie. Jeśli nie istnieje ramka nadrzędna, ustaw wartość -1.
-
requestId
string,
Identyfikator żądania. Identyfikatory żądań są unikalne w obrębie sesji przeglądarki.
-
tabId
Liczba
Identyfikator karty, na której występuje żądanie. Jeśli żądanie nie jest związane z kartą, ustaw wartość -1.
-
Niestandardowy typ treści
Typ zasobu żądania.
-
URL
string,
Adres URL żądania.
RequestMethod
Opisuje metodę żądania HTTP w żądaniu sieciowym.
Typ wyliczeniowy
"get"
"head"
"post"
"put"
ResourceType
Opisuje on typ zasobu żądania sieciowego.
Typ wyliczeniowy
"main_frame"
"sub_frame"
"script"
"object"
"xmlhttprequest"
"csp_report"
"media"
"websocket"
Rule
Właściwości
-
działanie
Działanie, które ma zostać wykonane w przypadku zgodności z regułą.
-
stan
Warunek, pod którym ta reguła jest wyzwalana.
-
id
Liczba
Unikalny identyfikator reguły. Obowiązkowa, powinna wynosić >= 1.
-
kampanii
Liczba opcjonalnie
Priorytet reguły. Domyślna wartość to 1. Gdy należy podać wartość, powinna być >= 1.
RuleAction
Właściwości
-
Przekieruj
Przekierowanie opcjonalnie
Opisuje sposób wykonywania przekierowania. Dotyczy tylko reguł przekierowania.
-
requestHeaders
ModifyHeaderInfo[] opcjonalny
Chrome 86 i nowsze wersjeNagłówki żądania do zmodyfikowania. Tej opcji można użyć tylko wtedy, gdy element RuleActionType ma wartość „modifyHeaders”.
-
responseHeaders
ModifyHeaderInfo[] opcjonalny
Chrome 86 i nowsze wersjeNagłówki odpowiedzi do zmodyfikowania w związku z żądaniem. Tej opcji można użyć tylko wtedy, gdy element RuleActionType ma wartość „modifyHeaders”.
-
Niestandardowy typ treści
Typ działania do wykonania.
RuleActionType
Opisuje działanie, które ma zostać wykonane, gdy jest spełniony dany warunek reguły.
Typ wyliczeniowy
"block"
Zablokuj żądanie sieciowe.
"redirect"
Przekieruj żądanie sieciowe.
"allow"
Zezwól na żądanie sieciowe. Żądanie nie zostanie przechwycone, jeśli istnieje pasująca do niego reguła zezwalająca.
"upgradeScheme"
Zmień schemat adresu URL żądania sieciowego na https, jeśli żądanie to http lub ftp.
"modifyHeaders"
Zmodyfikuj nagłówki żądania/odpowiedzi żądania sieciowego.
"allowAllRequests"
Akceptuj wszystkie żądania w hierarchii ramek, w tym samo żądanie ramki.
RuleCondition
Właściwości
-
domainType
Opcjonalny DomainType
Określa, czy żądanie sieciowe jest własne czy zewnętrzne w domenie, z której pochodzi. Jeśli ten argument zostanie pominięty, wszystkie żądania zostaną zaakceptowane.
-
domeny
string[] opcjonalny
Wycofane od Chrome 101Zamiast niej użyj
initiatorDomains
.Reguła będzie dopasowywać tylko żądania sieciowe pochodzące z listy
domains
. -
excludedDomains
string[] opcjonalny
Wycofane od Chrome 101Zamiast niej użyj
excludedInitiatorDomains
.Reguła nie będzie pasować do żądań sieciowych pochodzących z listy
excludedDomains
. -
excludedInitiatorDomains
string[] opcjonalny
Chrome 101 i nowsze wersjeReguła nie będzie pasować do żądań sieciowych pochodzących z listy
excludedInitiatorDomains
. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ma pierwszeństwo przedinitiatorDomains
.Uwagi:
- Subdomeny takie jak „a.example.com” również są dozwolone.
- Wpisy mogą zawierać tylko znaki ASCII.
- W przypadku domen międzynarodowych używaj kodowania punycode.
- Adres ten jest zgodny z adresem URL inicjatora żądania, a nie z adresem URL tego żądania.
- Subdomeny wymienionych domen są również wykluczone.
-
excludedRequestDomains
string[] opcjonalny
Chrome 101 i nowsze wersjeReguła nie będzie dopasowywana do żądań sieciowych, gdy domeny będą pasować do jednej z nich na liście
excludedRequestDomains
. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ma pierwszeństwo przedrequestDomains
.Uwagi:
- Subdomeny takie jak „a.example.com” również są dozwolone.
- Wpisy mogą zawierać tylko znaki ASCII.
- W przypadku domen międzynarodowych używaj kodowania punycode.
- Subdomeny wymienionych domen są również wykluczone.
-
excludedRequestMethods
RequestMethod[] opcjonalny
Chrome 91 i nowsze wersjeLista metod żądań, których reguła nie będzie pasować. Należy określić tylko jedną z tych wartości:
requestMethods
iexcludedRequestMethods
. Jeśli żadna z tych metod nie zostanie określona, dopasowywane są wszystkie metody żądań. -
excludedResourceTypes
ResourceType[] opcjonalny
Lista typów zasobów, do których reguła nie będzie pasować. Należy określić tylko jedną z tych wartości:
resourceTypes
iexcludedResourceTypes
. Jeśli nie podasz żadnej z nich, wszystkie typy zasobów oprócz „main_frame” będą blokowane. -
excludedTabIds
number[] opcjonalny
Chrome 92 i nowsze wersjeLista elementów
tabs.Tab.id
, do których reguła nie powinna pasować. Identyfikatortabs.TAB_ID_NONE
nie uwzględnia żądań, które nie pochodzą z karty. Obsługiwane tylko w przypadku reguł ograniczonych do sesji. -
initiatorDomains
string[] opcjonalny
Chrome 101 i nowsze wersjeReguła będzie dopasowywać tylko żądania sieciowe pochodzące z listy
initiatorDomains
. W przypadku pominięcia listy reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.Uwagi:
- Subdomeny takie jak „a.example.com” również są dozwolone.
- Wpisy mogą zawierać tylko znaki ASCII.
- W przypadku domen międzynarodowych używaj kodowania punycode.
- Adres ten jest zgodny z adresem URL inicjatora żądania, a nie z adresem URL tego żądania.
- Dopasowywane są również subdomeny wymienionych domen.
-
isUrlFilterCaseSensitive
wartość logiczna opcjonalna
Określa, czy w polu
urlFilter
czyregexFilter
(w zależności od tego, co jest określone) rozróżniana jest wielkość liter. Wartość domyślna to false (fałsz). -
regexFilter
ciąg znaków opcjonalny
Wyrażenie regularne dopasowane do adresu URL żądania sieciowego. Jest on zgodny ze składnią RE2.
Uwaga: można określić tylko jedną wartość
urlFilter
lubregexFilter
.Uwaga: pole
regexFilter
może zawierać tylko znaki ASCII. Jest on dopasowywany do adresu URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych), a wszelkie inne znaki spoza zestawu ASCII są zakodowane w formacie UTF-8. -
requestDomains
string[] opcjonalny
Chrome 101 i nowsze wersjeReguła będzie dopasowywać żądania sieciowe tylko wtedy, gdy domena jest zgodna z domeną z listy
requestDomains
. W przypadku pominięcia listy reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.Uwagi:
- Subdomeny takie jak „a.example.com” również są dozwolone.
- Wpisy mogą zawierać tylko znaki ASCII.
- W przypadku domen międzynarodowych używaj kodowania punycode.
- Dopasowywane są również subdomeny wymienionych domen.
-
requestMethods
RequestMethod[] opcjonalny
Chrome 91 i nowsze wersjeLista metod żądań HTTP, które może pasować do reguły. Pusta lista jest niedozwolona.
Uwaga: określenie warunku reguły
requestMethods
spowoduje też wykluczenie żądań innych niż HTTP, a określenie warunkuexcludedRequestMethods
nie. -
resourceTypes
ResourceType[] opcjonalny
Lista typów zasobów, które mogą być dopasowywane przez regułę. Pusta lista jest niedozwolona.
Uwaga: to pole należy określić w przypadku reguł
allowAllRequests
i może zawierać tylko typy zasobówsub_frame
orazmain_frame
. -
tabIds
number[] opcjonalny
Chrome 92 i nowsze wersjeLista elementów
tabs.Tab.id
, do których powinna pasować reguła. Identyfikatortabs.TAB_ID_NONE
pasuje do żądań, które nie pochodzą z karty. Pusta lista jest niedozwolona. Obsługiwane tylko w przypadku reguł ograniczonych do sesji. -
urlFilter
ciąg znaków opcjonalny
Wzorzec pasujący do adresu URL żądania sieciowego. Obsługiwane konstrukcje:
'*' : symbol wieloznaczny: odpowiada dowolnej liczbie znaków.
'|' : kotwica lewa/prawa: jeśli jest używany na dowolnym końcu wzorca, określa odpowiednio początek i koniec adresu URL.
„||” : kotwica nazwy domeny: jeśli jest używana na początku wzorca, określa początek (subdomeny) adresu URL.
'^' : znak separatora: odpowiada dowolnemu znakowi oprócz litery, cyfr lub jednego z tych znaków:
_
,-
,.
lub%
. Odpowiada też końcowi adresu URL.Dlatego element
urlFilter
składa się z tych elementów: (opcjonalnie kotwica nazwy lewej/domeny) + wzorzec + (opcjonalnie prawa kotwica).Jeśli go pominiesz, dopasowane będą wszystkie adresy URL. Pusty ciąg jest niedozwolony.
Wzorzec zaczynający się od
||*
jest niedozwolony. Użyj w zamian zasady*
.Uwaga: można określić tylko jedną wartość
urlFilter
lubregexFilter
.Uwaga: pole
urlFilter
może zawierać tylko znaki ASCII. Jest on dopasowywany do adresu URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych), a wszelkie inne znaki spoza zestawu ASCII są zakodowane w formacie UTF-8. Jeśli na przykład URL żądania to http://abc.р określany?q=dimension,urlFilter
zostanie dopasowany do adresu URL http://abc.xn--p1ai/?q=%D1%84.
Ruleset
Właściwości
-
włączone
boolean
Określa, czy zestaw reguł jest domyślnie włączony.
-
id
string,
Niepusty ciąg znaków jednoznacznie identyfikujący zestaw reguł. Identyfikatory zaczynające się od „_” są zarezerwowane do użytku wewnętrznego.
-
ścieżka
string,
Ścieżka zestawu reguł JSON względem katalogu rozszerzenia.
RulesMatchedDetails
Właściwości
-
rulesMatchedInfo
Reguły pasujące do danego filtra.
TabActionCountUpdate
Właściwości
-
Zwiększ
Liczba
Kwota, o którą ma się zwiększać liczba działań na karcie. Wartości ujemne zmniejszają liczbę.
-
tabId
Liczba
Karta, na której chcesz zaktualizować liczbę działań.
TestMatchOutcomeResult
Właściwości
-
matchedRules
Reguły (jeśli występują) pasujące do hipotetycznego żądania.
TestMatchRequestDetails
Właściwości
-
inicjator
ciąg znaków opcjonalny
Adres URL inicjatora (jeśli występuje) hipotetycznego żądania.
-
method
RequestMethod opcjonalny
Standardowa metoda HTTP hipotetycznego żądania. W przypadku żądań HTTP przyjmuje domyślnie wartość „get” i jest ignorowana w przypadku żądań innych niż HTTP.
-
tabId
Liczba opcjonalnie
Identyfikator karty, na której występuje hipotetyczne żądanie. Nie musi odpowiadać faktycznemu identyfikatorowi karty. Wartość domyślna to -1, co oznacza, że żądanie nie jest związane z kartą.
-
Niestandardowy typ treści
Typ zasobu hipotetycznego żądania.
-
URL
string,
Adres URL hipotetycznego żądania.
UnsupportedRegexReason
Opisuje przyczynę, dla której dane wyrażenie regularne nie jest obsługiwane.
Typ wyliczeniowy
"syntaxError"
Wyrażenie regularne ma nieprawidłową składnię lub wykorzystuje funkcje niedostępne w składni RE2.
"memoryLimitExceeded"
Wyrażenie regularne przekracza limit pamięci.
UpdateRuleOptions
Właściwości
-
addRules
Rule (Reguła) [] opcjonalny
Reguły do dodania.
-
removeRuleIds
number[] opcjonalny
Identyfikatory reguł do usunięcia. Nieprawidłowe identyfikatory zostaną zignorowane.
UpdateRulesetOptions
Właściwości
UpdateStaticRulesOptions
Właściwości
-
disableRuleIds
number[] opcjonalny
Zestaw identyfikatorów odpowiadających regułom w
Ruleset
, które mają zostać wyłączone. -
enableRuleIds
number[] opcjonalny
Zestaw identyfikatorów odpowiadających regułom w
Ruleset
, które mają być włączone. -
rulesetId
string,
Identyfikator odpowiadający statycznemu elementowi
Ruleset
.
URLTransform
Właściwości
-
fragment
ciąg znaków opcjonalny
Nowy fragment żądania. Pole powinno być puste. W takim przypadku istniejący fragment zostanie wyczyszczony lub powinien zaczynać się od znaku „#”.
-
organizator
ciąg znaków opcjonalny
Nowy host żądania.
-
hasło
ciąg znaków opcjonalny
Nowe hasło do żądania.
-
ścieżka
ciąg znaków opcjonalny
Nowa ścieżka żądania. Jeśli jest pusta, bieżąca ścieżka zostanie wyczyszczona.
-
port
ciąg znaków opcjonalny
Nowy port dla żądania. Jeśli jest pusty, istniejący port zostanie wyczyszczony.
-
zapytanie
ciąg znaków opcjonalny
Nowe zapytanie dotyczące żądania. Pole powinno być puste. W takim przypadku istniejące zapytanie zostanie wyczyszczone lub powinno zaczynać się od „?”.
-
queryTransform
Opcjonalnie QueryTransform
Dodawaj, usuwaj lub zastępuj pary klucz-wartość zapytania.
-
schemat
ciąg znaków opcjonalny
Nowy schemat żądania. Dozwolone wartości to „http”, „https”, „ftp” i „chrome-extension”.
-
nazwa użytkownika
ciąg znaków opcjonalny
Nowa nazwa użytkownika dla żądania.
Właściwości
DYNAMIC_RULESET_ID
Identyfikator zestawu reguł dla reguł dynamicznych dodanych przez rozszerzenie.
Wartość
"_dynamic"
GETMATCHEDRULES_QUOTA_INTERVAL
Przedział czasu (w minutach), w którym można wykonywać połączenia MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
. Dodatkowe połączenia nie będą natychmiast działać i zostaną skonfigurowane runtime.lastError
. Uwaga: wywołania getMatchedRules
powiązane z gestem użytkownika są zwolnione z limitu.
Wartość
10
GUARANTEED_MINIMUM_STATIC_RULES
Minimalna liczba reguł statycznych gwarantowanych przez rozszerzenie we wszystkich włączonych statycznych zestawach reguł. Reguły powyżej tego limitu wliczają się do limitu globalnych reguł statycznych.
Wartość
30000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
Liczba wywołań metody getMatchedRules
w okresie GETMATCHEDRULES_QUOTA_INTERVAL
.
Wartość
20
MAX_NUMBER_OF_DYNAMIC_RULES
Maksymalna liczba reguł dynamicznych, które może dodać rozszerzenie.
Wartość
30000
MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
Maksymalna liczba statycznych elementów Rulesets
, które rozszerzenie może włączyć jednocześnie.
Wartość
50
MAX_NUMBER_OF_REGEX_RULES
Maksymalna liczba reguł dotyczących wyrażeń regularnych, które może dodać rozszerzenie. Limit ten jest rozpatrywany oddzielnie dla zbioru reguł dynamicznych i tych określonych w pliku zasobów reguły.
Wartość
1000
MAX_NUMBER_OF_SESSION_RULES
Maksymalna liczba reguł ograniczonych do sesji, które rozszerzenie może dodać.
Wartość
5000
MAX_NUMBER_OF_STATIC_RULESETS
Maksymalna liczba statycznych elementów Rulesets
, które rozszerzenie może określić w kluczu manifestu "rule_resources"
.
Wartość
100
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
Maksymalna liczba niebezpiecznych reguł dynamicznych, które może dodać rozszerzenie.
Wartość
5000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
Maksymalna liczba „niebezpiecznych” reguł ograniczonych do sesji, które rozszerzenie może dodać.
Wartość
5000
SESSION_RULESET_ID
Identyfikator zestawu reguł dla reguł ograniczonych do sesji dodanych przez rozszerzenie.
Wartość
"_session"
Metody
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
Zwraca liczbę reguł statycznych, które rozszerzenie może włączyć, zanim zostanie osiągnięty limit globalnych reguł statycznych.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(count: number)=>void
-
liczba
Liczba
-
Akcje powrotne
-
Obietnica<number>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
Zwraca listę reguł statycznych, które są obecnie wyłączone w obrębie danego elementu Ruleset
.
Parametry
-
Określa zestaw reguł, których ma dotyczyć zapytanie.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(disabledRuleIds: number[])=>void
-
disabledRuleIds
liczba[]
-
Akcje powrotne
-
Obietnica<number[]>
Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
Zwraca bieżący zestaw reguł dynamicznych rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę pobranych reguł, określając właściwość filter
.
Parametry
-
filter
Opcjonalnie GetRulesFilter
Chrome 111 i nowsze wersjeObiekt do filtrowania listy pobranych reguł.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(rules: Rule[])=>void
-
reguły
Reguła[]
-
Akcje powrotne
-
Obietnica<Reguła[]>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
Zwraca identyfikatory bieżącego zestawu włączonych statycznych zestawów reguł.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(rulesetIds: string[])=>void
-
rulesetIds
string[]
-
Akcje powrotne
-
Obietnica<string[]>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
Zwraca wszystkie reguły pasujące do rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę dopasowanych reguł, określając element filter
. Ta metoda jest dostępna tylko w przypadku rozszerzeń z uprawnieniem "declarativeNetRequestFeedback"
lub uprawnieniem "activeTab"
dla elementu tabId
określonego w filter
. Uwaga: reguły niepowiązane z aktywnym dokumentem, które zostały dopasowane ponad pięć minut temu, nie zostaną zwrócone.
Parametry
-
filter
Opcjonalne MatchedRulesFilter
Obiekt do filtrowania listy dopasowanych reguł.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(details: RulesMatchedDetails)=>void
-
szczegóły
-
Akcje powrotne
-
Promise<RulesMatchedDetails>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
Zwraca bieżący zestaw reguł ograniczony do sesji dla rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę pobranych reguł, określając właściwość filter
.
Parametry
-
filter
Opcjonalnie GetRulesFilter
Chrome 111 i nowsze wersjeObiekt do filtrowania listy pobranych reguł.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(rules: Rule[])=>void
-
reguły
Reguła[]
-
Akcje powrotne
-
Obietnica<Reguła[]>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
isRegexSupported()
chrome.declarativeNetRequest.isRegexSupported(
regexOptions: RegexOptions,
callback?: function,
)
Sprawdza, czy dane wyrażenie regularne będzie obsługiwane jako warunek reguły regexFilter
.
Parametry
-
regexOptions
Wyrażenie regularne do sprawdzenia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: IsRegexSupportedResult)=>void
-
wynik
-
Akcje powrotne
-
Promise<IsRegexSupportedResult>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
setExtensionActionOptions()
chrome.declarativeNetRequest.setExtensionActionOptions(
options: ExtensionActionOptions,
callback?: function,
)
Określa, czy liczba działań na kartach ma być wyświetlana jako tekst plakietki działania rozszerzenia, oraz umożliwia zwiększanie tej liczby.
Parametry
-
Opcje
-
wywołanie zwrotne
funkcja opcjonalnie
Chrome 89 i nowsze wersjeParametr
callback
wygląda tak:()=>void
Akcje powrotne
-
Promise<void>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
Sprawdza, czy któraś z reguł deklaratywnych NetRequest rozszerzenia pasuje do hipotetycznego żądania. Uwaga: opcja dostępna tylko w przypadku rozszerzeń bez pakietu, ponieważ należy jej używać wyłącznie podczas tworzenia rozszerzeń.
Parametry
-
Poproś
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: TestMatchOutcomeResult)=>void
-
wynik
-
Akcje powrotne
-
Promise<TestMatchOutcomeResult>
Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
Modyfikuje bieżący zestaw reguł dynamicznych rozszerzenia. Reguły o identyfikatorach wymienione w kolumnie options.removeRuleIds
zostaną najpierw usunięte, a potem dodane zostaną reguły podane w polu options.addRules
. Uwagi:
- Ta aktualizacja to pojedyncza operacja niepodzielna: wszystkie określone reguły zostaną dodane i usunięte albo zostanie zwrócony błąd.
- Te reguły obowiązują przy wszystkich sesjach przeglądarki i aktualizacjach rozszerzeń.
- Reguł statycznych określonych w pakiecie rozszerzeń nie można usunąć za pomocą tej funkcji.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
to maksymalna liczba połączonych reguł dynamicznych i reguł sesji, które może dodać rozszerzenie.
Parametry
-
OpcjeChrome 87 i nowsze wersje
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:()=>void
Akcje powrotne
-
Promise<void>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
Aktualizuje zestaw włączonych statycznych zestawów reguł dla rozszerzenia. Zestawy reguł z identyfikatorami wymienionymi w zasadzie options.disableRulesetIds
zostaną najpierw usunięte, a potem dodane zostaną zestawy reguł wymienione w zasadzie options.enableRulesetIds
.
Pamiętaj, że zestaw włączonych statycznych zestawów reguł jest zachowywany w wielu sesjach, ale nie podczas aktualizacji rozszerzeń, np. klucz pliku manifestu rule_resources
określa zestaw włączonych statycznych zestawów reguł przy każdej aktualizacji rozszerzenia.
Parametry
-
OpcjeChrome 87 i nowsze wersje
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:()=>void
Akcje powrotne
-
Promise<void>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
Modyfikuje bieżący zestaw reguł ograniczonych do sesji dla rozszerzenia. Reguły o identyfikatorach wymienione w kolumnie options.removeRuleIds
zostaną najpierw usunięte, a potem dodane zostaną reguły podane w polu options.addRules
. Uwagi:
- Ta aktualizacja to pojedyncza operacja niepodzielna: wszystkie określone reguły zostaną dodane i usunięte albo zostanie zwrócony błąd.
- Reguły te nie są zachowywane w wielu sesjach, a ich kopie zapasowe są zapisywane w pamięci.
MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES
to maksymalna liczba połączonych reguł dynamicznych i reguł sesji, które może dodać rozszerzenie.
Parametry
-
Opcje
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:()=>void
Akcje powrotne
-
Promise<void>
Chrome 91 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
updateStaticRules()
chrome.declarativeNetRequest.updateStaticRules(
options: UpdateStaticRulesOptions,
callback?: function,
)
Wyłącza i włącza poszczególne reguły statyczne w Ruleset
. Zmiany w regułach należących do wyłączonego elementu Ruleset
zaczną obowiązywać po następnym włączeniu tej funkcji.
Parametry
-
Opcje
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:()=>void
Akcje powrotne
-
Promise<void>
Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
Wydarzenia
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
Uruchamiane, gdy reguła zostanie dopasowana do żądania. Ta opcja jest dostępna tylko w przypadku rozszerzeń bez pakietu z uprawnieniem "declarativeNetRequestFeedback"
, ponieważ jest przeznaczona wyłącznie do debugowania.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(info: MatchedRuleInfoDebug)=>void
-
informacje
-