chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

Opis

Interfejs chrome.declarativeNetRequest API 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

Plik manifestu

Oprócz uprawnień opisanych powyżej niektóre typy zestawów reguł, w szczególności statyczne zestawy reguł, wymagają zadeklarowania klucza manifestu "declarative_net_request", który powinien być słownikiem z jednym kluczem o nazwie "rule_resources". Ten klucz to tablica zawierająca 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). Statyczne zestawy reguł zostały omówione w dalszej części tego dokumentu.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

Pojęcia i zastosowanie

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

  • Zablokuj żądanie sieciowe.
  • Zaktualizuj schemat (z http na https).
  • Zapobiegaj blokowaniu żądań 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ą one zachowywane w sesjach przeglądarki i podczas uaktualniania 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ły sesji są zarządzane za pomocą JavaScriptu podczas korzystania z rozszerzenia.
Statyczny
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 znajdziesz szczegółowe informacje o typach zestawów reguł.

Zbiory reguł dynamicznych i ograniczonych do sesji

Zestawy reguł dynamicznych i sesji są zarządzane za pomocą JavaScriptu, gdy rozszerzenie jest używane.

  • Reguły dynamiczne są zachowywane w kolejnych sesjach przeglądarki i po uaktualnieniu rozszerzenia.
  • Reguły sesji są usuwane po zamknięciu przeglądarki i zainstalowaniu nowej wersji rozszerzenia.

Każdy z tych typów zbiorów reguł występuje tylko raz. Rozszerzenie może dynamicznie dodawać i usuwać reguły, wywołując funkcje updateDynamicRules() i updateSessionRules(), pod warunkiem że 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 sesji reguły statyczne są pakowane, instalowane i aktualizowane podczas instalacji lub aktualizacji 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 za pomocą co najmniej jednego słownika Ruleset. Ruleset słownik 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ł programowo.

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

Aby przetestować pliki reguł, wczytaj 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 programu.

Zbiór włączonych reguł statycznych i zbiorów reguł jest zachowywany między sesjami przeglądarki. Nie są one zachowywane po aktualizacji rozszerzenia, co oznacza, że po aktualizacji dostępne są tylko reguły, które zostały w plikach reguł.

Ze względu na wydajność obowiązują też ograniczenia dotyczące liczby reguł i zestawów reguł, które można włączyć jednocześnie. Zadzwoń pod numer getAvailableStaticRuleCount(), aby sprawdzić liczbę dodatkowych reguł, które można włączyć. Informacje o limitach reguł znajdziesz w artykule Limity reguł.

Aby włączyć lub wyłączyć statyczne reguły, wywołaj funkcję 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" w słowniku Ruleset.

Aby włączyć lub wyłączyć statyczne zbiory reguł, wywołaj funkcję 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" w słowniku Ruleset.

Tworzenie reguł

Niezależnie od typu reguła zaczyna się od 4 pól, jak pokazano poniżej. Klucze "id" i "priority" przyjmują liczbę, a klucze "action" i "condition" mogą określać kilka warunków blokowania i przekierowywania. Ta reguła blokuje wszystkie żądania skryptów pochodzące z domeny "foo.com" i wysyłane do dowolnego adresu URL zawierającego ciąg znaków "abc".

{
  "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 działania 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ą wywoływane przez żądania wysyłane ze stron internetowych. Jeśli do konkretnego żądania pasuje kilka reguł, należy im przypisać priorytety. W tej sekcji wyjaśniamy, jak są one priorytetyzowane. Określanie priorytetów odbywa się w 2 etapach.

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

W tym przypadku priorytetem będzie reguła, której priorytet nadało dane rozszerzenie.

Określanie priorytetów reguł w rozszerzeniu

W przypadku jednego rozszerzenia priorytetyzacja jest ustalana 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 nie jest równy block ani redirect, oceniane są wszystkie pasujące reguły modifyHeaders. Pamiętaj, że jeśli istnieją reguły z priorytetem zdefiniowanym przez dewelopera, który jest niższy niż priorytet określony dla reguł allow i allowAllRequests, takie reguły są ignorowane.

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

    • Jeśli reguła dodaje informacje do nagłówka, reguły o niższym priorytecie mogą dodawać informacje tylko do tego nagłówka. Operacje ustawiania i usuwania są niedozwolone.
    • Jeśli reguła ustawi nagłówek, reguły o niższym priorytecie mogą tylko dołączyć do niego tekst. Nie można wprowadzać żadnych innych zmian.
    • Jeśli reguła usunie nagłówek, reguły o niższym priorytecie nie będą mogły go dalej modyfikować.

Priorytetyzacja reguł między rozszerzeniami

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

  1. Reguły są traktowane priorytetowo w polu "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, pierwszeństwo ma ostatnio zainstalowane rozszerzenie.

Ograniczenia reguł

Wczytywanie i ocenianie reguł w przeglądarce wiąże się z obciążeniem wydajności, dlatego podczas korzystania z interfejsu API obowiązują pewne limity. 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żna włączyć tylko 10 z nich. Ten drugi typ nazywa się MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Łącznie te zestawy reguł gwarantują co najmniej 30 tys. reguł. Jest to tzw. GUARANTEED_MINIMUM_STATIC_RULES.

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

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

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

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

Wszystkie typy reguł mogą używać wyrażeń regularnych, ale łączna liczba reguł wyrażeń regularnych każdego typu nie może przekraczać 1000. Jest to tzw. MAX_NUMBER_OF_REGEX_RULES.

Po skompilowaniu każda reguła musi mieć mniej niż 2 KB. Jest to w przybliżeniu powiązane 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 service workerami

Deklaratywne żądanie sieciowe ma zastosowanie tylko do żą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 w skrypcie service worker. Interfejs declarativeNetRequest nie ma wpływu na odpowiedzi generowane przez skrypt service worker ani pobierane z CacheStorage, ale ma wpływ na wywołania fetch() wykonywane w skrypcie service worker.

Zasoby dostępne w internecie

Reguła declarativeNetRequest nie może przekierowywać żą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ć funkcję updateDynamicRules(). Procedura w przypadku updateSessionRules() jest taka sama.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Aktualizowanie statycznych zestawów reguł

Poniższy przykład pokazuje, jak włączać i wyłączać zestawy reguł z uwzględnieniem liczby dostępnych i maksymalnej liczby włączonych statycznych zestawów reguł. Zrobisz to, gdy liczba potrzebnych reguł statycznych przekroczy dozwoloną liczbę. Aby to zadziałało, niektóre zestawy reguł powinny być zainstalowane, a niektóre wyłączone (w pliku manifestu ustawienie "Enabled" powinno mieć wartość 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 ustala priorytety reguł w rozszerzeniu. Podczas sprawdzania reguł określania priorytetów możesz otworzyć je w osobnym oknie.

Klucz „priority”

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

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

Przejście na stronę https://google.com
Ten adres URL obejmują 2 reguły: reguły o identyfikatorach 1 i 4. Obowiązuje reguła o identyfikatorze 1, ponieważ działania "block" mają wyższy priorytet niż działania "redirect". Pozostałe reguły nie mają zastosowania, ponieważ dotyczą dłuższych adresów URL.
Przejście na stronę https://google.com/1234
Ze względu na dłuższy adres URL reguła o identyfikatorze 2 pasuje teraz do reguł o identyfikatorach 1 i 4. Zastosowana zostanie reguła o identyfikatorze 2, ponieważ "allow" ma wyższy priorytet niż "block" i "redirect".
Przejście na stronę https://google.com/12345
Wszystkie 4 reguły pasują do tego adresu URL. Zastosowana zostanie reguła o identyfikatorze 3, ponieważ jej priorytet określony przez dewelopera jest najwyższy 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

Poniższy przykład wymaga uprawnień hosta do *://*.example.com/*.

W przykładzie poniżej pokazujemy, jak przekierować żądanie z example.com na stronę w ramach samego rozszerzenia. Ścieżka rozszerzenia /a.jpg jest przekształcana w chrome-extension://EXTENSION_ID/a.jpg, gdzie EXTENSION_ID to identyfikator rozszerzenia. Aby to działało, w pliku manifestu należy zadeklarować /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"]
  }
}

Poniższy przykład używa klucza "transform" do przekierowywania do subdomeny example.com. Używa kotwicy nazwy domeny („||”), aby przechwytywać żądania z dowolnym schematem z domeny 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. Zwróć uwagę, że w przypadku klucza "regexFilter" kropki są poprzedzone znakiem ucieczki, a grupa przechwytująca wybiera „abc” lub „def”. Klucz "regexSubstitution" określa pierwsze zwrócone dopasowanie wyrażenia regularnego przy użyciu „\1”. W tym przypadku ciąg „abc” jest pobierany z przekierowanego adresu URL i umieszczany 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 z głównej ramki 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

Określa, czy żądanie pochodzi od podmiotu zewnętrznego czy wewnętrznego w stosunku do ramki, w której zostało wygenerowane. Żądanie jest uznawane za pochodzące od podmiotu własnego, jeśli ma tę samą domenę (eTLD+1) co ramka, w której zostało wygenerowane.

Typ wyliczeniowy

„firstParty”
Żądanie sieciowe pochodzi z ramki, w której zostało wygenerowane.

„thirdParty”
Żądanie sieciowe pochodzi od firmy zewnętrznej w stosunku do ramki, w której zostało wygenerowane.

ExtensionActionOptions

Chrome 88 lub nowsza

Właściwości

  • displayActionCountAsBadgeText

    wartość logiczna opcjonalna

    Określa, czy liczba działań na stronie ma być automatycznie wyświetlana jako tekst plakietki rozszerzenia. To ustawienie jest zachowywane w kolejnych sesjach.

  • tabUpdate

    TabActionCountUpdate [opcjonalnie]

    Chrome 89 lub nowsza

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

GetDisabledRuleIdsOptions

Chrome 111 lub nowsza

Właściwości

  • rulesetId

    tekst

    Identyfikator odpowiadający statycznemu Ruleset.

GetRulesFilter

Chrome 111 lub nowsza

Właściwości

  • ruleIds

    number[] opcjonalny

    Jeśli zostanie podany, uwzględniane są tylko reguły z pasującymi identyfikatorami.

HeaderInfo

Chrome 128 lub nowsza

Właściwości

  • excludedValues

    string[] opcjonalnie

    Jeśli ten warunek jest określony, nie jest spełniony, jeśli 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 pasuje do nazwy tylko wtedy, gdy nie określono wartości values ani excludedValues.

  • wartości

    string[] opcjonalnie

    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 bez uwzględniania wielkości liter oraz te konstrukcje:

    „*” : odpowiada dowolnej liczbie znaków.

    „?” : pasuje do 0 lub 1 znaku.

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

HeaderOperation

Chrome w wersji 86 lub nowszej

Opisuje możliwe operacje w przypadku 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

Właściwości

  • isSupported

    wartość logiczna

  • powód,

    UnsupportedRegexReason opcjonalny

    Określa przyczynę, dla której wyrażenie regularne jest nieobsługiwane. Podawany tylko wtedy, gdy wartość isSupported to fałsz.

MatchedRule

Właściwości

  • ruleId

    liczba

    Identyfikator reguły dopasowywania.

  • rulesetId

    tekst

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

MatchedRuleInfo

Właściwości

  • reguła

    MatchedRule

  • tabId

    liczba

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

  • timeStamp

    liczba

    Czas, w którym reguła została dopasowana. Sygnatury czasowe będą zgodne z konwencją JavaScriptu dotyczącą czasu, czyli liczbą milisekund od początku epoki.

MatchedRuleInfoDebug

Właściwości

MatchedRulesFilter

Właściwości

  • minTimeStamp

    number opcjonalny

    Jeśli została określona, reguła będzie pasować tylko do sygnatur czasowych po podanej sygnaturze czasowej.

  • tabId

    number opcjonalny

    Jeśli podasz tę wartość, będą dopasowywane tylko reguły dotyczące danej karty. Odpowiada regułom niepowiązanym z żadną aktywną kartą, jeśli wartość wynosi -1.

ModifyHeaderInfo

Chrome w wersji 86 lub nowszej

Właściwości

  • nagłówek

    tekst

    Nazwa nagłówka do zmodyfikowania.

  • 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

    wartość logiczna opcjonalna

    Chrome 94 lub nowsza

    Jeśli wartość to „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 do dodania lub zastąpienia.

  • removeParams

    string[] opcjonalnie

    Lista kluczy zapytań do usunięcia.

Redirect

Właściwości

  • extensionPath

    ciąg znaków opcjonalny

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

  • regexSubstitution

    ciąg znaków opcjonalny

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

  • przekształcenie

    URLTransform opcjonalny

    Przekształcenia adresu 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

Właściwości

  • isCaseSensitive

    wartość logiczna opcjonalna

    Określa, czy w przypadku podanego parametru regex rozróżniana jest wielkość liter. Wartość domyślna to true.

  • wyrażenie regularne

    tekst

    Wyrażenie regularne do sprawdzenia.

  • requireCapturing

    wartość logiczna opcjonalna

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

RequestDetails

Właściwości

  • documentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowsza

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

  • documentLifecycle

    DocumentLifecycle opcjonalny

    Chrome 106 lub nowsza

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

  • frameId

    liczba

    Wartość 0 oznacza, że żądanie jest wysyłane w głównej ramce, a wartość dodatnia – że jest wysyłane w ramce podrzędnej o danym identyfikatorze. Jeśli dokument (pod)ramki jest wczytany (type jest main_frame lub sub_frame), frameId wskazuje identyfikator tej ramki, a nie identyfikator ramki zewnętrznej. Identyfikatory ramek są unikalne w ramach karty.

  • frameType

    FrameType opcjonalny

    Chrome 106 lub nowsza

    Rodzaj ramki, jeśli to żądanie dotyczy ramki.

  • inicjator,

    ciąg znaków opcjonalny

    Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

  • method

    tekst

    Standardowa metoda HTTP.

  • parentDocumentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowsza

    Unikalny identyfikator dokumentu nadrzędnego ramki, jeśli to żą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 następuje żądanie. Ustaw wartość -1, jeśli żądanie nie jest powiązane z kartą.

  • Typ zasobu żądania.

  • URL

    tekst

    Adres URL żądania.

RequestMethod

Chrome 91 lub nowszy

Opisuje metodę żądania HTTP w żądaniu sieciowym.

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 uruchamia tę regułę.

  • id

    liczba

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

  • kampanii

    number opcjonalny

    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 ma być wykonane przekierowanie. Dotyczy tylko reguł przekierowania.

  • requestHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome w wersji 86 lub nowszej

    Nagłówki żądania do zmodyfikowania. Prawidłowe tylko wtedy, gdy RuleActionType ma wartość „modifyHeaders”.

  • responseHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome w wersji 86 lub nowszej

    Nagłówki odpowiedzi do zmodyfikowania w przypadku żądania. Prawidłowe tylko wtedy, gdy RuleActionType ma wartość „modifyHeaders”.

  • Typ działania do wykonania.

RuleActionType

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

Typ wyliczeniowy

„block”
Blokuje żądanie sieciowe.

„redirect”
Przekieruj żądanie sieciowe.

„allow”
Zezwól na żądanie sieciowe. Jeśli istnieje reguła zezwalająca, która pasuje do żądania, nie zostanie ono przechwycone.

„upgradeScheme”
Zaktualizuj schemat adresu URL żądania sieci do https, jeśli żądanie jest typu http lub ftp.

„modifyHeaders”
Modyfikowanie nagłówków żądania lub odpowiedzi w żądaniu sieciowym.

„allowAllRequests”
Zezwalaj na wszystkie żądania w hierarchii ramek, w tym na samo żądanie ramki.

RuleCondition

Właściwości

  • domainType

    DomainType opcjonalny

    Określa, czy żądanie sieciowe jest własne czy pochodzi z domeny innej firmy. Jeśli ten parametr zostanie pominięty, wszystkie prośby będą akceptowane.

  • domeny

    string[] opcjonalnie

    Wycofane w Chrome 101

    Zamiast tego użyj initiatorDomains

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

  • excludedDomains

    string[] opcjonalnie

    Wycofane w Chrome 101

    Zamiast tego użyj excludedInitiatorDomains

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

  • excludedInitiatorDomains

    string[] opcjonalnie

    Chrome 101 lub nowsza

    Reguła nie będzie pasować do żądań sieciowych pochodzących z listy excludedInitiatorDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczane. Ma to pierwszeństwo przed zasadą initiatorDomains.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Dopasowanie następuje do inicjatora żądania, a nie do adresu URL żądania.
    • Wykluczone są też subdomeny wymienionych domen.
  • excludedRequestDomains

    string[] opcjonalnie

    Chrome 101 lub nowsza

    Reguła nie będzie pasować do żądań sieciowych, gdy domeny będą pasować do jednej z domen na liście excludedRequestDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczane. Ma to pierwszeństwo przed zasadą requestDomains.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Wykluczone są też subdomeny wymienionych domen.
  • excludedRequestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowszy

    Lista metod żądań, 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 nich, będą pasować 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 zostanie określony żaden z nich, wszystkie typy zasobów z wyjątkiem „main_frame” zostaną zablokowane.

  • excludedResponseHeaders

    HeaderInfo[] optional

    Chrome 128 lub nowsza

    Reguła nie pasuje, jeśli żądanie pasuje do dowolnego warunku nagłówka odpowiedzi na tej liście (jeśli jest 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

    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[] opcjonalnie

    Chrome 145 lub nowsza

    Reguła nie będzie pasować do żądań sieciowych, gdy domena powiązanej ramki najwyższego poziomu będzie pasować do jednej z domen na liście excludedTopDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczane. Ma to pierwszeństwo przed zasadą topDomains.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Wykluczone są też subdomeny wymienionych domen.
    • W przypadku żądań bez powiązanej ramki najwyższego poziomu (np. żądań zainicjowanych przez ServiceWorker) zamiast tego jest brana pod uwagę domena inicjatora żądania.
  • initiatorDomains

    string[] opcjonalnie

    Chrome 101 lub nowsza

    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 muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Dopasowanie następuje do inicjatora żądania, a nie do adresu URL żądania.
    • Dopasowywane są też subdomeny wymienionych domen.
  • isUrlFilterCaseSensitive

    wartość logiczna opcjonalna

    Określa, czy w przypadku atrybutu urlFilter lub regexFilter (w zależności od tego, który z nich został określony) jest rozróżniana wielkość liter. Wartość domyślna to fałsz.

  • regexFilter

    ciąg znaków opcjonalny

    Wyrażenie regularne pasujące do adresu URL żądania sieciowego. Jest ona zgodna ze składnią RE2.

    Uwaga: można określić tylko jedną z opcji urlFilter lub regexFilter.

    Uwaga: parametr regexFilter musi składać się tylko 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 ASCII są zakodowane w formacie UTF-8.

  • requestDomains

    string[] opcjonalnie

    Chrome 101 lub nowsza

    Reguła będzie pasować do żądań sieciowych tylko wtedy, gdy domena będzie pasować do jednej z domen na liście 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 muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Dopasowywane są też subdomeny wymienionych domen.
  • requestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowszy

    Lista metod żądań HTTP, do których może pasować reguła. Pusta lista jest niedozwolona.

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

  • resourceTypes

    ResourceType[] opcjonalny

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

    Uwaga: musi być określony w przypadku reguł allowAllRequests i może obejmować tylko typy zasobów sub_frame i main_frame.

  • responseHeaders

    HeaderInfo[] optional

    Chrome 128 lub nowsza

    Reguła jest dopasowywana, jeśli żądanie spełnia dowolny warunek nagłówka odpowiedzi na tej liście (jeśli jest określony).

  • tabIds

    number[] opcjonalny

    Chrome 92 lub nowsza

    Lista tabs.Tab.id, z którymi reguła powinna być zgodna. 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[] opcjonalnie

    Chrome 145 lub nowsza

    Reguła będzie pasować do żądań sieciowych tylko wtedy, gdy domena powiązanej ramki najwyższego poziomu będzie pasować do jednej z domen na liście topDomains. Jeśli lista zostanie pominięta, reguła będzie stosowana do żądań powiązanych ze wszystkimi domenami ramki najwyższego poziomu. Pusta lista jest niedozwolona.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Dopasowywane są też subdomeny wymienionych domen.
    • W przypadku żądań bez powiązanej ramki najwyższego poziomu (np. żądań zainicjowanych przez ServiceWorker) zamiast tego jest brana pod uwagę domena inicjatora żądania.
  • urlFilter

    ciąg znaków opcjonalny

    Wzorzec, który jest porównywany z adresem URL żądania sieciowego. Obsługiwane konstrukcje:

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

    '|' : lewy/prawy kotwiczący: jeśli jest używany na którymkolwiek 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.

    „^”: znak separatora. Odpowiada wszystkiemu z wyjątkiem litery, cyfry lub jednego z tych znaków: _, -, . lub %. Pasuje on również do końca adresu URL.

    Dlatego urlFilter składa się z tych części: (opcjonalny lewy/nazwa domeny) + wzorzec + (opcjonalny prawy).

    Jeśli go pominiesz, zostaną dopasowane wszystkie adresy URL. Pusty ciąg znaków jest niedozwolony.

    Wzorzec zaczynający się od ||* jest niedozwolony. Zamiast niej użyj zasady *.

    Uwaga: można określić tylko jedną z opcji urlFilter lub regexFilter.

    Uwaga: parametr urlFilter musi składać się tylko 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 ASCII są zakodowane w formacie UTF-8. Jeśli na przykład adres URL żądania to http://abc.рф?q=ф, wzorzec urlFilter zostanie dopasowany do adresu URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145 lub nowsza

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

    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 w odniesieniu do katalogu rozszerzenia.

RulesMatchedDetails

Właściwości

TabActionCountUpdate

Chrome 89 lub nowsza

Właściwości

  • Zwiększ

    liczba

    Wartość, o którą należy zwiększyć liczbę działań na karcie. Wartości ujemne zmniejszają liczbę.

  • tabId

    liczba

    Karta, dla której ma zostać zaktualizowana liczba działań.

TestMatchOutcomeResult

Chrome 103 lub nowsza

Właściwości

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 lub nowsza

Właściwości

  • inicjator,

    ciąg znaków opcjonalny

    Adres URL inicjatora (jeśli występuje) hipotetycznego żądania.

  • method

    RequestMethod opcjonalny

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

  • responseHeaders

    obiekt opcjonalny

    Chrome 129 lub nowsza

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

  • tabId

    number opcjonalny

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

  • topUrl

    ciąg znaków opcjonalny

    Chrome 145 lub nowsza

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

  • Typ zasobu hipotetycznego żądania.

  • URL

    tekst

    Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome 87 lub nowsza

Wyjaśnia, 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

Właściwości

  • addRules

    Rule[] opcjonalny

    Reguły do dodania.

  • removeRuleIds

    number[] opcjonalny

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

UpdateRulesetOptions

Chrome 87 lub nowsza

Właściwości

  • disableRulesetIds

    string[] opcjonalnie

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

  • enableRulesetIds

    string[] opcjonalnie

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

UpdateStaticRulesOptions

Chrome 111 lub nowsza

Właściwości

  • disableRuleIds

    number[] opcjonalny

    Zbiór 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 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 do żądania.

  • ścieżka

    ciąg znaków opcjonalny

    Nowa ścieżka żądania. Jeśli to pole jest puste, dotychczasowa ścieżka zostanie wyczyszczona.

  • port

    ciąg znaków opcjonalny

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

  • zapytanie

    ciąg znaków opcjonalny

    Nowe zapytanie dotyczące prośby. Powinien być pusty (w takim przypadku istniejące zapytanie zostanie wyczyszczone) lub zaczynać się od znaku „?”.

  • queryTransform

    QueryTransform opcjonalny

    Dodawanie, usuwanie i zastępowanie par klucz-wartość w zapytaniu.

  • 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 w żądaniu.

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 wykonywać połączenia MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, podany w minutach. Dodatkowe wywołania natychmiast się nie powiodą i ustawią wartość runtime.lastError. Uwaga: getMatchedRules wywołania powiązane z gestem użytkownika są zwolnione z limitu.

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 lub nowsza

Minimalna liczba reguł statycznych gwarantowanych rozszerzeniu w ramach włączonych zestawów reguł statycznych. Wszystkie reguły przekraczające ten limit będą wliczane do globalnego limitu reguł statycznych.

Wartość

30 000

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ść

30 000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 lub nowsza

Maksymalna liczba statycznych Rulesets, które rozszerzenie może włączyć w danym momencie.

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

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

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

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 lub nowsza

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

Wartość

5000

SESSION_RULESET_ID

Chrome w wersji 90 lub nowszej

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

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Promise Chrome 89 lub nowsza wersja 
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

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (count: number) => void

    • liczba

      liczba

Zwroty

  • Promise<number>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getDisabledRuleIds()

Promise Chrome 111 lub nowszy 
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 być wysłane zapytanie.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Zwroty

  • Promise<number[]>

    Obietnica, która zwraca listę identyfikatorów odpowiadających wyłączonym regułom w tym zbiorze reguł.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getDynamicRules()

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

Zwraca bieżący zestaw reguł dynamicznych rozszerzenia. Rozmówcy mogą opcjonalnie filtrować listę pobranych reguł, podając filter.

Parametry

  • filtr

    GetRulesFilter opcjonalny

    Chrome 111 lub nowsza

    Obiekt do filtrowania listy pobranych reguł.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (rules: Rule[]) => void

Zwroty

  • Promise<Rule[]>

    Chrome 91 lub nowszy

    Obietnica, która jest spełniana w przypadku zbioru reguł dynamicznych. Obietnica może zostać odrzucona w przypadku przejściowych błędów wewnętrznych.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą 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

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

Zwroty

  • Promise<string[]>

    Chrome 91 lub nowszy

    Obietnica, która zwraca listę identyfikatorów, gdzie każdy identyfikator odpowiada włączonemu statycznemu Ruleset.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getMatchedRules()

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

Zwraca wszystkie reguły dopasowane do rozszerzenia. Rozmówcy mogą opcjonalnie filtrować listę pasujących reguł, podając filter. Ta metoda jest dostępna tylko w przypadku rozszerzeń z uprawnieniem "declarativeNetRequestFeedback" lub uprawnieniem "activeTab" przyznanym dla elementu tabId określonego w parametrze 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 nowszy

    Obietnica, która zostanie spełniona po pobraniu listy pasujących reguł. W przypadku błędu obietnica zostanie odrzucona. Może to wynikać z różnych powodów, np. z niewystarczających uprawnień lub przekroczenia limitu.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

getSessionRules()

Obietnica Chrome w wersji 90 lub nowszej 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
): Promise<Rule[]>

Zwraca bieżący zestaw reguł o zakresie sesji dla rozszerzenia. Rozmówcy mogą opcjonalnie filtrować listę pobranych reguł, podając filter.

Parametry

  • filtr

    GetRulesFilter opcjonalny

    Chrome 111 lub nowsza

    Obiekt do filtrowania listy pobranych reguł.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (rules: Rule[]) => void

Zwroty

  • Promise<Rule[]>

    Chrome 91 lub nowszy

    Obietnica, która jest spełniana w przypadku zbioru reguł o zakresie sesji.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

isRegexSupported()

Promise Chrome 87 lub nowszy 
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 nowszy

    Obietnica, która jest spełniana z informacjami o tym, czy wyrażenie regularne jest obsługiwane, a jeśli nie, to z podaniem przyczyny.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

setExtensionActionOptions()

Promise Chrome 88 lub nowszy 
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

    funkcja opcjonalna

    Chrome 89 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

testMatchOutcome()

Promise Chrome 103 lub nowszy 
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żywania tylko podczas tworzenia rozszerzeń.

Parametry

Zwroty

  • Obietnica, która jest spełniana ze szczegółami pasujących reguł.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą 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 z identyfikatorami wymienionymi w options.removeRuleIds, a potem dodawane są reguły podane w options.addRules. Uwagi:

  • Ta aktualizacja jest wykonywana jako pojedyncza operacja niepodzielna: wszystkie określone reguły są dodawane i usuwane albo zwracany jest błąd.
  • Te reguły są zachowywane w kolejnych sesjach przeglądarki i aktualizacjach rozszerzenia.
  • 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
  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona, a zestaw reguł nie ulegnie zmianie. Może się to zdarzyć z wielu powodów, takich jak nieprawidłowy format reguły, zduplikowany identyfikator reguły, przekroczenie limitu liczby reguł, błędy wewnętrzne itp.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

updateEnabledRulesets()

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

Aktualizuje zestaw włączonych statycznych zbiorów reguł dla rozszerzenia. Najpierw usuwane są zestawy reguł z identyfikatorami wymienionymi w options.disableRulesetIds, a potem dodawane są zestawy reguł wymienione w options.enableRulesetIds. Pamiętaj, że zestaw włączonych statycznych zbiorów reguł jest zachowywany w różnych sesjach, ale nie w przypadku aktualizacji rozszerzenia. Oznacza to, że klucz manifestu rule_resources określa zestaw włączonych statycznych zbiorów reguł przy każdej aktualizacji rozszerzenia.

Parametry

  • Chrome 87 lub nowsza
  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona, a zestaw włączonych zestawów reguł nie ulegnie zmianie. Może się to zdarzyć z różnych powodów, np. z powodu nieprawidłowych identyfikatorów zestawu reguł, przekroczenia limitu liczby reguł lub błędów wewnętrznych.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

updateSessionRules()

Obietnica Chrome w wersji 90 lub nowszej 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
): Promise<void>

Modyfikuje bieżący zestaw reguł dotyczących sesji dla rozszerzenia. Najpierw usuwane są reguły z identyfikatorami wymienionymi w options.removeRuleIds, a potem dodawane są reguły podane w options.addRules. Uwagi:

  • Ta aktualizacja jest wykonywana jako pojedyncza operacja niepodzielna: wszystkie określone reguły są dodawane i usuwane 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

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona, a zestaw reguł nie ulegnie zmianie. Może się to zdarzyć z różnych powodów, np. z powodu nieprawidłowego formatu reguły, zduplikowanego identyfikatora reguły lub przekroczenia limitu liczby reguł.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

updateStaticRules()

Promise Chrome 111 lub nowszy 
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łączonego Ruleset zaczną obowiązywać przy następnym włączeniu tego.

Parametry

Zwroty

  • Promise<void>

    Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona, a włączone reguły statyczne nie zostaną zmienione.

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onRuleMatchedDebug

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

Wywoływane, gdy reguła pasuje do żądania. Dostępne tylko w przypadku rozpakowanych rozszerzeń z uprawnieniem "declarativeNetRequestFeedback", ponieważ jest to przeznaczone wyłącznie do debugowania.

Parametry