chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

Opis

Interfejs API chrome.declarativeNetRequest służy do blokowania lub modyfikowania żądań sieciowych przez określanie reguł deklaratywnych. Dzięki temu rozszerzenia mogą modyfikować żądania sieciowe bez ich przechwytywania i wyświetlania ich zawartości, co zapewnia większą prywatność.

Uprawnienia

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

Dostępność

Chrome 84 lub nowsza wersja

Plik manifestu

Oprócz uprawnień opisanych powyżej niektóre typy zestawów reguł, zwłaszcza statyczne zestawy reguł, wymagają zadeklarowania klucza manifestu "declarative_net_request", który powinien być słownikiem z jednym kluczem o nazwie "rule_resources". Ten klucz jest tablicą zawierającą słowniki typu Ruleset, jak pokazano poniżej. (Pamiętaj, że nazwa „Ruleset” nie pojawia się w pliku JSON manifestu, ponieważ jest to tylko tablica). Zestawy reguł statycznych 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 użycie

Aby używać tego interfejsu API, określ co najmniej 1 zestaw reguł. Zestaw reguł zawiera tablicę reguł. Pojedyncza reguła wykonuje jedną z tych czynności:

  • Zablokuj żądanie sieciowe.
  • Uaktualnij schemat (z http na https).
  • Zapobiegaj blokowaniu żądania przez negowanie pasujących reguł blokowania.
  • przekierowywać żądania sieciowe,
  • modyfikować nagłówki żądań lub odpowiedzi;

Istnieją 3 rodzaje zestawów reguł, którymi zarządza się w nieco inny sposób.

Dynamiczne
Są zachowywane między sesjami przeglądarki i uaktualnieniami rozszerzeń oraz zarządzane za pomocą JavaScriptu, gdy rozszerzenie jest używane.
Sesja
Dane są usuwane po zamknięciu przeglądarki i zainstalowaniu nowej wersji rozszerzenia. Regułami sesji zarządza się za pomocą JavaScriptu, gdy rozszerzenie jest używane.
Statyczny
Są pakowane, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Reguły statyczne są przechowywane w plikach reguł w formacie JSON i wymienione w pliku manifestu.

W kolejnych sekcjach szczegółowo opisujemy typy zestawów reguł.

Zestawy reguł dynamicznych i ograniczonych do sesji

Dynamicznymi zestawami reguł i zestawami reguł sesji zarządza się za pomocą JavaScriptu, gdy rozszerzenie jest używane.

  • Reguły dynamiczne są zachowywane między sesjami przeglądarki i uaktualnieniami rozszerzeń.
  • Reguły sesji są czyszczone po zamknięciu przeglądarki i zainstalowaniu nowej wersji rozszerzenia.

Istnieje tylko po jednym zbiorze reguł każdego z tych typów. Rozszerzenie może dynamicznie dodawać lub usuwać reguły, wywołując funkcje updateDynamicRules() i updateSessionRules(), o ile nie zostaną przekroczone limity reguł. Informacje o limitach reguł znajdziesz w artykule Limity reguł. Przykład znajdziesz w sekcji Przykłady kodu.

Statyczne zestawy reguł

W przeciwieństwie do reguł dynamicznych i reguł 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ą wskazywane rozszerzeniu 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ł, identyfikator zestawu reguł zawartego w pliku oraz informację o tym, czy zestaw reguł jest włączony czy wyłączony. Dwa ostatnie są ważne, gdy włączasz lub wyłączasz zestaw reguł automatycznie.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Aby przetestować pliki reguł, załadować rozpakowane rozszerzenie. Błędy i ostrzeżenia dotyczące nieprawidłowych reguł statycznych są wyświetlane tylko w przypadku rozpakowanych rozszerzeń. Nieprawidłowe reguły statyczne w spakowanych rozszerzeniach są ignorowane.

Włączanie i wyłączanie reguł statycznych oraz zestawów reguł

Zarówno poszczególne reguły statyczne, jak i całe zestawy reguł statycznych można włączać i wyłączać w czasie działania.

Zestaw włączonych reguł statycznych i zbiorów reguł jest zachowywany między sesjami przeglądarki. Żadne z nich nie są zachowywane po aktualizacji rozszerzenia, co oznacza, że po aktualizacji dostępne są tylko reguły, które zdecydujesz się pozostawić w plikach reguł.

Ze względu na wydajność obowiązują też ograniczenia dotyczące liczby reguł i zestawów reguł, które mogą być włączone jednocześnie. Zadzwoń pod numer getAvailableStaticRuleCount(), aby sprawdzić liczbę dodatkowych reguł, które mogą być włączone. 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 są definiowane za pomocą klucza "id" słownika Ruleset.

Aby włączyć lub wyłączyć statyczne zestawy reguł, wywołaj updateEnabledRulesets(). Ta metoda przyjmuje obiekt UpdateRulesetOptions, który zawiera tablice identyfikatorów zestawów reguł do włączenia lub wyłączenia. Identyfikatory są definiowane za pomocą klucza "id" słownika Ruleset.

Reguły kompilacji

Niezależnie od typu reguła zaczyna się od 4 pól, jak pokazano poniżej. Klucze "id" i "priority" przyjmują liczbę, natomiast klucze "action" i "condition" mogą zawierać kilka warunków blokowania i przekierowywania. Ta reguła blokuje wszystkie żądania skryptów pochodzące z "foo.com" do dowolnego adresu URL z "abc" jako podłańcuchem.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

Znaki dopasowania urlFilter

Klucz "condition" reguły umożliwia użycie klucza "urlFilter" do wykonywania działań na adresach URL w określonej domenie. Wzorce tworzy się za pomocą tokenów dopasowania do wzorca. Poniżej znajdziesz kilka przykładów.

urlFilter Dopasowania 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

Priorytetyzacja reguł

Reguły są aktywowane przez żądania wysyłane ze stron internetowych. Jeśli do danego żądania pasuje kilka reguł, należy określić ich priorytety. W tej sekcji wyjaśniamy, jak ustalane są priorytety. Ustalanie priorytetów odbywa się w 2 etapach.

  1. Priorytet jest określany dla reguł w rozszerzeniu.
  2. Jeśli więcej niż jedno rozszerzenie może zastosować regułę do żądania, priorytet jest określany dla wszystkich rozszerzeń, które pasują do danego żądania.

Dopasowywanie działa w ten sposób: reguła, która ma najwyższy priorytet w danym rozszerzeniu, będzie miała wyższy priorytet niż reguły z innych rozszerzeń.

Priorytetyzacja reguł w rozszerzeniu

W ramach jednego rozszerzenia priorytety są ustalane w ten sposób:

  1. Zwracana jest reguła o najwyższym priorytecie zdefiniowanym przez dewelopera (czyli pole "priority").

  2. Jeśli istnieje więcej niż 1 reguła o najwyższym priorytecie zdefiniowanym przez dewelopera, reguły są traktowane priorytetowo według pola "action" w tej kolejności:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Jeśli typ działania to nie block ani redirect, oceniane są wszystkie pasujące reguły modifyHeaders. Pamiętaj, że jeśli istnieją reguły o priorytecie zdefiniowanym przez dewelopera, który jest niższy niż priorytet określony dla allow i allowAllRequests, takie reguły są ignorowane.

  4. Jeśli ten sam nagłówek jest modyfikowany przez kilka reguł, modyfikacja jest określana przez zdefiniowane przez dewelopera pole "priority" i określone operacje.

    • Jeśli reguła dodaje wartość do nagłówka, reguły o niższym priorytecie mogą tylko dodawać wartość do tego nagłówka. Operacje ustawiania i usuwania są niedozwolone.
    • Jeśli reguła ustawia nagłówek, reguły o niższym priorytecie mogą tylko dołączać do tego nagłówka. Żadne inne modyfikacje nie są dozwolone.
    • Jeśli reguła usuwa nagłówek, reguły o niższym priorytecie nie mogą go dalej modyfikować.

Priorytetyzacja reguł między rozszerzeniami

Jeśli tylko jedno rozszerzenie ma regułę pasującą do żądania, ta reguła zostanie zastosowana. Jeśli jednak do żądania pasuje więcej niż 1 rozszerzenie, stosowany jest ten proces:

  1. Priorytety reguł są ustalane za pomocą pola "action" w tej kolejności:

    1. block
    2. redirect lub upgradeScheme
    3. allow lub allowAllRequests

  2. 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 obciążeniem, dlatego podczas korzystania z interfejsu API 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. Rozszerzenie może określać maksymalnie 50 statycznych zestawów reguł w ramach klucza manifestu "rule_resources", ale jednocześnie może być włączonych tylko 10 z nich. Ten drugi to MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Łącznie te zestawy reguł gwarantują co najmniej 30 000 reguł. Jest to GUARANTEED_MINIMUM_STATIC_RULES.

Liczba reguł dostępnych po tym czasie zależy od tego, ile reguł jest włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Możesz znaleźć ten numer w czasie działania, wywołując getAvailableStaticRuleCount(). Przykład znajdziesz w sekcji Przykłady kodu.

Reguły dynamiczne i reguły dotyczące sesji

Limity stosowane do reguł dynamicznych i reguł sesji są prostsze niż w przypadku reguł statycznych. Łączna liczba obu tych elementów nie może przekraczać 5000. Jest to MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

Reguły, które używają wyrażeń regularnych

Wyrażeń regularnych można używać we wszystkich typach reguł, ale łączna liczba reguł z wyrażeniami regularnymi każdego typu nie może przekraczać 1000. Jest to limit MAX_NUMBER_OF_REGEX_RULES.

Dodatkowo każda reguła po skompilowaniu musi mieć mniej niż 2 KB. Jest to w przybliżeniu skorelowane 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 pracownikami obsługi

Interfejs declarativeNetRequest dotyczy tylko żądań, które docierają do stosu sieciowego. Obejmuje to odpowiedzi z pamięci podręcznej HTTP, ale może nie obejmować odpowiedzi, które przechodzą przez moduł obsługi onfetch skryptu service worker. declarativeNetRequest nie będzie mieć wpływu na odpowiedzi generowane przez skrypt service worker ani pobierane z CacheStorage, ale będzie mieć wpływ na wywołania fetch() wykonywane w skrypcie service worker.

Zasoby dostępne w internecie

Reguła declarativeNetRequest nie może przekierowywać z żądania zasobu publicznego do zasobu, który nie jest dostępny w internecie. Spowoduje to błąd. Dzieje się tak nawet wtedy, gdy określony zasób dostępny w internecie należy do rozszerzenia przekierowującego. Aby zadeklarować zasoby dla declarativeNetRequest, użyj tablicy "web_accessible_resources" w pliku manifestu.

Przykłady

Przykłady kodu

Aktualizowanie reguł dynamicznych

Poniższy przykład pokazuje, jak wywołać updateDynamicRules(). Procedura dla 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ł, biorąc pod uwagę liczbę dostępnych i maksymalną liczbę włączonych statycznych zestawów reguł. Możesz to zrobić, gdy liczba potrzebnych reguł statycznych przekracza dozwoloną liczbę. Aby to działało, niektóre zestawy reguł powinny być zainstalowane z wyłączonymi niektórymi zestawami reguł (ustawienie "Enabled" na false w pliku manifestu).

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ł

Przykłady poniżej pokazują, jak Chrome ustala priorytety reguł w rozszerzeniu. Podczas sprawdzania reguł możesz otworzyć reguły ustalania priorytetów w osobnym oknie.

Klucz „priority”

Te przykłady wymagają uprawnień hosta do *://*.example.com/*.

Aby określić priorytet konkretnego adresu URL, sprawdź klucze "priority" (zdefiniowany przez dewelopera), "action" i "urlFilter". Te przykłady odnoszą się do przykładowego pliku reguł pokazanego poniżej.

Nawigacja do https://google.com
Ten adres URL jest objęty 2 regułami: o identyfikatorach 1 i 4. Zastosowana zostanie 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.
Przejście na stronę https://google.com/1234
Ze względu na dłuższy adres URL reguła o identyfikatorze 2 jest teraz dopasowywana oprócz reguł o identyfikatorach 1 i 4. Zastosowana zostanie reguła o identyfikatorze 2, ponieważ "allow" ma wyższy priorytet niż "block" i "redirect".
Nawigacja do https://google.com/12345
Wszystkie 4 reguły pasują do tego adresu URL. Zastosowana zostanie reguła o identyfikatorze 3, ponieważ ma najwyższy priorytet w grupie zdefiniowany przez dewelopera.
[
  {
    "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 do *://*.example.com/*.

Z przykładu poniżej dowiesz się, jak przekierować żądanie z example.com na stronę w samym rozszerzeniu. Ścieżka rozszerzenia /a.jpg jest rozpoznawana jako chrome-extension://EXTENSION_ID/a.jpg, gdzie EXTENSION_ID to identyfikator rozszerzenia. Aby to działało, plik manifestu powinien deklarować /a.jpg jako zasób dostępny w internecie.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "https://www.example.com",
    "resourceTypes": ["main_frame"]
  }
}

W tym przykładzie użyto klucza "transform" do przekierowania do subdomeny example.com. Używa on kotwicy nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z example.com. Klucz "scheme" w "transform" określa, że przekierowania do subdomeny będą zawsze używać protokołu „https”.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com",
    "resourceTypes": ["main_frame"]
  }
}

W przykładzie poniżej użyto wyrażeń regularnych do przekierowania z https://www.abc.xyz.com/path na https://abc.xyz.com/path. W kluczu "regexFilter" zwróć uwagę na to, jak kropki są poprzedzone znakiem zmiany znaczenia i że grupa przechwytywania wybiera „abc” lub „def”. Klucz "regexSubstitution" określa pierwsze zwrócone dopasowanie wyrażenia regularnego za pomocą „\1”. W tym przypadku „abc” jest pobierane z przekierowanego adresu URL i umieszczane w podstawieniu.

{
  "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

W przykładzie poniżej usuwane są 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 jest własne czy zewnętrzne w stosunku do ramki, w której zostało wygenerowane. Żądanie jest uznawane za żądanie własne, jeśli ma tę samą domenę (eTLD+1) co ramka, w której zostało wygenerowane.

Typ wyliczeniowy

"firstParty"
Żądanie sieciowe jest własne w ramce, w której zostało wygenerowane.

"thirdParty"
Żądanie sieciowe pochodzi z ramki innej firmy.

ExtensionActionOptions

Chrome 88 lub nowsza wersja

Właściwości

  • displayActionCountAsBadgeText

    boolean opcjonalne

    Określa, czy liczba działań na stronie ma być automatycznie wyświetlana jako tekst plakietki rozszerzenia. To ustawienie jest zachowywane między sesjami.

  • tabUpdate

    TabActionCountUpdate opcjonalny

    Chrome 89 lub nowsza wersja

    Szczegóły dotyczące sposobu dostosowania liczby działań na karcie.

GetDisabledRuleIdsOptions

Chrome 111 lub nowsza wersja

Właściwości

  • rulesetId

    tekst

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

GetRulesFilter

Chrome 111 lub nowsza wersja

Właściwości

  • ruleIds

    number[] opcjonalny

    Jeśli podasz tę wartość, uwzględniane będą tylko reguły o zgodnych identyfikatorach.

HeaderInfo

Chrome 128 lub nowsza wersja

Właściwości

  • excludedValues

    string[] opcjonalne

    Jeśli ten warunek jest określony, nie zostanie dopasowany, gdy nagłówek istnieje, ale jego wartość zawiera co najmniej 1 element z tej listy. Używa tej samej składni wzorca dopasowania co values.

  • nagłówek

    tekst

    Nazwa nagłówka. Ten warunek dopasowuje nazwę tylko wtedy, gdy nie określono ani values, ani excludedValues.

  • wartości

    string[] opcjonalne

    Jeśli ten warunek jest określony, jest spełniony, gdy wartość nagłówka pasuje do co najmniej jednego wzorca na tej liście. Obsługuje dopasowywanie wartości nagłówka, w którym wielkość liter nie jest rozróżniana, oraz te konstrukcje:

    '*' : odpowiada dowolnej liczbie znaków.

    '?' : odpowiada 0 lub 1 znakowi.

    Znaki „*” i „?” można poprzedzić ukośnikiem lewym, np. „\*” i „\?”.

HeaderOperation

Chrome 86 lub nowsza wersja

Opisuje możliwe operacje dla reguły „modifyHeaders”.

Typ wyliczeniowy

"append"
Dodaje nowy wpis dla określonego nagłówka. Podczas modyfikowania nagłówków żądania ta operacja jest obsługiwana tylko w przypadku określonych nagłówków.

"set"
Ustawia nową wartość określonego nagłówka, usuwając wszystkie istniejące nagłówki o tej samej nazwie.

"remove"
Usuwa wszystkie wpisy dla określonego nagłówka.

IsRegexSupportedResult

Chrome 87 lub nowsza wersja

Właściwości

  • isSupported

    wartość logiczna

  • reason

    UnsupportedRegexReason opcjonalny

    Określa, dlaczego wyrażenie regularne nie jest obsługiwane. Podawane tylko wtedy, gdy parametr isSupported ma wartość false.

MatchedRule

Właściwości

  • ruleId

    liczba

    Identyfikator reguły dopasowania.

  • rulesetId

    tekst

    Identyfikator Ruleset, do którego należy ta reguła. W przypadku reguły pochodzącej z zestawu reguł dynamicznych będzie to DYNAMIC_RULESET_ID.

MatchedRuleInfo

Właściwości

  • reguła

    MatchedRule

  • tabId

    liczba

    Identyfikator tabId karty, z której pochodzi żądanie, jeśli karta jest nadal aktywna. W przeciwnym razie – -1.

  • timeStamp

    liczba

    Czas dopasowania reguły. Sygnatury czasowe będą zgodne z konwencją JavaScriptu dotyczącą czasu, czyli będą liczbą milisekund od początku epoki.

MatchedRuleInfoDebug

Właściwości

MatchedRulesFilter

Właściwości

  • minTimeStamp

    number optional

    Jeśli została określona, dopasowuje tylko reguły po podanej sygnaturze czasowej.

  • tabId

    number optional

    Jeśli jest określona, dopasowuje tylko reguły dla danej karty. Jeśli ustawiono wartość -1, dopasowuje reguły, które nie są powiązane z żadną aktywną kartą.

ModifyHeaderInfo

Chrome 86 lub nowsza wersja

Właściwości

  • nagłówek

    tekst

    Nazwa nagłówka, który ma zostać zmodyfikowany.

  • operacja

    HeaderOperation

    Operacja, która ma zostać wykonana na nagłówku.

  • wartość

    ciąg znaków opcjonalny

    Nowa wartość nagłówka. Musisz go określić w przypadku operacji append i set.

QueryKeyValue

Właściwości

  • klucz

    tekst

  • replaceOnly

    boolean opcjonalne

    Chrome 94 lub nowsza wersja

    Jeśli ma wartość „true”, klucz zapytania jest zastępowany tylko wtedy, gdy już istnieje. W przeciwnym razie klucz zostanie dodany, jeśli go brakuje. Wartość domyślna to fałsz.

  • wartość

    tekst

QueryTransform

Właściwości

  • addOrReplaceParams

    QueryKeyValue[] opcjonalny

    Lista par klucz-wartość zapytania, które mają zostać dodane lub zastąpione.

  • removeParams

    string[] opcjonalne

    Lista kluczy zapytań do usunięcia.

Redirect

Właściwości

  • extensionPath

    ciąg znaków opcjonalny

    Ścieżka względna do katalogu rozszerzenia. Powinna zaczynać się od „/”.

  • regexSubstitution

    ciąg znaków opcjonalny

    Wzorzec zastępowania dla reguł, które określają regexFilter. Pierwsze dopasowanie regexFilter w adresie URL zostanie zastąpione tym wzorcem. W parametrze regexSubstitution można używać cyfr poprzedzonych ukośnikiem lewym (\1–\9), aby wstawiać odpowiednie grupy przechwytywania. \0 odnosi się do całego pasującego tekstu.

  • przekształcenie

    URLTransform opcjonalny

    Przekształcenia adresów URL do wykonania.

  • URL

    ciąg znaków opcjonalny

    Adres URL przekierowania. Przekierowania do adresów URL JavaScriptu są niedozwolone.

RegexOptions

Chrome 87 lub nowsza wersja

Właściwości

  • isCaseSensitive

    boolean opcjonalne

    Określa, czy w przypadku podanej wartości regex ma być uwzględniana wielkość liter. Wartość domyślna to true.

  • wyrażenie regularne

    tekst

    Wyrażenie regularne do sprawdzenia.

  • requireCapturing

    boolean opcjonalne

    Określa, czy podany parametr regex wymaga przechwytywania. Przechwytywanie jest wymagane tylko w przypadku reguł przekierowania, które określają działanie regexSubstition. Wartość domyślna to fałsz (false).

RequestDetails

Właściwości

  • documentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowsza wersja

    Unikalny identyfikator dokumentu ramki, jeśli żądanie dotyczy ramki.

  • documentLifecycle

    DocumentLifecycle opcjonalny

    Chrome 106 lub nowsza wersja

    Cykl życia dokumentu ramki, jeśli żądanie dotyczy ramki.

  • frameId

    liczba

    Wartość 0 oznacza, że żądanie występuje w ramce głównej, a wartość dodatnia wskazuje identyfikator ramki podrzędnej, w której występuje żądanie. Jeśli dokument (pod)ramki jest wczytany (type to main_frame lub sub_frame), frameId wskazuje identyfikator tej ramki, a nie identyfikator ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

  • frameType

    FrameType opcjonalny

    Chrome 106 lub nowsza wersja

    Typ ramki, jeśli żądanie dotyczy ramki.

  • inicjator

    ciąg znaków opcjonalny

    Źródło, z którego zainicjowano żądanie. Nie zmienia się on w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, używany jest ciąg tekstowy „null”.

  • method

    tekst

    Standardowa metoda HTTP.

  • parentDocumentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowsza wersja

    Unikalny identyfikator dokumentu nadrzędnego ramki, jeśli żądanie dotyczy ramki i ma element nadrzędny.

  • parentFrameId

    liczba

    Identyfikator ramki, która zawiera ramkę wysyłającą żądanie. Jeśli nie ma ramki nadrzędnej, ustaw wartość -1.

  • requestId

    tekst

    Identyfikator żądania. Identyfikatory żądań są unikalne w ramach sesji przeglądarki.

  • tabId

    liczba

    Identyfikator karty, na której występuje żądanie. Jeśli żądanie nie jest powiązane z kartą, ustaw wartość -1.

  • Typ zasobu żądania.

  • URL

    tekst

    Adres URL żądania.

RequestMethod

Chrome 91 lub nowsza wersja

Opisuje metodę żądania HTTP żądania sieciowego.

Typ wyliczeniowy

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Opisuje typ zasobu żądania sieciowego.

Typ wyliczeniowy

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Właściwości

  • działanie

    RuleAction

    Działanie, które należy podjąć, jeśli ta reguła zostanie dopasowana.

  • warunek

    RuleCondition

    Warunek, który powoduje uruchomienie tej reguły.

  • id

    liczba

    Identyfikator, który jednoznacznie identyfikuje regułę. Obowiązkowa i powinna być większa lub równa 1.

  • kampanii

    number optional

    Priorytet reguły. Domyślna wartość to 1. Jeśli jest określona, powinna być większa lub równa 1.

RuleAction

Właściwości

  • Przekieruj

    Redirect opcjonalny

    Opisuje, jak powinno zostać wykonane przekierowanie. Dotyczy tylko reguł przekierowania.

  • requestHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 lub nowsza wersja

    Nagłówki żądania, które mają zostać zmodyfikowane. Ma zastosowanie tylko wtedy, gdy RuleActionType to „modifyHeaders”.

  • responseHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 lub nowsza wersja

    Nagłówki odpowiedzi do zmodyfikowania w żądaniu. Ma zastosowanie tylko wtedy, gdy RuleActionType to „modifyHeaders”.

  • Typ działania, które ma zostać wykonane.

RuleActionType

Opisuje rodzaj działania, które należy podjąć, jeśli dany warunek RuleCondition jest spełniony.

Typ wyliczeniowy

"block"
Blokuje żądanie sieciowe.

"redirect"
Przekieruj żądanie sieciowe.

"allow"
Zezwalaj na żądanie sieciowe. Żądanie nie zostanie przechwycone, jeśli istnieje pasująca do niego reguła zezwalania.

"upgradeScheme"
Zmień schemat adresu URL żądania sieciowego na https, jeśli żądanie jest typu http lub ftp.

"modifyHeaders"
Modyfikowanie nagłówków żądania/odpowiedzi z żądania sieciowego.

"allowAllRequests"
Zezwalaj na wszystkie żądania w hierarchii ramek, w tym na żądanie ramki.

RuleCondition

Właściwości

  • domainType

    DomainType opcjonalny

    Określa, czy żądanie sieciowe jest własne czy pochodzi od innej firmy w domenie, z której zostało wysłane. Jeśli zostanie pominięty, wszystkie prośby zostaną zaakceptowane.

  • domeny

    string[] opcjonalne

    Wycofane od wersji Chrome 101

    Użyj w zamian initiatorDomains

    Reguła będzie pasować tylko do żądań sieciowych pochodzących z listy domains.

  • excludedDomains

    string[] opcjonalne

    Wycofane od wersji Chrome 101

    Użyj w zamian excludedInitiatorDomains

    Reguła nie będzie dopasowywać żądań sieciowych pochodzących z listy excludedDomains.

  • excludedInitiatorDomains

    string[] opcjonalne

    Chrome 101 lub nowsza wersja

    Reguła nie będzie dopasowywać żądań sieciowych pochodzących z listy excludedInitiatorDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ta zasada ma pierwszeństwo przed zasadą initiatorDomains.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Dopasowanie dotyczy inicjatora żądania, a nie adresu URL żądania.
    • Subdomeny wymienionych domen również są wykluczone.
  • excludedRequestDomains

    string[] opcjonalne

    Chrome 101 lub nowsza wersja

    Reguła nie będzie dopasowywać żądań sieciowych, gdy domeny będą zgodne z domenami z listy excludedRequestDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ta zasada ma pierwszeństwo przed zasadą requestDomains.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Subdomeny wymienionych domen również są wykluczone.
  • excludedRequestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowsza wersja

    Lista metod żądania, do których reguła nie będzie pasować. Należy określić tylko jedną z tych właściwości: requestMethods lub excludedRequestMethods. Jeśli nie podasz żadnej z tych wartości, dopasowywane będą wszystkie metody żądania.

  • 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 właściwości: resourceTypes lub excludedResourceTypes. Jeśli nie podano żadnego z nich, blokowane są wszystkie typy zasobów oprócz „main_frame”.

  • excludedResponseHeaders

    HeaderInfo[] opcjonalny

    Chrome 128 lub nowsza wersja

    Reguła nie pasuje, jeśli żądanie pasuje do dowolnego warunku nagłówka odpowiedzi na tej liście (jeśli został określony). Jeśli określono zarówno właściwość excludedResponseHeaders, jak i responseHeaders, pierwszeństwo ma właściwość excludedResponseHeaders.

  • excludedTabIds

    number[] opcjonalny

    Chrome 92 lub nowsza wersja

    Lista tabs.Tab.id, do których reguła nie powinna pasować. Identyfikator tabs.TAB_ID_NONE wyklucza żądania, które nie pochodzą z karty. Obsługiwane tylko w przypadku reguł ograniczonych do sesji.

  • excludedTopDomains

    string[] opcjonalne

    Chrome 145 lub nowsza wersja

    Reguła nie będzie dopasowywać żądań sieciowych, gdy domena powiązanej ramki najwyższego poziomu będzie zgodna z domeną z listy excludedTopDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ta zasada ma pierwszeństwo przed zasadą topDomains.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Subdomeny wymienionych domen również są wykluczone.
    • W przypadku żądań bez powiązanej ramki najwyższego poziomu (np. żądań inicjowanych przez ServiceWorker) brana jest pod uwagę domena inicjatora żądania.
  • initiatorDomains

    string[] opcjonalne

    Chrome 101 lub nowsza wersja

    Reguła będzie pasować tylko do żądań sieciowych pochodzących z listy initiatorDomains. Jeśli lista zostanie pominięta, reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Dopasowanie dotyczy inicjatora żądania, a nie adresu URL żądania.
    • Subdomeny wymienionych domen również są dopasowywane.
  • isUrlFilterCaseSensitive

    boolean opcjonalne

    Określa, czy w urlFilter lub regexFilter (w zależności od tego, co zostało określone) jest rozróżniana wielkość liter. Wartość domyślna to false (fałsz).

  • regexFilter

    ciąg znaków opcjonalny

    Wyrażenie regularne, które ma być dopasowane do adresu URL żądania sieciowego. Używana jest składnia RE2.

    Uwaga: można użyć tylko opcji urlFilter lub regexFilter.

    Uwaga: regexFilter musi składać się wyłącznie ze znaków ASCII. Jest on dopasowywany do adresu URL, w którym host jest zakodowany w formacie punycode (w przypadku domen międzynarodowych), a wszystkie inne znaki spoza zestawu ASCII są zakodowane w formacie UTF-8.

  • requestDomains

    string[] opcjonalne

    Chrome 101 lub nowsza wersja

    Reguła będzie dopasowywać żądania sieciowe tylko wtedy, gdy domena będzie zgodna z domeną z listy requestDomains. Jeśli lista zostanie pominięta, reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Subdomeny wymienionych domen również są dopasowywane.
  • requestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowsza wersja

    Lista metod żądań HTTP, które mogą pasować do reguły. Pusta lista jest niedozwolona.

    Uwaga: określenie warunku reguły requestMethods spowoduje też wykluczenie żądań innych niż HTTP(S), natomiast określenie excludedRequestMethods nie spowoduje takiego wykluczenia.

  • resourceTypes

    ResourceType[] opcjonalny

    Lista typów zasobów, do których może pasować reguła. Pusta lista jest niedozwolona.

    Uwaga: należy to określić w przypadku reguł allowAllRequests. Może to obejmować tylko typy zasobów sub_frame i main_frame.

  • responseHeaders

    HeaderInfo[] opcjonalny

    Chrome 128 lub nowsza wersja

    Reguła jest dopasowywana, jeśli żądanie pasuje do dowolnego warunku nagłówka odpowiedzi na tej liście (jeśli został określony).

  • tabIds

    number[] opcjonalny

    Chrome 92 lub nowsza wersja

    Lista tabs.Tab.id, do których powinna pasować reguła. Identyfikator tabs.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.

  • topDomains

    string[] opcjonalne

    Chrome 145 lub nowsza wersja

    Reguła będzie dopasowywać tylko żądania sieciowe, gdy domena powiązanej ramki najwyższego poziomu będzie zgodna z domeną z listy topDomains. Jeśli lista zostanie pominięta, reguła będzie stosowana do żądań powiązanych ze wszystkimi domenami ramek najwyższego poziomu. Pusta lista jest niedozwolona.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Subdomeny wymienionych domen również są dopasowywane.
    • W przypadku żądań bez powiązanej ramki najwyższego poziomu (np. żądań inicjowanych przez ServiceWorker) brana jest pod uwagę domena inicjatora żądania.
  • urlFilter

    ciąg znaków opcjonalny

    Wzorzec, który jest dopasowywany do adresu URL żądania sieciowego. Obsługiwane konstrukcje:

    '*': symbol wieloznaczny, który odpowiada dowolnej liczbie znaków.

    '|': kotwica po lewej/prawej stronie – jeśli jest używana na końcu wzorca, określa odpowiednio początek lub koniec adresu URL.

    '||': kotwica nazwy domeny. Jeśli jest używana na początku wzorca, określa początek (sub)domeny adresu URL.

    '^' : separator: pasuje do wszystkiego oprócz liter, cyfr i tych znaków: _, -, ., %. Dopasowuje też koniec adresu URL.

    Dlatego urlFilter składa się z tych części: (opcjonalna kotwica po lewej stronie / kotwica nazwy domeny) + wzorzec + (opcjonalna kotwica po prawej stronie).

    Jeśli pominiesz tę wartość, dopasowywane będą wszystkie adresy URL. Pusty ciąg znaków jest niedozwolony.

    Wzorzec zaczynający się od ||* jest niedozwolony. Użyj w zamian zasady *.

    Uwaga: można użyć tylko opcji urlFilter lub regexFilter.

    Uwaga: urlFilter musi składać się wyłącznie ze znaków ASCII. Jest on dopasowywany do adresu URL, w którym host jest zakodowany w formacie punycode (w przypadku domen międzynarodowych), a wszystkie inne znaki spoza zestawu ASCII są zakodowane w formacie UTF-8. Jeśli na przykład adres URL żądania to http://abc.рф?q=ф, urlFilter zostanie dopasowany do adresu URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145 lub nowsza wersja

Typ wyliczeniowy

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Właściwości

  • aktywne

    wartość logiczna

    Określa, czy zestaw reguł jest domyślnie włączony.

  • id

    tekst

    Niepusty ciąg znaków, który jednoznacznie identyfikuje zestaw reguł. Identyfikatory zaczynające się od „_” są zarezerwowane do użytku wewnętrznego.

  • ścieżka

    tekst

    Ścieżka do zestawu reguł JSON względem katalogu rozszerzenia.

RulesMatchedDetails

Właściwości

TabActionCountUpdate

Chrome 89 lub nowsza wersja

Właściwości

  • Zwiększ

    liczba

    Wartość, o którą ma zostać zwiększona liczba działań na karcie. Wartości ujemne zmniejszają liczbę.

  • tabId

    liczba

    Karta, na której chcesz zaktualizować liczbę działań.

TestMatchOutcomeResult

Chrome 103 lub nowsza wersja

Właściwości

  • matchedRules

    MatchedRule[]

    Reguły (jeśli istnieją), które pasują do hipotetycznego żądania.

TestMatchRequestDetails

Chrome 103 lub nowsza wersja

Właściwości

  • inicjator

    ciąg znaków opcjonalny

    Adres URL inicjatora (jeśli istnieje) hipotetycznego żądania.

  • method

    RequestMethod opcjonalny

    Standardowa metoda HTTP hipotetycznego żądania. W przypadku żądań HTTP domyślnie jest to „get”, a w przypadku żądań innych niż HTTP jest ignorowane.

  • responseHeaders

    object opcjonalny

    Chrome 129 lub nowsza wersja

    Nagłówki podane w hipotetycznej odpowiedzi, jeśli żądanie nie zostanie zablokowane ani przekierowane przed wysłaniem. Jest reprezentowany jako obiekt, który mapuje nazwę nagłówka na listę wartości ciągu znaków. Jeśli nie zostanie określony, hipotetyczna odpowiedź zwróci puste nagłówki odpowiedzi, które mogą pasować do reguł pasujących do braku nagłówków. Na przykład: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number optional

    Identyfikator karty, na której ma miejsce hipotetyczne żądanie. Nie musi odpowiadać rzeczywistemu identyfikatorowi karty. Wartość domyślna to -1, co oznacza, że żądanie nie jest powiązane z kartą.

  • topUrl

    ciąg znaków opcjonalny

    Chrome 145 lub nowsza wersja

    Powiązany adres URL ramki najwyższego poziomu (jeśli istnieje) dla żądania.

  • Typ zasobu hipotetycznego żądania.

  • URL

    tekst

    Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome 87 lub nowsza wersja

Opisuje, dlaczego dane wyrażenie regularne nie jest obsługiwane.

Typ wyliczeniowy

"syntaxError"
Wyrażenie regularne jest nieprawidłowe pod względem składni lub używa funkcji niedostępnych w składni RE2.

"memoryLimitExceeded"
Wyrażenie regularne przekracza limit pamięci.

UpdateRuleOptions

Chrome 87 lub nowsza wersja

Właściwości

  • addRules

    Rule[] opcjonalne

    Reguły do dodania.

  • removeRuleIds

    number[] opcjonalny

    Identyfikatory reguł do usunięcia. Wszystkie nieprawidłowe identyfikatory zostaną zignorowane.

UpdateRulesetOptions

Chrome 87 lub nowsza wersja

Właściwości

  • disableRulesetIds

    string[] opcjonalne

    Zbiór identyfikatorów odpowiadających statycznemu elementowi Ruleset, który powinien zostać wyłączony.

  • enableRulesetIds

    string[] opcjonalne

    Zbiór identyfikatorów odpowiadających statycznemu zasobowi Ruleset, który powinien być włączony.

UpdateStaticRulesOptions

Chrome 111 lub nowsza wersja

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

    Zbiór identyfikatorów odpowiadających regułom w Ruleset, które mają zostać włączone.

  • rulesetId

    tekst

    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 zaczynać się od znaku „#”.

  • host

    ciąg znaków opcjonalny

    Nowy host żą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 pole jest puste, dotychczasowa ścieżka zostanie wyczyszczona.

  • port

    ciąg znaków opcjonalny

    Nowy port dla żądania. Jeśli pole jest puste, istniejący port zostanie wyczyszczony.

  • zapytanie

    ciąg znaków opcjonalny

    Nowe zapytanie dla żądania. Może być puste (w takim przypadku istniejące zapytanie zostanie wyczyszczone) lub zaczynać się od znaku „?”.

  • queryTransform

    QueryTransform opcjonalny

    Dodawanie, usuwanie i zastępowanie par 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 którym można wykonać MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules połączeń, podany w minutach. Dodatkowe wywołania natychmiast zakończą się niepowodzeniem i ustawią runtime.lastError. Uwaga: wywołania getMatchedRules powiązane z gestem użytkownika nie są objęte limitem.

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 lub nowsza wersja

Minimalna liczba reguł statycznych gwarantowanych dla rozszerzenia 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.

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

Chrome 94 lub nowsza wersja

Maksymalna liczba statycznych reguł Rulesets, które rozszerzenie może włączyć jednocześnie.

Wartość

50

MAX_NUMBER_OF_REGEX_RULES

Maksymalna liczba reguł wyrażeń regularnych, które może dodać rozszerzenie. Ten limit jest oceniany oddzielnie dla zestawu reguł dynamicznych i reguł określonych w pliku zasobów reguł.

Wartość

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 lub nowsza wersja

Maksymalna liczba reguł o zakresie sesji, które może dodać rozszerzenie.

Wartość

5000

MAX_NUMBER_OF_STATIC_RULESETS

Maksymalna liczba statycznych Rulesets, które rozszerzenie może określić w ramach klucza manifestu "rule_resources".

Wartość

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 lub nowsza wersja

Maksymalna liczba „niebezpiecznych” reguł dynamicznych, które może dodać rozszerzenie.

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 lub nowsza wersja

Maksymalna liczba „niebezpiecznych” reguł o zakresie sesji, które może dodać rozszerzenie.

Wartość

5000

SESSION_RULESET_ID

Chrome 90 lub nowsza wersja

Identyfikator zestawu reguł dla reguł ograniczonych do sesji dodanych przez rozszerzenie.

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Promise Chrome 89+ 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

Zwraca liczbę reguł statycznych, które rozszerzenie może włączyć, zanim zostanie osiągnięty globalny limit reguł statycznych.

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (count: number) => void

    • liczba

      liczba

Zwroty

  • Promise<number>

    Chrome 91 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getDisabledRuleIds()

Promise Chrome 111+ 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
): Promise<number[]>

Zwraca listę reguł statycznych w danym Ruleset, które są obecnie wyłączone.

Parametry

  • Określa zestaw reguł, do którego ma zostać wysłane zapytanie.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Zwroty

  • thought Promise<number[]>

    Obiekt Promise, który zwraca listę identyfikatorów odpowiadających wyłączonym regułom w tym zbiorze reguł.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getDynamicRules()

Obietnica 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Zwraca bieżący zestaw reguł dynamicznych rozszerzenia. Osoby dzwoniące mogą opcjonalnie filtrować listę pobranych reguł, podając filter.

Parametry

  • filtr

    GetRulesFilter opcjonalny

    Chrome 111 lub nowsza wersja

    Obiekt do filtrowania listy pobranych reguł.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (rules: Rule[]) => void

Zwroty

  • Promise<Rule[]>

    Chrome 91 lub nowsza wersja

    Obiekt Promise, który rozwiązuje się za pomocą zbioru reguł dynamicznych. Obiekt Promise może zostać odrzucony w przypadku tymczasowych błędów wewnętrznych.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getEnabledRulesets()

Obietnica 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
): Promise<string[]>

Zwraca identyfikatory bieżącego zestawu włączonych statycznych zbiorów reguł.

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

Zwroty

  • Promise<string[]>

    Chrome 91 lub nowsza wersja

    Obiekt Promise, który zwraca listę identyfikatorów, gdzie każdy identyfikator odpowiada włączonemu statycznemu obiektowi Ruleset.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getMatchedRules()

Obietnica 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
): Promise<RulesMatchedDetails>

Zwraca wszystkie reguły dopasowane do rozszerzenia. Osoby dzwoniące mogą opcjonalnie filtrować listę dopasowanych reguł, podając filter. Ta metoda jest dostępna tylko w przypadku rozszerzeń z uprawnieniem "declarativeNetRequestFeedback" lub uprawnieniem "activeTab" przyznanym dla tabId określonego w filter. Uwaga: reguły, które nie są powiązane z aktywnym dokumentem i zostały dopasowane ponad 5 minut temu, nie zostaną zwrócone.

Parametry

Zwroty

  • Chrome 91 lub nowsza wersja

    Obiekt Promise, który jest rozwiązywany po pobraniu listy dopasowanych reguł. W przypadku błędu obiekt Promise zostanie odrzucony. Może się tak zdarzyć z różnych powodów, takich jak niewystarczające uprawnienia lub przekroczenie limitu.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getSessionRules()

Promise Chrome 90 lub nowsza wersja 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Zwraca bieżący zestaw reguł rozszerzenia w ramach sesji. Osoby dzwoniące mogą opcjonalnie filtrować listę pobranych reguł, podając filter.

Parametry

  • filtr

    GetRulesFilter opcjonalny

    Chrome 111 lub nowsza wersja

    Obiekt do filtrowania listy pobranych reguł.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (rules: Rule[]) => void

Zwroty

  • Promise<Rule[]>

    Chrome 91 lub nowsza wersja

    Obiekt Promise, który jest rozwiązywany za pomocą zestawu reguł o zakresie sesji.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

isRegexSupported()

Promise Chrome 87 lub nowsza wersja 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

Sprawdza, czy podane wyrażenie regularne będzie obsługiwane jako warunek reguły regexFilter.

Parametry

Zwroty

  • Chrome 91 lub nowsza wersja

    Obiekt Promise, który zwraca szczegóły dotyczące tego, czy wyrażenie regularne jest obsługiwane, a jeśli nie, to dlaczego.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

setExtensionActionOptions()

Promise Chrome 88 lub nowsza wersja 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): Promise<void>

Określa, czy liczba działań na kartach ma być wyświetlana jako tekst plakietki działania rozszerzenia, i umożliwia zwiększanie tej liczby.

Parametry

  • callback

    function opcjonalne

    Chrome 89 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 91 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

testMatchOutcome()

Promise Chrome 103 lub nowsza wersja 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

Sprawdza, czy któraś z reguł declarativeNetRequest rozszerzenia pasuje do hipotetycznego żądania. Uwaga: ta opcja jest dostępna tylko w przypadku rozpakowanych rozszerzeń, ponieważ jest przeznaczona do użycia tylko podczas tworzenia rozszerzenia.

Parametry

Zwroty

  • Obiekt Promise, który zwraca szczegóły pasujących reguł.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

updateDynamicRules()

Obietnica 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

Modyfikuje bieżący zestaw reguł dynamicznych rozszerzenia. Najpierw usuwane są reguły o identyfikatorach wymienionych w options.removeRuleIds, a potem dodawane są reguły podane w options.addRules. Uwagi:

  • Ta aktualizacja jest wykonywana jako pojedyncza operacja niepodzielna: dodawane i usuwane są wszystkie określone reguły albo zwracany jest błąd.
  • Te reguły są zachowywane między sesjami przeglądarki i aktualizacjami 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

  • Chrome 87 lub nowsza wersja
  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 91 lub nowsza wersja

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany w zestawie reguł. Może się tak zdarzyć z różnych powodów, takich jak nieprawidłowy format reguły, zduplikowany identyfikator reguły, przekroczenie limitu liczby reguł, błędy wewnętrzne i inne.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

updateEnabledRulesets()

Obietnica 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
): Promise<void>

Aktualizuje zestaw włączonych statycznych zbiorów reguł rozszerzenia. Najpierw usuwane są zestawy reguł o identyfikatorach wymienionych w options.disableRulesetIds, a następnie dodawane są zestawy reguł wymienione w options.enableRulesetIds. Pamiętaj, że zestaw włączonych statycznych zbiorów reguł jest zachowywany między sesjami, ale nie między aktualizacjami rozszerzeń, tzn. klucz manifestu rule_resources określa zestaw włączonych statycznych zbiorów reguł przy każdej aktualizacji rozszerzenia.

Parametry

  • Chrome 87 lub nowsza wersja
  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 91 lub nowsza wersja

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany w zestawie włączonych zestawów reguł. Może się to zdarzyć z różnych powodów, takich jak nieprawidłowe identyfikatory zestawów reguł, przekroczenie limitu liczby reguł lub błędy wewnętrzne.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

updateSessionRules()

Promise Chrome 90 lub nowsza wersja 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

Modyfikuje bieżący zestaw reguł rozszerzenia na poziomie sesji. Najpierw usuwane są reguły o identyfikatorach wymienionych w options.removeRuleIds, a potem dodawane są reguły podane w options.addRules. Uwagi:

  • Ta aktualizacja jest wykonywana jako pojedyncza operacja niepodzielna: dodawane i usuwane są wszystkie określone reguły albo zwracany jest błąd.
  • Te reguły nie są zachowywane między sesjami i są przechowywane w pamięci.
  • MAX_NUMBER_OF_SESSION_RULES to maksymalna liczba reguł sesji, które może dodać rozszerzenie.

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 91 lub nowsza wersja

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany w zestawie reguł. Może się tak zdarzyć z różnych powodów, takich jak nieprawidłowy format reguły, zduplikowany identyfikator reguły, przekroczenie limitu liczby reguł i inne.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

updateStaticRules()

Promise Chrome 111+ 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
): Promise<void>

Wyłącza i włącza poszczególne reguły statyczne w obiekcie Ruleset. Zmiany w regułach należących do wyłączonej Ruleset zaczną obowiązywać po jej ponownym włączeniu.

Parametry

Zwroty

  • thought Promise<void>

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany we włączonych regułach statycznych.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onRuleMatchedDebug

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

Uruchamiane, gdy reguła pasuje do żądania. Ta opcja jest dostępna tylko w przypadku rozpakowanych rozszerzeń z uprawnieniem "declarativeNetRequestFeedback", ponieważ jest przeznaczona wyłącznie do debugowania.

Parametry