Opis
Interfejs API chrome.declarativeNetRequest
służy do blokowania lub modyfikowania żądań sieciowych przez określenie reguł deklaratywnych. Dzięki temu rozszerzenia mogą modyfikować żądania sieciowe bez ich przechwytywania i wyświetlania treści, co zapewnia większą prywatność.
Uprawnienia
declarativeNetRequest
declarativeNetRequestWithHostAccess
„declarativeNetRequest
” i „declarativeNetRequestWithHostAccess
” uprawnienia
dają te same możliwości. Różnica między nimi polega na tym, że uprawnienia
którą poproszono lub przyznano.
"declarativeNetRequest"
- Wyświetla ostrzeżenie o uprawnieniach podczas instalacji, ale daje niejawny dostęp do:
Reguły
allow
,allowAllRequests
iblock
. Używaj go, gdy to możliwe, aby uniknąć które wymagają pełnego dostępu do hostów. "declarativeNetRequestFeedback"
- Udostępnia funkcje debugowania dotyczące rozpakowanych rozszerzeń, w szczególności
getMatchedRules()
ionRuleMatchedDebug
. "declarativeNetRequestWithHostAccess"
- Ostrzeżenie o uprawnieniach nie jest wyświetlane podczas instalacji, ale musisz poprosić o dostęp do hosta , zanim będzie można wykonać jakiekolwiek czynności na hoście. Ten jest odpowiednie, gdy chcesz użyć deklaratywnych reguł żądań netto w rozszerzenie, które ma już uprawnienia hosta bez generowania dodatkowych ostrzeżeniami.
Dostępność
Plik manifestu
Oprócz uprawnień opisanych powyżej niektóre typy zestawów reguł, a także 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 jest tablicą zawierającą słowniki typu Ruleset
, jak pokazano poniżej. Pamiętaj, że nazwa „Ruleset” (Zestaw reguł) nie pojawia się w pliku JSON manifestu, ponieważ jest to tylko tablica. Statyczne zestawy reguł zostały opisane 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 wykorzystanie
Aby użyć tego interfejsu API, określ co najmniej 1 zestaw reguł. Zestaw reguł zawiera tablicę reguł. Pojedyncza reguła może wykonywać jedną z tych czynności:
- Blokuj żądanie sieciowe.
- Uaktualnij schemat (z HTTP do https).
- Zapobiegaj blokowaniu żądania, negując wszystkie pasujące zablokowane reguły.
- Przekieruj żądanie sieciowe.
- modyfikować nagłówki żądania lub odpowiedzi;
Istnieją 3 typy zestawów reguł, którymi zarządzasz w nieco inny sposób.
- Dynamiczna
- Podczas korzystania z rozszerzenia działają w czasie sesji przeglądarki i uaktualniania rozszerzeń, a w czasie ich używania są zarządzane za pomocą JavaScriptu.
- Sesja
- Wyczyść, gdy przeglądarka się wyłączy i po zainstalowaniu nowej wersji rozszerzenia. Reguły sesji są zarządzane przez JavaScript, 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ą widoczne w pliku manifestu.
W kilku kolejnych sekcjach znajdziesz szczegółowe informacje o typach zestawów reguł.
Zestawy reguł dynamicznych i ograniczonych do sesji
Zbiory reguł dynamicznych i sesji są zarządzane za pomocą JavaScriptu, gdy używane jest rozszerzenie.
- Reguły dynamiczne pozostają niezmienne podczas sesji przeglądarki i uaktualniania 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ł może zawierać tylko 1 typ. Rozszerzenie może dynamicznie dodawać i usuwać reguły, wywołując parametry updateDynamicRules()
i updateSessionRules()
, o ile limity reguł nie zostaną przekroczone. Informacje o limitach reguł znajdziesz w artykule Limity reguł. Przykład znajdziesz w sekcji przykładowy kod.
Statyczne zestawy reguł
W przeciwieństwie do 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, co wskazuje rozszerzenie za pomocą kluczy "declarative_net_request"
i "rule_resources"
w sposób opisany powyżej, a także co najmniej 1 słownika Ruleset
. Słownik Ruleset
zawiera ścieżkę do pliku reguły, identyfikator zestawu reguł zawartych w pliku oraz informacje o tym, czy zestaw jest włączony czy wyłączony. Ostatnie dwa 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ł, rozpakuj rozszerzenie. Błędy i ostrzeżenia o nieprawidłowych regułach statycznych są wyświetlane tylko w przypadku rozszerzeń bez pakietu. Nieprawidłowe reguły statyczne w pakietach rozszerzeń są ignorowane.
Przyspieszona weryfikacja
Zmiany w statycznych zestawach reguł mogą kwalifikować się do przyspieszonego sprawdzenia. Zobacz przyspieszone sprawdzanie kwalifikujących się zmian.
Włączanie i wyłączanie reguł statycznych i zbiorów reguł
Zarówno pojedyncze reguły statyczne, jak i pełne statyczne zestawy reguł mogą być włączane lub wyłączane w czasie działania.
Zestaw włączonych reguł statycznych i zestawów reguł jest zachowywany przez wszystkie sesje przeglądarki. Żadne z nich nie są zachowywane przy aktualizacjach rozszerzeń, co oznacza, że po aktualizacji dostępne są tylko reguły, które zostawisz w plikach reguł.
Ze względu na wydajność obowiązują też limity liczby reguł i zestawów reguł, które można włączyć jednocześnie. Zadzwoń pod numer getAvailableStaticRuleCount()
, aby sprawdzić, ile dodatkowych reguł można włączyć. Informacje o limitach reguł znajdziesz w artykule Limity reguł.
Aby włączyć lub wyłączyć statyczne reguły, wywołaj updateStaticRules()
. Ta metoda przyjmuje obiekt UpdateStaticRulesOptions
, który zawiera tablice identyfikatorów reguł do włączenia lub wyłączenia. Identyfikatory definiuje się za pomocą klucza "id"
w słowniku Ruleset
. Dozwolonych jest maksymalnie 5000 wyłączonych reguł statycznych.
Aby włączyć lub wyłączyć statyczne reguły, wywołaj updateEnabledRulesets()
. Ta metoda przyjmuje obiekt UpdateRulesetOptions
, który zawiera tablice identyfikatorów zestawów reguł do włączenia lub wyłączenia. Identyfikatory definiuje się za pomocą klucza "id"
w słowniku Ruleset
.
Utwórz reguły
Bez względu na typ reguła zaczyna się od czterech pól, jak pokazano poniżej. Klucze "id"
i "priority"
zabierają wartość liczbową, a klucze "action"
i "condition"
mogą określać kilka warunków blokowania i przekierowania. Poniższa reguła blokuje wszystkie żądania skryptu wysyłane z adresu "foo.com"
do dowolnego adresu URL z podła��cuchem "abc"
.
{
"id" : 1,
"priority": 1,
"action" : { "type" : "block" },
"condition" : {
"urlFilter" : "abc",
"initiatorDomains" : ["foo.com"],
"resourceTypes" : ["script"]
}
}
Pasujące znaki urlFilter
Klucz "condition"
reguły zezwala kluczowi "urlFilter"
na wykonywanie działań na adresach URL w określonej domenie. Wzory możesz tworzyć za pomocą tokenów dopasowywania wzorców. Oto 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 |
Nadawanie priorytetów regułom
Reguły są wywoływane przez żądania wysyłane ze stron internetowych. Jeśli do jednego żądania pasuje wiele reguł, należy nadać im priorytet. Z tej sekcji dowiesz się, jak są traktowane priorytetowo. Określanie priorytetów przebiega dwuetapowo.
- Priorytet jest określany dla reguł w rozszerzeniu.
- Jeśli więcej niż jedno rozszerzenie może stosować regułę do żądania, priorytet jest określany dla wszystkich rozszerzeń, które pasują do danego żądania.
Taki sposób dopasowywania: reguła, którą ma dane rozszerzenie, będzie mieć wyższy priorytet względem reguł z innych rozszerzeń.
Nadawanie priorytetów regułom w rozszerzeniu
W ramach pojedynczego rozszerzenia priorytety są ustalane w ten sposób:
- Zwracana jest reguła o najwyższym priorytecie zdefiniowanym przez programistę (czyli z polem
"priority"
). Jeśli istnieje więcej niż 1 reguła o najwyższym priorytecie zdefiniowanym przez programistę, nadaje się ona priorytetom w polu
"action"
w następującej kolejności:allow
allowAllRequests
block
upgradeScheme
redirect
Jeśli typ działania jest inny niż
block
lubredirect
, sprawdzane są wszystkie pasujące regułymodifyHeaders
. Pamiętaj, że jeśli istnieją reguły o priorytecie zdefiniowanym przez programistę niższym niż priorytet określony dlaallow
iallowAllRequests
, są one ignorowane.Jeśli wiele reguł modyfikuje ten sam nagłówek, modyfikacje są określane przez zdefiniowane przez dewelopera pole
"priority"
oraz przez określone operacje.- Jeśli reguła jest dołączana do nagłówka, to reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Operacje ustawiania i usuwania nie są dozwolone.
- Jeśli reguła ustawia nagłówek, to reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Inne modyfikacje nie są dozwolone.
- Jeśli reguła usuwa nagłówek, reguły o niższym priorytecie nie mogą go dalej modyfikować.
Nadawanie priorytetów regułom między rozszerzeniami
Jeśli tylko jedno rozszerzenie ma regułę pasującą do żądania, jest ona stosowana. Jeśli jednak do żądania pasuje więcej niż jedno rozszerzenie, zostanie zastosowany ten proces:
Priorytety są ustalane w polu
"action"
w następującej kolejności:block
redirect
lubupgradeScheme
allow
luballowAllRequests
Jeśli pasuje więcej niż 1 reguła, pierwszeństwo ma ostatnio zainstalowane rozszerzenie.
Bezpieczne reguły
Bezpieczne reguły to reguły o działaniu block
, allow
,
allowAllRequests
lub upgradeScheme
. Reguły te podlegają
limit reguł dynamicznych.
Ograniczenia reguł
Wczytywanie i ocenianie reguł w przeglądarce wiąże się z dużą wydajnością, więc podczas korzystania z tego interfejsu obowiązują pewne ograniczenia. Limity zależą od typu używanej reguły.
Reguły statyczne
Reguły statyczne to reguły określone w plikach reguł zadeklarowanych w pliku manifestu. W kluczu manifestu "rule_resources"
rozszerzenie może zawierać maksymalnie 100 statycznych reguł, ale jednocześnie można włączyć tylko 50 z tych zestawów reguł. Ta ostatnia nazywa się MAX_NUMBER_OF_ENABLED_STATIC_RULESETS
. Łącznie dla tych zestawów reguł musi istnieć co najmniej 30 tys. reguł. Jest to tzw. GUARANTEED_MINIMUM_STATIC_RULES
.
Liczba dostępnych reguł zależy od tego, ile reguł są włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Aby go znaleźć w czasie działania, zadzwoń pod numer getAvailableStaticRuleCount()
. Przykład znajdziesz w sekcji przykładowy kod.
Reguły sesji
Rozszerzenie może mieć maksymalnie 5000 reguł sesji. Jest ona narażona na
MAX_NUMBER_OF_SESSION_RULES
.
Przed wersją Chrome 120 obowiązywał limit 5000 reguł dynamicznych i reguł dotyczących sesji.
Reguły dynamiczne
Rozszerzenie może mieć co najmniej 5000 reguł dynamicznych. Jest ona narażona na
MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
.
Od wersji Chrome 121 obowiązuje większy limit 30 tys. reguł dla bezpiecznych reguł dynamicznych,
są widoczne jako MAX_NUMBER_OF_DYNAMIC_RULES
. Dowolne
niebezpieczne reguły dodane do limitu do 5000 również będą wliczane do tego limitu.
Przed wersją Chrome 120 obowiązywał limit 5000 reguł dynamicznych i reguł sesji.
Reguły korzystające z wyrażeń regularnych
Wyrażenia regularne mogą być używane w przypadku wszystkich typów reguł. jednak łączna liczba reguł wyrażeń regularnych każdego typu nie może przekroczyć 1000. Jest to tzw. MAX_NUMBER_OF_REGEX_RULES.
Dodatkowo każda reguła po skompilowaniu musi mieć mniej niż 2 KB. Wynika to w przybliżeniu ze 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 complex regex than allowed
as part of the "regexFilter" key.
Interakcje z mechanizmami Service Worker
Parametr declarativeNetRequest obowiązuje tylko w przypadku żądań, które docierają do stosu sieciowego. Obejmuje to odpowiedzi z pamięci podręcznej HTTP, ale może nie obejmować odpowiedzi przekazywanych przez moduł obsługi onfetch
skryptu service worker. declarativeNetRequest nie wpłynie na odpowiedzi generowane przez skrypt service worker oraz pobrane z CacheStorage
, ale wpłynie na wywołania fetch()
wykonywane w skrypcie service worker.
Zasoby dostępne przez internet
Reguła declarativeNetRequest 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 określony zasób dostępny w internecie należy do rozszerzenia przekierowującego. Aby zadeklarować zasoby na potrzeby funkcji declarativeNetRequest, użyj tablicy "web_accessible_resources"
pliku manifestu.
Modyfikacja nagłówka
Operacja dołączania jest obsługiwana tylko w przypadku tych nagłówków: accept
, accept-encoding
, accept-language
, access-control-request-headers
, cache-control
, connection
, content-language
, cookie
, forwarded
, if-match
, if-none-match
, keep-alive
, range
, te
, trailer
, transfer-encoding
, upgrade
, user-agent
, via
, want-digest
, x-forwarded-for
.
Przykłady
Przykłady kodu
Zaktualizuj reguły dynamiczne
Z przykładu poniżej dowiesz się, jak wywołać funkcję updateDynamicRules()
. Procedura dla elementu 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
});
Zaktualizuj statyczne zestawy 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 zestawów reguł statycznych. Zrobisz to, gdy liczba reguł statycznych, których potrzebujesz, przekracza dozwoloną liczbę. Aby tak się stało, niektóre z Twoich zestawów reguł powinny być zainstalowane z wyłączonymi niektórymi z nich (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. Aby je przejrzeć, otwórz w osobnym oknie reguły ustalania priorytetów.
„Priorytet”, klawisz
Te przykłady wymagają uprawnień hosta do *://*.example.com/*
.
Aby określić priorytet konkretnego adresu URL, użyj kluczy "priority"
(zdefiniowanych przez programistę), kluczy "action"
i "urlFilter"
. Podane przykłady odnoszą się do przykładowego pliku reguł widocznego pod nimi.
- Przejście na stronę https://google.com
- Ten adres URL obejmuje 2 reguły: reguły o identyfikatorach 1 i 4. Reguła o identyfikatorze 1 jest stosowana, 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. - Nawigacja do strony https://google.com/1234
- Ze względu na dłuższy adres URL reguła z identyfikatorem 2 pasuje teraz do reguł o identyfikatorach 1 i 4. Reguła o identyfikatorze 2 jest stosowana, ponieważ zasada
"allow"
ma wyższy priorytet niż"block"
i"redirect"
. - Nawigacja do strony https://google.com/12345
- Wszystkie 4 reguły pasują do tego adresu URL. Reguła o identyfikatorze 3 jest stosowana, ponieważ jej priorytet zdefiniowany przez dewelopera jest najwyższym w grupie.
[
{
"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
Ten przykład wymaga uprawnień hosta do uprawnienia *://*.example.com/*
.
Z przykładu poniżej dowiesz się, jak przekierować żądanie z domeny example.com na stronę w samym rozszerzeniu. Ścieżka rozszerzenia /a.jpg
prowadzi do: chrome-extension://EXTENSION_ID/a.jpg
, gdzie EXTENSION_ID
to identyfikator rozszerzenia. Aby to dział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"]
}
}
Poniższy kod służy do przekierowania do subdomeny example.com za pomocą klucza "transform"
. Wykorzystuje kotwicę nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z example.com. Klucz "scheme"
w zasadzie "transform"
określa, że przekierowania do subdomeny zawsze używają przedrostka „https”.
{
"id": 1,
"priority": 1,
"action": {
"type": "redirect",
"redirect": {
"transform": { "scheme": "https", "host": "new.example.com" }
}
},
"condition": {
"urlFilter": "||example.com",
"resourceTypes": ["main_frame"]
}
}
Następujący przykład pokazuje przekierowanie z https://www.abc.xyz.com/path
do https://abc.xyz.com/path
z użyciem wyrażeń regularnych. Zwróć uwagę, że w kluczu "regexFilter"
zmienia się znaczenie kropek i że grupa przechwytywania wybiera „abc” czy „def”. Klucz "regexSubstitution"
określa pierwsze zwrócone dopasowanie wyrażenia regularnego z użyciem „\1”. W tym przypadku: „abc” jest przechwytywany z przekierowanego adresu URL i umieszczany w zastąpieniu.
{
"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łówki
Poniższy przykład pokazuje usunięcie wszystkich plików cookie zarówno z ramki głównej, jak i wszystkich ramek podrzędnych.
{
"id": 1,
"priority": 1,
"action": {
"type": "modifyHeaders",
"requestHeaders": [{ "header": "cookie", "operation": "remove" }]
},
"condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}
Typy
DomainType
Wskazuje, czy żądanie jest własne czy pochodzące od innej firmy. Żądanie jest uznawane za własne, jeśli ma tę samą domenę (eTLD+1) co ramka, z której pochodzi.
Typ wyliczeniowy
"firstParty"
Żądanie sieciowe jest własne dla ramki, z której pochodzi.
"thirdParty"
Żądanie sieci jest usługą zewnętrzną względem 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 zapamiętywane w kolejnych sesjach.
-
tabUpdate
TabActionCountUpdate optional
Chrome w wersji 89 lub nowszejSzczegóły dotyczące dostosowywania liczby działań na karcie.
GetDisabledRuleIdsOptions
Właściwości
-
rulesetId
ciąg znaków
Identyfikator odpowiadający statycznemu elementowi
Ruleset
.
GetRulesFilter
Właściwości
-
ruleIds
liczba[] opcjonalnie
Jeśli określisz reguły, uwzględnione zostaną tylko reguły z pasującymi identyfikatorami.
HeaderOperation
Opisuje możliwe operacje polecenia „modifyHeaders” .
Typ wyliczeniowy
"append"
Dodaje nowy wpis dla określonego nagłówka. Tej operacji nie można wykonać na nagłówkach żądań.
"set"
Ustawia nową wartość określonego nagłówka i usuwa wszystkie istniejące nagłówki o tej samej nazwie.
"remove"
usuwa wszystkie wpisy określonego nagłówka.
IsRegexSupportedResult
Właściwości
-
isSupported
wartość logiczna
-
powód
UnsupportedRegexReason opcjonalny
Określa przyczynę, dla której wyrażenie regularne nie jest obsługiwane. Wartość podawana tylko wtedy, gdy
isSupported
ma wartość fałsz.
MatchedRule
Właściwości
-
ruleId
liczba
Identyfikator pasującej reguły.
-
rulesetId
ciąg znaków
Identyfikator
Ruleset
, do którego należy ta reguła. W przypadku reguły pochodzącej ze zbioru reguł dynamicznych wartość 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 jest nadal aktywna. W innym przypadku – 1.
-
timeStamp
liczba
Czas dopasowania reguły. Sygnatury czasowe będą odpowiadały konwencji JavaScriptu dotyczącej czasu, czyli liczby milisekund od początku epoki.
MatchedRuleInfoDebug
Właściwości
-
żądanie
Szczegółowe informacje o żądaniu, w którego przypadku reguła została dopasowana.
-
reguła
MatchedRulesFilter
Właściwości
-
minTimeStamp
liczba opcjonalnie
Jeśli jest określony, pasuje tylko do reguł po podanej sygnaturze czasowej.
-
tabId
liczba opcjonalnie
Jeśli zostanie określona, będzie pasować tylko do reguł dla danej karty. Pasuje do reguł, które nie są powiązane z żadną aktywną kartą, jeśli ustawiona jest wartość -1.
ModifyHeaderInfo
Właściwości
-
nagłówek
ciąg znaków
Nazwa nagłówka do zmodyfikowania.
-
operacja
Operacja do wykonania na nagłówku.
-
wartość
ciąg znaków opcjonalny
Nowa wartość nagłówka. Musi być określony w przypadku operacji
append
iset
.
QueryKeyValue
Właściwości
-
klucz
ciąg znaków
-
replaceOnly
Wartość logiczna opcjonalna
Chrome w wersji 94 lub nowszejJeśli ma wartość prawda, klucz zapytania jest zastępowany tylko wtedy, gdy już istnieje. W przeciwnym razie klucz jest dodawany, jeśli go nie ma. Wartość domyślna to fałsz.
-
wartość
ciąg znaków
QueryTransform
Właściwości
-
addOrReplaceParams
QueryKeyValue[] optional
Lista par klucz-wartość zapytania, które mają zostać dodane lub zastąpione.
-
removeParams
string[] opcjonalnie
Lista kluczy zapytania do usunięcia.
Redirect
Właściwości
-
extensionPath
ciąg znaków opcjonalny
Ścieżka względem katalogu rozszerzenia. Musi zaczynać się od „/”.
-
regexSubstitution
ciąg znaków opcjonalny
Wzorzec zastępowania dla reguł, które określają
regexFilter
. Pierwsze dopasowanie elementuregexFilter
w adresie URL zostanie zastąpione tym wzorcem. WregexSubstitution
do wstawiania odpowiednich grup przechwytywania można użyć cyfr po ukośniku odwrotnym (\1–\9). \0 oznacza cały pasujący tekst. -
przekształcenie
Opcjonalny URLTransform
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 określonym
regex
jest rozróżniana wielkość liter. Wartość domyślna to true (prawda). -
wyrażenie regularne
ciąg znaków
Wyrażenie regularne do sprawdzenia.
-
requireCapturing
Wartość logiczna opcjonalna
Określa, czy
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 lub nowszyUnikalny identyfikator dokumentu ramki, jeśli żądanie dotyczy ramki.
-
documentLifecycle
Opcjonalny DocumentLifecycle
Chrome 106 lub nowszyCykl życia dokumentu z ramką, jeśli to żądanie dotyczy ramki.
-
frameId
liczba
Wartość 0 oznacza, że żądanie jest realizowane w ramce głównej. wartość dodatnia wskazuje identyfikator ramki podrzędnej, w której zachodzi żądanie. Jeśli wczytany jest dokument ramki (podrzędnej) (
type
tomain_frame
lubsub_frame
),frameId
wskazuje identyfikator ramki, a nie ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie danej karty. -
frameType
Opcjonalny FrameType
Chrome 106 lub nowszyTyp ramki, jeśli żądanie dotyczy ramki.
-
inicjator
ciąg znaków opcjonalny
Źródło, w którym zainicjowano żądanie. Nie zmienia się to w przypadku przekierowań. Jeśli źródło jest nieprzezroczyste, ciąg znaków „null” .
-
method
ciąg znaków
Standardowa metoda HTTP.
-
parentDocumentId
ciąg znaków opcjonalny
Chrome 106 lub nowszyUnikalny identyfikator dokumentu nadrzędnego ramki, jeśli żądanie dotyczy ramki i ma element nadrzędny.
-
parentFrameId
liczba
Identyfikator ramki otaczającej klatkę, z której wysłano żądanie. Jeśli nie ma ramki nadrzędnej, ustaw wartość -1.
-
requestId
ciąg znaków
Identyfikator żądania. Identyfikatory żądań są unikalne w obrębie sesji przeglądarki.
-
tabId
liczba
Identyfikator karty, na której zachodzi żądanie. Jeśli żądanie nie jest związane z kartą, ustaw wartość –1.
-
typ
Typ zasobu żądania.
-
URL
ciąg znaków
Adres URL żądania.
RequestMethod
Opisuje metodę żądania HTTP żądania sieciowego.
Typ wyliczeniowy
ResourceType
Opisuje typ zasobu żądania sieciowego.
Typ wyliczeniowy
Rule
Właściwości
-
działanie
Działanie, które należy podjąć w przypadku dopasowania tej reguły.
-
stan
Warunek, który powoduje uruchomienie tej reguły.
-
id
liczba
Identyfikator jednoznacznie identyfikujący regułę. Obowiązkowy i powinien wynosić >= 1.
-
kampanii
liczba opcjonalnie
Priorytet reguły. Domyślna wartość to 1. W przypadku określenia tego parametru powinien to być >= 1.
RuleAction
Właściwości
-
Przekieruj
Przekierowanie opcjonalne
Opisuje sposób wykonywania przekierowania. Może mieć zastosowanie tylko w przypadku reguł przekierowania.
-
requestHeaders
ModifyHeaderInfo[] optional
Chrome 86 i nowszeNagłówki żądania do zmodyfikowania. Tej formuły można użyć tylko wtedy, gdy RuleActionType ma wartość „modifyHeaders”.
-
responseHeaders
ModifyHeaderInfo[] optional
Chrome 86 i nowszeNagłówki odpowiedzi, które mają być zmodyfikowane dla żądania. Tej formuły można użyć tylko wtedy, gdy RuleActionType ma wartość „modifyHeaders”.
-
typ
Typ działania do wykonania.
RuleActionType
Opisuje rodzaj działania, jakie ma być wykonywane w przypadku spełnienia określonego warunku RuleCondition.
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 reguła zezwalająca.
"upgradeScheme"
Uaktualnij schemat adresu URL żądania sieciowego do HTTPS, jeśli żądanie dotyczy protokołu http lub ftp.
"modifyHeaders"
Modyfikuj nagłówki żądania/odpowiedzi z żądania sieciowego.
"allowAllRequests"
Zezwalaj na 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 domenie, z której pochodzi, jest żądaniem należącym do użytkownika czy od firmy zewnętrznej. Jeśli go pominiesz, wszystkie żądania zostaną zaakceptowane.
-
domeny
string[] opcjonalnie
Wycofane od Chrome 101Zamiast tego użyj
initiatorDomains
Reguła będzie dopasowywać tylko żądania sieciowe pochodzące z listy
domains
. -
excludedDomains
string[] opcjonalnie
Wycofane od Chrome 101Zamiast tego użyj
excludedInitiatorDomains
Reguła nie będzie dopasowywać żądań sieciowych pochodzących z listy
excludedDomains
. -
excludedInitiatorDomains
string[] opcjonalnie
Chrome 101 i nowsze wersjeReguła nie będzie dopasowywać żądań sieciowych pochodzących z listy
excludedInitiatorDomains
. Jeśli lista jest pusta lub pominięta, żadne domeny nie zostaną wykluczone. Ma to pierwszeństwo przed zasadąinitiatorDomains
.Uwagi:
- Subdomen, takich jak „a.example.com” są dozwolone.
- Wpisy mogą się składać tylko z znaków ASCII.
- Używaj kodowania punycode w domenach umiędzynarodowionych.
- Ten identyfikator pasuje do inicjatora żądania, a nie do adresu URL żądania.
- Subdomeny wymienionych domen również są wykluczone.
-
excludedRequestDomains
string[] opcjonalnie
Chrome 101 i nowsze wersjeReguła nie będzie dopasowywać żądań sieciowych, jeśli domena odpowiada jednej z domen na liście
excludedRequestDomains
. Jeśli lista jest pusta lub pominięta, żadne domeny nie zostaną wykluczone. Ma to pierwszeństwo przed zasadąrequestDomains
.Uwagi:
- Subdomen, takich jak „a.example.com” są dozwolone.
- Wpisy mogą się składać tylko z znaków ASCII.
- Używaj kodowania punycode w domenach umiędzynarodowionych.
- Subdomeny wymienionych domen również są wykluczone.
-
excludedRequestMethods
RequestMethod[] opcjonalny
Chrome w wersji 91 lub nowszejLista metod żądań, które nie pasują do reguły. Należy określić tylko jedną z tych właściwości:
requestMethods
lubexcludedRequestMethods
. Jeśli żadna z nich nie zostanie określona, dopasowywane będą wszystkie metody żądań. -
excludedResourceTypes
ResourceType[] opcjonalny
Lista typów zasobów, które nie pasują do reguły. Należy określić tylko jedną z tych właściwości:
resourceTypes
lubexcludedResourceTypes
. Jeśli nie określono żadnego z nich, wszystkie typy zasobów oprócz „main_frame” są zablokowane. -
excludedTabIds
liczba[] opcjonalnie
Chrome w wersji 92 lub nowszejLista
tabs.Tab.id
, do których reguła nie powinna pasować. Identyfikatortabs.TAB_ID_NONE
wyklucza żądania, które nie pochodzą z karty. Obsługiwane tylko w przypadku reguł ograniczonych do sesji. -
initiatorDomains
string[] opcjonalnie
Chrome 101 i nowsze wersjeReguła będzie dopasowywać tylko żądania sieciowe pochodzące z listy
initiatorDomains
. Jeśli pominiesz listę, reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.Uwagi:
- Subdomen, takich jak „a.example.com” są dozwolone.
- Wpisy mogą się składać tylko z znaków ASCII.
- Używaj kodowania punycode w domenach umiędzynarodowionych.
- Ten identyfikator pasuje do inicjatora żądania, a nie do adresu URL żądania.
- Subdomeny wymienionych domen również są dopasowywane.
-
isUrlFilterCaseSensitive
Wartość logiczna opcjonalna
Określa, czy w polu
urlFilter
lubregexFilter
(w zależności od tego, która z nich została określona) wielkość liter ma znaczenie. Wartość domyślna to false (fałsz). -
regexFilter
ciąg znaków opcjonalny
Wyrażenie regularne pasujące do adresu URL żądania sieciowego. Ma on zgodność ze składnią RE2.
Uwaga: można określić tylko jedną z tych właściwości:
urlFilter
lubregexFilter
.Uwaga: pole
regexFilter
może się składać tylko ze znaków ASCII. Jest on porównywany z adresem URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych) a wszystkie inne znaki spoza zestawu ASCII są kodowane w formacie UTF-8. -
requestDomains
string[] opcjonalnie
Chrome 101 i nowsze wersjeReguła będzie dopasowywać żądania sieciowe tylko wtedy, gdy domena pasuje do jednej z listy
requestDomains
. Jeśli pominiesz listę, reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.Uwagi:
- Subdomen, takich jak „a.example.com” są dozwolone.
- Wpisy mogą się składać tylko z znaków ASCII.
- Używaj kodowania punycode w domenach umiędzynarodowionych.
- Subdomeny wymienionych domen również są dopasowywane.
-
requestMethods
RequestMethod[] opcjonalny
Chrome w wersji 91 lub nowszejLista metod żądań HTTP, które mogą być dopasowane do reguły. Pusta lista jest niedozwolona.
Uwaga: określenie warunku reguły
requestMethods
spowoduje też wykluczenie żądań innych niż HTTP, a określenieexcludedRequestMethods
– nie. -
resourceTypes
ResourceType[] opcjonalny
Lista typów zasobów, które reguła może pasować. Pusta lista jest niedozwolona.
Uwaga: ten atrybut musi być określony w regułach
allowAllRequests
i może zawierać wyłącznie typy zasobówsub_frame
orazmain_frame
. -
tabIds
liczba[] opcjonalnie
Chrome w wersji 92 lub nowszejLista
tabs.Tab.id
, która powinna pasować do reguły. 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 dopasowywany do adresu URL żądania sieciowego. Obsługiwane konstrukcje:
'*' : symbol wieloznaczny: dopasowuje dowolną liczbę znaków.
'|' : kotwica lewa/prawa: jeśli zostanie użyta na końcu wzorca, określa odpowiednio początek/koniec adresu URL.
'||' : kotwica nazwy domeny: jeśli jest używana na początku wzorca, określa początek (sub-)domeny adresu URL.
'^' : separator: powoduje wyszukanie wszystkiego oprócz litery, cyfry lub jednej z tych wartości:
_
,-
,.
i%
. Będą także zgodne z końcem adresu URL.Dlatego ciąg
urlFilter
składa się z tych części: (opcjonalna kotwica nazwy lewej/domeny) + wzorzec + (opcjonalna prawa kotwica).Jeśli go pominiesz, dopasowywane będą wszystkie adresy URL. Pusty ciąg jest niedozwolony.
Wzorzec zaczynający się od
||*
nie jest dozwolony. Użyj w zamian zasady*
.Uwaga: można określić tylko jedną z tych właściwości:
urlFilter
lubregexFilter
.Uwaga: pole
urlFilter
może się składać tylko ze znaków ASCII. Jest on porównywany z adresem URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych) a wszystkie inne znaki spoza zestawu ASCII są kodowane w formacie UTF-8. Jeśli na przykład URL żądania to http://abc.р➘?q=pomaga, ciągurlFilter
zostanie dopasowany do adresu URL http://abc.xn--p1ai/?q=%D1%84.
Ruleset
Właściwości
-
włączone
wartość logiczna
Określa, czy zestaw reguł jest domyślnie włączony.
-
id
ciąg znaków
Niepusty ciąg znaków jednoznacznie identyfikujący zestaw reguł. Identyfikatory rozpoczynające się od „_” są zarezerwowane do użytku wewnętrznego.
-
ścieżka
ciąg znaków
Ś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ą zwiększa się liczba działań na karcie. Wartości ujemne będą zmniejszać liczbę.
-
tabId
liczba
Karta, dla której ma zostać zaktualizowana liczba działań.
TestMatchOutcomeResult
Właściwości
-
matchedRules
Reguły (jeśli występują), które pasują do hipotetycznego żądania.
TestMatchRequestDetails
Właściwości
-
inicjator
ciąg znaków opcjonalny
Adres URL inicjatora (jeśli istnieje) hipotetycznego żądania.
-
method
Opcjonalny RequestMethod
Standardowa metoda HTTP hipotetycznego żądania. Domyślna wartość to „get”. w przypadku żądań HTTP i ignorowane w przypadku żądań innych niż HTTP.
-
tabId
liczba opcjonalnie
Identyfikator karty, w której zachodzi hipotetyczne żądanie. Nie musi odpowiadać faktycznemu identyfikatorowi karty. Wartość domyślna to -1, co oznacza, że żądanie nie jest związane z kartą.
-
typ
Typ zasobu hipotetycznego żądania.
-
URL
ciąg znaków
Adres URL hipotetycznego żądania.
UnsupportedRegexReason
Opisuje powód, dla którego dane wyrażenie regularne nie jest obsługiwane.
Typ wyliczeniowy
"syntaxError"
Wyrażenie regularne jest niepoprawne składniowo lub korzysta z funkcji niedostępnych w składni RE2.
"memoryLimitExceeded"
Wyrażenie regularne przekracza limit pamięci.
UpdateRuleOptions
Właściwości
-
addRules
Reguła[] opcjonalna
Reguły do dodania.
-
removeRuleIds
liczba[] opcjonalnie
Identyfikatory reguł do usunięcia. Nieprawidłowe identyfikatory zostaną zignorowane.
UpdateRulesetOptions
Właściwości
UpdateStaticRulesOptions
Właściwości
-
disableRuleIds
liczba[] opcjonalnie
Zestaw identyfikatorów odpowiadających regułom w elemencie
Ruleset
do wyłączenia. -
enableRuleIds
liczba[] opcjonalnie
Zestaw identyfikatorów odpowiadających regułom w:
Ruleset
do włączenia. -
rulesetId
ciąg znaków
Identyfikator odpowiadający statycznemu elementowi
Ruleset
.
URLTransform
Właściwości
-
fragment
ciąg znaków opcjonalny
Nowy fragment żądania. Powinien być pusty – w takim przypadku istniejący fragment zostanie wyczyszczony. lub powinien się zaczynać od znaku „#”.
-
host
ciąg znaków opcjonalny
Nowy host dla żądania.
-
hasło
ciąg znaków opcjonalny
Nowe hasło dla żądania.
-
ścieżka
ciąg znaków opcjonalny
Nowa ścieżka żądania. Jeśli ta wartość jest pusta, istniejąca ścieżka zostanie wyczyszczona.
-
port
ciąg znaków opcjonalny
Nowy port dla żądania. Jeśli jest pusty, istniejący port jest wyczyszczony.
-
zapytanie
ciąg znaków opcjonalny
Nowe zapytanie dla żądania. To pole powinno być puste. W takim przypadku istniejące zapytanie zostanie wyczyszczone. lub powinien zaczynać się od „?”.
-
queryTransform
Opcjonalny QueryTransform
Dodaj, usuń lub zastąp 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 prośby.
Właściwości
DYNAMIC_RULESET_ID
Identyfikator zestawu reguł dynamicznych dodanych przez rozszerzenie.
Wartość
GETMATCHEDRULES_QUOTA_INTERVAL
Przedział czasu, w którym można wykonywać połączenia MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules
, określony w minutach. Dodatkowe połączenia zostaną natychmiast zakończone niepowodzeniem i ustawionym jako runtime.lastError
. Uwaga: połączenia getMatchedRules
związane z gestem użytkownika nie są objęte limitem.
Wartość
10
GUARANTEED_MINIMUM_STATIC_RULES
Minimalna liczba reguł statycznych, które gwarantują rozszerzenie we wszystkich włączonych statycznych zestawach reguł. Wszystkie reguły powyżej tego limitu będą wliczane do globalnego limitu reguł statycznych.
Wartość
30000
MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
Liczba wywołań funkcji getMatchedRules
w okresie GETMATCHEDRULES_QUOTA_INTERVAL
wynosi
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 Rulesets
, które rozszerzenie może jednorazowo włączyć.
Wartość
50
MAX_NUMBER_OF_REGEX_RULES
Maksymalna liczba reguł wyrażeń regularnych, które może dodać rozszerzenie. Limit ten jest oceniany oddzielnie dla zbioru reguł dynamicznych i tych określonych w pliku zasobów reguł.
Wartość
1000
MAX_NUMBER_OF_SESSION_RULES
Maksymalna liczba reguł ograniczonych do sesji, które może dodać rozszerzenie.
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 treści reguł dynamicznych, które może dodawać rozszerzenie.
Wartość
5000
MAX_NUMBER_OF_UNSAFE_SESSION_RULES
Maksymalna liczba niebezpiecznych treści reguł ograniczonych do sesji, które może dodawać rozszerzenie.
Wartość
5000
SESSION_RULESET_ID
Identyfikator zestawu reguł dla reguł ograniczonych do sesji dodanych przez rozszerzenie.
Wartość
Metody
getAvailableStaticRuleCount()
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
callback?: function,
)
Zwraca liczbę reguł statycznych, które rozszerzenie może włączyć przed osiągnięciem globalnego limitu reguł statycznych.
Parametry
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(count: number) => void
.-
liczba
liczba
-
Zwroty
-
Promise<number>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getDisabledRuleIds()
chrome.declarativeNetRequest.getDisabledRuleIds(
options: GetDisabledRuleIdsOptions,
callback?: function,
)
Zwraca listę reguł statycznych w danym elemencie Ruleset
, które są obecnie wyłączone.
Parametry
-
Określa zestaw reguł, których ma dotyczyć zapytanie.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(disabledRuleIds: number[]) => void
.-
disabledRuleIds
liczba[]
-
Zwroty
-
Promise<number[]>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getDynamicRules()
chrome.declarativeNetRequest.getDynamicRules(
filter?: GetRulesFilter,
callback?: function,
)
Zwraca bieżący zestaw reguł dynamicznych dla rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę pobranych reguł, określając filter
.
Parametry
-
filtr
GetRulesFilter optional
Chrome w wersji 111 lub nowszejObiekt służący do filtrowania listy pobranych reguł.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(rules: Rule[]) => void
.-
reguły
Reguła[]
-
Zwroty
-
Promise<Rule[]>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getEnabledRulesets()
chrome.declarativeNetRequest.getEnabledRulesets(
callback?: function,
)
Zwraca identyfikatory bieżącego zestawu włączonych statycznych zestawów reguł.
Parametry
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(rulesetIds: string[]) => void
.-
rulesetIds
ciąg znaków[]
-
Zwroty
-
Promise<string[]>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getMatchedRules()
chrome.declarativeNetRequest.getMatchedRules(
filter?: MatchedRulesFilter,
callback?: function,
)
Zwraca wszystkie reguły dopasowane do rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę dopasowanych reguł, określając filter
. Ta metoda jest dostępna tylko w przypadku rozszerzeń, które mają uprawnienie "declarativeNetRequestFeedback"
lub uprawnienie "activeTab"
w przypadku elementu tabId
określonego w zasadzie filter
. Uwaga: reguły niepowiązane z aktywnym dokumentem, który został dopasowany ponad pięć minut temu, nie są zwracane.
Parametry
-
filtr
Opcjonalny MatchedRulesFilter
Obiekt służący do filtrowania listy dopasowanych reguł.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(details: RulesMatchedDetails) => void
.-
szczegóły
-
Zwroty
-
Promise<RulesMatchedDetails>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getSessionRules()
chrome.declarativeNetRequest.getSessionRules(
filter?: GetRulesFilter,
callback?: function,
)
Zwraca bieżący zestaw reguł ograniczonych do sesji dla rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę pobranych reguł, określając filter
.
Parametry
-
filtr
GetRulesFilter optional
Chrome w wersji 111 lub nowszejObiekt służący do filtrowania listy pobranych reguł.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(rules: Rule[]) => void
.-
reguły
Reguła[]
-
Zwroty
-
Promise<Rule[]>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
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 optional
Parametr
callback
wygląda tak:(result: IsRegexSupportedResult) => void
.-
wynik
-
Zwroty
-
Promise<IsRegexSupportedResult>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
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, i umożliwia jej zwiększanie.
Parametry
-
Opcje
-
wywołanie zwrotne
funkcja optional
Chrome w wersji 89 lub nowszejParametr
callback
wygląda tak:() => void
.
Zwroty
-
Promise<void>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
testMatchOutcome()
chrome.declarativeNetRequest.testMatchOutcome(
request: TestMatchRequestDetails,
callback?: function,
)
Sprawdza, czy któraś z reguł declarativeNetRequest rozszerzenia pasuje do hipotetycznego żądania. Uwaga: ta opcja jest dostępna tylko w przypadku rozszerzeń bez pakietu, ponieważ jest przeznaczona do użycia wyłącznie podczas tworzenia rozszerzeń.
Parametry
-
żądanie
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(result: TestMatchOutcomeResult) => void
.-
wynik
-
Zwroty
-
Promise<TestMatchOutcomeResult>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
updateDynamicRules()
chrome.declarativeNetRequest.updateDynamicRules(
options: UpdateRuleOptions,
callback?: function,
)
Zmienia bieżący zestaw reguł dynamicznych rozszerzenia. Reguły o identyfikatorach wymienionych w tabeli options.removeRuleIds
zostaną najpierw usunięte, a następnie zostaną dodane reguły podane w tabeli options.addRules
. Uwagi:
- Ta aktualizacja odbywa się jako jedna niepodzielna operacja: albo zostaną dodane i usunięte wszystkie określone reguły, albo zwracany jest błąd.
- Te reguły są zachowywane podczas różnych sesji przeglądarki i aktualizacji rozszerzeń.
- Reguł statycznych określonych w pakiecie rozszerzeń nie można usunąć za pomocą tej funkcji.
MAX_NUMBER_OF_DYNAMIC_RULES
to maksymalna liczba reguł dynamicznych, które może dodać rozszerzenie. Liczba niebezpiecznych reguł nie może przekraczaćMAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES
.
Parametry
-
OpcjeChrome 87 i nowsze
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
.
Zwroty
-
Promise<void>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
updateEnabledRulesets()
chrome.declarativeNetRequest.updateEnabledRulesets(
options: UpdateRulesetOptions,
callback?: function,
)
Aktualizuje zestaw włączonych statycznych zestawów reguł rozszerzenia. Najpierw usuwane są zestawy reguł o identyfikatorach wymienionych w tabeli options.disableRulesetIds
, a potem do nich dodawane są zestawy reguł wymienione w tabeli options.enableRulesetIds
.
Pamiętaj, że zestaw włączonych statycznych zestawów reguł jest zachowywany między sesjami, ale nie pomiędzy aktualizacjami rozszerzeń. Oznacza to, że klucz manifestu rule_resources
będzie określać zestaw włączonych statycznych zestawów reguł przy każdej aktualizacji rozszerzenia.
Parametry
-
OpcjeChrome 87 i nowsze
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
.
Zwroty
-
Promise<void>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
updateSessionRules()
chrome.declarativeNetRequest.updateSessionRules(
options: UpdateRuleOptions,
callback?: function,
)
Modyfikuje bieżący zestaw reguł ograniczonych do sesji dla rozszerzenia. Reguły o identyfikatorach wymienionych w tabeli options.removeRuleIds
zostaną najpierw usunięte, a następnie zostaną dodane reguły podane w tabeli options.addRules
. Uwagi:
- Ta aktualizacja odbywa się jako jedna niepodzielna operacja: albo zostaną dodane i usunięte wszystkie określone reguły, albo zostanie zwrócony błąd.
- Reguły te nie są zachowywane między sesjami i są zapisywane w pamięci.
MAX_NUMBER_OF_SESSION_RULES
to maksymalna liczba reguł sesji, które może dodać rozszerzenie.
Parametry
-
Opcje
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
.
Zwroty
-
Promise<void>
Chrome w wersji 91 lub nowszejObietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
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łączonej grupy Ruleset
zaczną obowiązywać po jej następnym włączeniu.
Parametry
-
Opcje
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
.
Zwroty
-
Promise<void>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowane jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onRuleMatchedDebug
chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
callback: function,
)
Uruchamiane, gdy reguła jest zgodna z żądaniem. Ta opcja jest dostępna tylko w przypadku rozszerzeń bez pakietu z uprawnieniami "declarativeNetRequestFeedback"
, ponieważ jest przeznaczone wyłącznie do debugowania.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(info: MatchedRuleInfoDebug) => void
.-
informacje
-