chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

Описание

API chrome.declarativeNetRequest используется для блокировки или изменения сетевых запросов путем указания декларативных правил. Это позволяет расширениям изменять сетевые запросы, не перехватывая их и не просматривая их содержимое, что обеспечивает большую конфиденциальность.

Разрешения

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

Доступность

Chrome 84 и более поздних версий

Манифест

Помимо разрешений, описанных выше, для некоторых типов наборов правил, в частности статических, требуется объявить ключ манифеста "declarative_net_request", который должен быть словарем с одним ключом "rule_resources". Этот ключ представляет собой массив, содержащий словари типа Ruleset, как показано ниже. (Обратите внимание, что название Ruleset не появляется в JSON-коде манифеста, поскольку это просто массив.) Статические наборы правил описаны ниже.

{
  "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/*"
  ],
  ...
}

Основные понятия и использование

Чтобы использовать этот API, укажите один или несколько наборов правил. Набор правил содержит массив правил. Одно правило выполняет одно из следующих действий:

  • Блокировать сетевой запрос.
  • Обновите схему (с http на https).
  • Предотвращает блокировку запроса, отменяя все соответствующие правила блокировки.
  • Перенаправлять сетевые запросы.
  • Изменение заголовков запросов или ответов.

Существует три типа наборов правил, которые управляются по-разному.

Динамическая
Сохраняются между сеансами браузера и обновлениями расширения. Управляются с помощью JavaScript, пока расширение используется.
Сеанс
Очищается при закрытии браузера и установке новой версии расширения. Правила сеанса управляются с помощью JavaScript, пока расширение используется.
Статический
Упаковывается, устанавливается и обновляется вместе с расширением. Статические правила хранятся в файлах правил в формате JSON и перечислены в файле манифеста.

В следующих разделах подробно описаны типы наборов правил.

Наборы динамических правил и правил на уровне сеанса

Динамические наборы правил и наборы правил сеанса управляются с помощью JavaScript во время использования расширения.

  • Динамические правила сохраняются в разных сеансах браузера и при обновлении расширений.
  • Правила сеанса удаляются при закрытии браузера и установке новой версии расширения.

Для каждого типа набора правил можно создать только один набор. Расширение может динамически добавлять или удалять правила, вызывая updateDynamicRules() и updateSessionRules(), если не превышены ограничения на количество правил. Подробнее об ограничениях на количество правил… Пример можно найти в разделе Примеры кода.

Статические наборы правил

В отличие от динамических правил и правил сеанса, статические правила упаковываются, устанавливаются и обновляются при установке или обновлении расширения. Они хранятся в файлах правил в формате JSON, которые указываются в расширении с помощью ключей "declarative_net_request" и "rule_resources", как описано выше, а также одного или нескольких словарей Ruleset. Словарь Ruleset содержит путь к файлу правил, идентификатор набора правил в файле и информацию о том, включен ли набор правил. Последние два параметра важны, если вы включаете или отключаете набор правил программно.

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

Чтобы протестировать файлы правил, загрузите расширение в распакованном виде. Ошибки и предупреждения о недопустимых статических правилах показываются только для распакованных расширений. Недопустимые статические правила в упакованных расширениях игнорируются.

Включение и отключение статических правил и наборов правил

Как отдельные статические правила, так и полные наборы статических правил можно включать или отключать во время выполнения.

Набор включенных статических правил и наборов правил сохраняется между сеансами браузера. Ни те, ни другие не сохраняются при обновлении расширения. Это значит, что после обновления будут доступны только правила, которые вы оставили в файлах правил.

В целях повышения производительности также ограничено количество правил и наборов правил, которые могут быть включены одновременно. Вызовите getAvailableStaticRuleCount(), чтобы узнать, сколько дополнительных правил можно включить. Подробнее об ограничениях на количество правил…

Чтобы включить или отключить статические правила, вызовите updateStaticRules(). Этот метод принимает объект UpdateStaticRulesOptions, который содержит массивы идентификаторов правил, которые нужно включить или отключить. Идентификаторы задаются с помощью ключа "id" словаря Ruleset.

Чтобы включить или отключить статические наборы правил, вызовите updateEnabledRulesets(). Этот метод принимает объект UpdateRulesetOptions, который содержит массивы идентификаторов наборов правил, которые нужно включить или отключить. Идентификаторы задаются с помощью ключа "id" словаря Ruleset.

Создание правил

Независимо от типа, правило начинается с четырех полей, как показано ниже. В то время как ключи "id" и "priority" принимают число, ключи "action" и "condition" могут предоставлять несколько условий блокировки и перенаправления. Следующее правило блокирует все запросы скриптов, исходящие из "foo.com", к любому URL, содержащему подстроку "abc".

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

Символы сопоставления urlFilter

Ключ "condition" правила позволяет ключу "urlFilter" выполнять действия с URL в указанном домене. Шаблоны создаются с помощью токенов сопоставления с образцом. Ниже приведено несколько примеров.

urlFilter Соответствует Не соответствует
"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

Приоритет правил

Правила активируются запросами, отправленными с веб-страниц. Если одному запросу соответствует несколько правил, необходимо задать их приоритет. В этом разделе объясняется, как определяется приоритет. Приоритизация выполняется в два этапа.

  1. Приоритет определяется для правил в рамках расширения.
  2. Если правило к запросу могут применить несколько расширений, приоритет определяется для всех расширений, соответствующих определенному запросу.

При этом правило, которое имеет приоритет в определенном расширении, будет иметь приоритет и по сравнению с правилами из других расширений.

Приоритет правил в расширении

В рамках одного расширения приоритет определяется следующим образом:

  1. Возвращается правило с наивысшим приоритетом, заданным разработчиком (то есть поле "priority").

  2. Если правил с наивысшим приоритетом несколько, они упорядочиваются по полю "action" в следующем порядке:

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

  3. Если тип действия не block и не redirect, то оцениваются все подходящие правила modifyHeaders. Обратите внимание, что если есть правила с приоритетом, заданным разработчиком, который ниже приоритета, указанного для allow и allowAllRequests, то такие правила игнорируются.

  4. Если один и тот же заголовок изменяется несколькими правилами, то результат зависит от заданного разработчиком поля "priority" и указанных операций.

    • Если правило добавляет заголовок, то правила с более низким приоритетом могут только добавлять этот заголовок. Операции по установке и удалению не разрешены.
    • Если правило задает заголовок, то правила с более низким приоритетом могут только добавлять данные в этот заголовок. Другие изменения не допускаются.
    • Если правило удаляет заголовок, то правила с более низким приоритетом не могут его изменить.

Приоритет правил между расширениями

Если только у одного расширения есть правило, соответствующее запросу, применяется это правило. Если запросу соответствует несколько расширений, то применяется следующий процесс:

  1. Приоритет правил определяется по полю "action" в следующем порядке:

    1. block
    2. redirect или upgradeScheme
    3. allow или allowAllRequests

  2. Если совпадений несколько, приоритет будет у расширения, установленного последним.

Ограничения для правил

Загрузка и оценка правил в браузере требует дополнительных ресурсов, поэтому при использовании API действуют некоторые ограничения. Ограничения зависят от типа правила.

Статические правила

Статические правила указываются в файлах правил, объявленных в файле манифеста. В расширении можно указать до 50 статических наборов правил в ключе манифеста "rule_resources", но одновременно включить можно только 10 из них. Последний называется MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. В совокупности эти наборы правил гарантируют не менее 30 000 правил. Это называется GUARANTEED_MINIMUM_STATIC_RULES.

Количество доступных правил зависит от того, сколько правил включено всеми расширениями, установленными в браузере пользователя. Это число можно узнать во время выполнения, вызвав метод getAvailableStaticRuleCount(). Пример можно найти в разделе Примеры кода.

Динамические правила и правила для сеансов

Ограничения, применяемые к динамическим правилам и правилам сеанса, проще, чем ограничения для статических правил. Общее количество не должно превышать 5000. Это называется MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

Правила, в которых используются регулярные выражения

Регулярные выражения можно использовать во всех типах правил, но общее количество правил с регулярными выражениями каждого типа не может превышать 1000. Это значение называется MAX_NUMBER_OF_REGEX_RULES.

Кроме того, размер каждого правила после компиляции не должен превышать 2 КБ. Это примерно соответствует сложности правила. Если вы попытаетесь загрузить правило, превышающее это ограничение, вы увидите предупреждение, подобное приведенному ниже, и правило будет проигнорировано.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Взаимодействие с сервис-воркерами

Правила declarativeNetRequest применяются только к запросам, которые достигают сетевого стека. Сюда входят ответы из кеша HTTP, но могут не входить ответы, которые проходят через обработчик onfetch сервисного работника. declarativeNetRequest не повлияет на ответы, сгенерированные сервисным работником или полученные из CacheStorage, но повлияет на вызовы fetch(), сделанные в сервисном работнике.

Ресурсы, доступные в интернете

Правило declarativeNetRequest не может перенаправлять запрос общедоступного ресурса на ресурс, недоступный в интернете. В противном случае возникнет ошибка. даже если указанный веб-ресурс принадлежит перенаправляющему расширению. Чтобы объявить ресурсы для declarativeNetRequest, используйте массив "web_accessible_resources" манифеста.

Примеры

Примеры кода

Как обновить динамические правила

В следующем примере демонстрируется вызов updateDynamicRules(). Процедура для updateSessionRules() такая же.

// 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
});

Обновление статических наборов правил

В примере ниже показано, как включать и отключать наборы правил с учетом количества доступных и максимального количества включенных статических наборов правил. Это может потребоваться, если вам нужно больше статических правил, чем разрешено. Чтобы это работало, некоторые наборы правил должны быть установлены с отключенными наборами правил (для этого в файле манифеста нужно задать для "Enabled" значение 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);
}

Примеры правил

В примерах ниже показано, как Chrome определяет приоритет правил в расширении. При проверке правил вы можете открыть правила приоритизации в отдельном окне.

Ключ priority

Для этих примеров требуется разрешение на доступ к хосту *://*.example.com/*.

Чтобы определить приоритет определенного URL, посмотрите на ключи "priority" (определяется разработчиком), "action" и "urlFilter". Примеры ниже относятся к файлу правил, который приведен под ними.

Переход на страницу https://google.com
Этому URL соответствуют два правила: с идентификаторами 1 и 4. Применяется правило с идентификатором 1, поскольку действия "block" имеют более высокий приоритет, чем действия "redirect". Остальные правила не применяются, поскольку они предназначены для более длинных URL.
Переход на страницу https://google.com/1234
Поскольку URL стал длиннее, теперь ему соответствует не только правило 1 и 4, но и правило 2. Применяется правило с идентификатором 2, поскольку у "allow" приоритет выше, чем у "block" и "redirect".
Переход на страницу https://google.com/12345
Этому URL соответствуют все четыре правила. Применяется правило с идентификатором 3, поскольку у него самый высокий приоритет в группе, заданный разработчиком.
[
  {
    "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"] }
  },
]

Переадресация

В примере ниже требуется разрешение на доступ к хосту *://*.example.com/*.

В следующем примере показано, как перенаправить запрос с example.com на страницу в самом расширении. Путь к расширению /a.jpg разрешается в chrome-extension://EXTENSION_ID/a.jpg, где EXTENSION_ID – идентификатор расширения. Чтобы это работало, в манифесте нужно объявить /a.jpg как веб-ресурс.

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

В примере ниже ключ "transform" используется для перенаправления на субдомен example.com. Якорь доменного имени (||) позволяет перехватывать запросы с любой схемой из example.com. Ключ "scheme" в "transform" указывает, что для перенаправлений на субдомен всегда будет использоваться протокол HTTPS.

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

В примере ниже регулярные выражения используются для перенаправления с https://www.abc.xyz.com/path на https://abc.xyz.com/path. Обратите внимание, что в ключе "regexFilter" точки экранированы, а группа для извлечения подстроки выбирает "abc" или "def". Ключ "regexSubstitution" указывает на первое совпадение регулярного выражения с помощью "\1". В этом случае из URL переадресации извлекается значение abc и подставляется в URL.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

заголовки;

В следующем примере удаляются все файлы cookie как из основного фрейма, так и из всех дочерних фреймов.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Типы

DomainType

Этот параметр указывает, является ли запрос собственным или сторонним по отношению к фрейму, в котором он был создан. Запрос считается собственным, если он имеет тот же домен (eTLD+1), что и фрейм, в котором он был создан.

Перечисление

"firstParty"
Сетевой запрос является собственным для фрейма, в котором он был создан.

"thirdParty"
Сетевой запрос является сторонним по отношению к фрейму, в котором он был создан.

ExtensionActionOptions

Chrome 88 и более поздних версий;

Свойства

  • displayActionCountAsBadgeText

    Логическое значение (необязательно)

    Определяет, будет ли автоматически показываться количество действий на странице в виде текста на значке расширения. Этот параметр сохраняется между сеансами.

  • tabUpdate

    TabActionCountUpdate необязательный

    Chrome 89 и более поздних версий

    Сведения о том, как следует скорректировать количество действий на вкладке.

GetDisabledRuleIdsOptions

Chrome 111 и более поздних версий

Свойства

  • rulesetId

    string

    Идентификатор, соответствующий статическому объекту Ruleset.

GetRulesFilter

Chrome 111 и более поздних версий

Свойства

  • ruleIds

    number[] optional

    Если указано, включаются только правила с совпадающими идентификаторами.

HeaderInfo

Chrome 128 и более поздних версий

Свойства

  • excludedValues

    string[] необязательно

    Если условие задано, оно не выполняется, когда заголовок существует, но его значение содержит хотя бы один элемент из этого списка. Используется тот же синтаксис шаблона соответствия, что и в values.

  • заголовок

    string

    Название заголовка. Это условие соответствует названию, только если не указаны оба параметра: values и excludedValues.

  • values

    string[] необязательно

    Если указано, это условие выполняется, если значение заголовка соответствует хотя бы одному шаблону в этом списке. Поддерживается сопоставление значений заголовков без учета регистра, а также следующие конструкции:

    * – соответствует любому количеству символов.

    ? – соответствует нулю или одному символу.

    Символы "*" и "?" можно экранировать с помощью обратной косой черты, например "\*" и "\?".

HeaderOperation

Chrome 86 и более поздних версий.

Описывает возможные операции для правила modifyHeaders.

Перечисление

"append"
Добавляет новую запись для указанного заголовка. При изменении заголовков запроса эта операция поддерживается только для определенных заголовков.

set
Задает новое значение для указанного заголовка, удаляя все существующие заголовки с тем же названием.

"remove"
Удаляет все записи для указанного заголовка.

IsRegexSupportedResult

Chrome 87 и более поздних версий;

Свойства

  • isSupported

    Логическое значение

  • reason

    UnsupportedRegexReason необязательный

    Указывает причину, по которой регулярное выражение не поддерживается. Указывается, только если для параметра isSupported задано значение false.

MatchedRule

Свойства

  • ruleId

    число

    Идентификатор соответствующего правила.

  • rulesetId

    string

    Идентификатор Ruleset, к которому относится это правило. Для правила, созданного на основе набора динамических правил, это значение будет равно DYNAMIC_RULESET_ID.

MatchedRuleInfo

Свойства

  • правило

    MatchedRule

  • tabId

    число

    Идентификатор tabId вкладки, из которой поступил запрос, если она все ещё активна. В противном случае возвращается значение -1.

  • timeStamp

    число

    Время, когда было выполнено условие правила. Временные метки будут соответствовать соглашению JavaScript для времени, то есть количеству миллисекунд с начала эпохи.

MatchedRuleInfoDebug

Свойства

  • запрос

    RequestDetails

    Сведения о запросе, для которого было подобрано правило.

  • правило

    MatchedRule

MatchedRulesFilter

Свойства

  • minTimeStamp

    number (необязательно)

    Если указано, сопоставляются только правила после заданной временной метки.

  • tabId

    number (необязательно)

    Если указано, то сопоставляются только правила для заданной вкладки. Если задано значение -1, сопоставляет правила, не связанные ни с одной активной вкладкой.

ModifyHeaderInfo

Chrome 86 и более поздних версий.

Свойства

  • заголовок

    string

    Название заголовка, который нужно изменить.

  • операция

    HeaderOperation

    Операция, которую нужно выполнить с заголовком.

  • value

    Строка (необязательно)

    Новое значение заголовка. Обязательно для операций append и set.

QueryKeyValue

Свойства

  • клавиша

    string

  • replaceOnly

    Логическое значение (необязательно)

    Chrome 94 и более поздних версий;

    Если указано значение true, ключ запроса заменяется, только если он уже существует. В противном случае ключ также добавляется, если он отсутствует. Значение по умолчанию – false.

  • value

    string

QueryTransform

Свойства

  • addOrReplaceParams

    QueryKeyValue[] необязательный

    Список пар "ключ-значение" в запросе, которые нужно добавить или заменить.

  • removeParams

    string[] необязательно

    Список ключей запроса, которые нужно удалить.

Redirect

Свойства

  • extensionPath

    Строка (необязательно)

    Путь относительно каталога расширения. Должен начинаться с символа "/".

  • regexSubstitution

    Строка (необязательно)

    Шаблон замены для правил, в которых указано regexFilter. Первое совпадение с regexFilter в URL будет заменено этим шаблоном. В поле regexSubstitution можно использовать цифры, экранированные обратной косой чертой (от \1 до \9), чтобы вставить соответствующие группы для извлечения подстроки. \0 – весь совпадающий текст.

  • преобразование

    URLTransform необязательный

    Преобразования URL, которые нужно выполнить.

  • url

    Строка (необязательно)

    URL переадресации. Переадресация на URL JavaScript запрещена.

RegexOptions

Chrome 87 и более поздних версий;

Свойства

  • isCaseSensitive

    Логическое значение (необязательно)

    Учитывается ли регистр в указанном значении regex. Значение по умолчанию – true.

  • регулярное выражение

    string

    Регулярное выражение для проверки.

  • requireCapturing

    Логическое значение (необязательно)

    Указывает, требуется ли захват для указанного regex. Захват требуется только для правил переадресации, в которых указано действие regexSubstition. По умолчанию присваивается значение false.

RequestDetails

Свойства

  • documentId

    Строка (необязательно)

    Chrome 106 и более поздних версий.

    Уникальный идентификатор документа фрейма, если запрос предназначен для фрейма.

  • documentLifecycle

    DocumentLifecycle необязательно

    Chrome 106 и более поздних версий.

    Жизненный цикл документа фрейма, если запрос предназначен для фрейма.

  • frameId

    число

    Значение 0 указывает, что запрос происходит в основном фрейме, а положительное значение – идентификатор дочернего фрейма, в котором происходит запрос. Если загружен документ (суб)фрейма (type – это main_frame или sub_frame), frameId указывает идентификатор этого фрейма, а не внешнего. Идентификаторы фреймов уникальны в пределах вкладки.

  • frameType

    FrameType необязательный

    Chrome 106 и более поздних версий.

    Тип фрейма, если запрос предназначен для фрейма.

  • инициатор

    Строка (необязательно)

    Источник, из которого был инициирован запрос. Это не меняется при переадресации. Если источник непрозрачный, будет использоваться строка null.

  • method

    string

    Стандартный метод HTTP.

  • parentDocumentId

    Строка (необязательно)

    Chrome 106 и более поздних версий.

    Уникальный идентификатор родительского документа фрейма, если запрос предназначен для фрейма и у него есть родительский документ.

  • parentFrameId

    число

    Идентификатор фрейма, который содержит фрейм, отправивший запрос. Если родительского фрейма нет, задайте значение -1.

  • requestId

    string

    Идентификатор запроса. Идентификаторы запросов уникальны в рамках сеанса браузера.

  • tabId

    число

    Идентификатор вкладки, в которой выполняется запрос. Если запрос не связан с вкладкой, задайте значение -1.

  • тип

    ResourceType

    Тип ресурса запроса.

  • url

    string

    URL запроса.

RequestMethod

Chrome 91 и более поздних версий

Описывает метод HTTP-запроса для сетевого запроса.

Перечисление

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Описывает тип ресурса сетевого запроса.

Перечисление

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Свойства

  • действие

    RuleAction

    Действие, которое нужно выполнить, если правило сработало.

  • условие

    RuleCondition

    Условие, при котором срабатывает правило.

  • id

    число

    Идентификатор, который однозначно определяет правило. Обязательный параметр. Значение должно быть больше или равно 1.

  • приоритет

    number (необязательно)

    Приоритет правила. (значение по умолчанию – 1). Если указано, должно быть >= 1.

RuleAction

Свойства

  • Переадресация

    Переадресация необязательно

    Описывает, как должно выполняться перенаправление. Допустимо только для правил переадресации.

  • requestHeaders

    ModifyHeaderInfo[] необязательный

    Chrome 86 и более поздних версий.

    Заголовки запроса, которые нужно изменить. Допустимо, только если RuleActionType имеет значение modifyHeaders.

  • responseHeaders

    ModifyHeaderInfo[] необязательный

    Chrome 86 и более поздних версий.

    Заголовки ответа, которые нужно изменить для запроса. Допустимо, только если RuleActionType имеет значение modifyHeaders.

  • Тип действия, которое нужно выполнить.

RuleActionType

Описывает тип действия, которое необходимо выполнить, если заданное условие RuleCondition совпадает.

Перечисление

"block"
Блокировать сетевой запрос.

"redirect"
Перенаправляет сетевой запрос.

allow
Разрешить сетевой запрос. Запрос не будет перехвачен, если для него есть соответствующее разрешающее правило.

"upgradeScheme"
Заменить схему URL сетевого запроса на https, если в запросе используется http или ftp.

"modifyHeaders"
Изменение заголовков запроса или заголовков ответа из сетевого запроса.

"allowAllRequests"
Разрешить все запросы в иерархии фреймов, включая запрос самого фрейма.

RuleCondition

Свойства

  • domainType

    DomainType необязательный

    Указывает, является ли сетевой запрос собственным или сторонним для домена, из которого он поступил. Если этот параметр не указан, принимаются все запросы.

  • domains

    string[] необязательно

    Устарело в Chrome 101

    Используйте initiatorDomains

    Правило будет соответствовать только сетевым запросам, исходящим из списка domains.

  • excludedDomains

    string[] необязательно

    Устарело в Chrome 101

    Используйте excludedInitiatorDomains

    Правило не будет соответствовать сетевым запросам, исходящим из списка excludedDomains.

  • excludedInitiatorDomains

    string[] необязательно

    Chrome 101 и более поздних версий.

    Правило не будет соответствовать сетевым запросам, исходящим из списка excludedInitiatorDomains. Если список пустой или не задан, домены не исключаются. Это правило имеет приоритет над правилом initiatorDomains.

    Примечания

    • Субдомены, например a.example.com, также разрешены.
    • Записи должны состоять только из символов ASCII.
    • Для интернационализированных доменов используйте кодировку Punycode.
    • Сопоставление выполняется с инициатором запроса, а не с URL запроса.
    • Субдомены перечисленных доменов также исключаются.
  • excludedRequestDomains

    string[] необязательно

    Chrome 101 и более поздних версий.

    Правило не будет соответствовать сетевым запросам, если домены совпадают с одним из списка excludedRequestDomains. Если список пустой или не задан, домены не исключаются. Это правило имеет приоритет над правилом requestDomains.

    Примечания

    • Субдомены, например a.example.com, также разрешены.
    • Записи должны состоять только из символов ASCII.
    • Для интернационализированных доменов используйте кодировку Punycode.
    • Субдомены перечисленных доменов также исключаются.
  • excludedRequestMethods

    RequestMethod[] необязательный

    Chrome 91 и более поздних версий

    Список методов запроса, которые не соответствуют правилу. Можно указать только одно значение: requestMethods или excludedRequestMethods. Если не указан ни один из них, сопоставляются все методы запроса.

  • excludedResourceTypes

    ResourceType[] необязательный

    Список типов ресурсов, которым правило не будет соответствовать. Можно указать только одно значение: resourceTypes или excludedResourceTypes. Если не указан ни один из них, блокируются все типы ресурсов, кроме main_frame.

  • excludedResponseHeaders

    HeaderInfo[] optional

    Chrome 128 и более поздних версий

    Правило не применяется, если запрос соответствует любому условию заголовка ответа в этом списке (если указано). Если указаны оба свойства (excludedResponseHeaders и responseHeaders), то приоритет имеет excludedResponseHeaders.

  • excludedTabIds

    number[] optional

    Chrome 92 и более поздних версий;

    Список tabs.Tab.id, которым правило не должно соответствовать. Идентификатор tabs.TAB_ID_NONE исключает запросы, которые не поступают из вкладки. Поддерживается только для правил на уровне сеанса.

  • excludedTopDomains

    string[] необязательно

    Chrome 145+

    Правило не будет сопоставлять сетевые запросы, если домен связанного фрейма верхнего уровня совпадает с одним из доменов в списке excludedTopDomains. Если список пустой или не задан, домены не исключаются. Это правило имеет приоритет над правилом topDomains.

    Примечания

    • Субдомены, например a.example.com, также разрешены.
    • Записи должны состоять только из символов ASCII.
    • Для интернационализированных доменов используйте кодировку Punycode.
    • Субдомены перечисленных доменов также исключаются.
    • Для запросов, не связанных с фреймом верхнего уровня (например, запросов, инициированных ServiceWorker), вместо этого учитывается домен инициатора запроса.
  • initiatorDomains

    string[] необязательно

    Chrome 101 и более поздних версий.

    Правило будет соответствовать только сетевым запросам, исходящим из списка initiatorDomains. Если список не указан, правило применяется к запросам из всех доменов. Список не может быть пустым.

    Примечания

    • Субдомены, например a.example.com, также разрешены.
    • Записи должны состоять только из символов ASCII.
    • Для интернационализированных доменов используйте кодировку Punycode.
    • Сопоставление выполняется с инициатором запроса, а не с URL запроса.
    • Субдомены перечисленных доменов также сопоставляются.
  • isUrlFilterCaseSensitive

    Логическое значение (необязательно)

    Учитывается ли регистр в urlFilter или regexFilter (в зависимости от того, что указано). Значение по умолчанию – false.

  • regexFilter

    Строка (необязательно)

    Регулярное выражение для сопоставления с URL сетевого запроса. используя синтаксис RE2.

    Примечание. Можно указать только одно значение: urlFilter или regexFilter.

    Примечание. regexFilter должен состоять только из символов ASCII. Сопоставление выполняется с URL, в котором хост закодирован в формате Punycode (для интернационализованных доменов), а все остальные символы, не входящие в набор ASCII, закодированы в UTF-8.

  • requestDomains

    string[] необязательно

    Chrome 101 и более поздних версий.

    Правило будет соответствовать только сетевым запросам, домен которых совпадает с одним из доменов в списке requestDomains. Если список не указан, правило применяется к запросам из всех доменов. Список не может быть пустым.

    Примечания

    • Субдомены, например a.example.com, также разрешены.
    • Записи должны состоять только из символов ASCII.
    • Для интернационализированных доменов используйте кодировку Punycode.
    • Субдомены перечисленных доменов также сопоставляются.
  • requestMethods

    RequestMethod[] необязательный

    Chrome 91 и более поздних версий

    Список методов HTTP-запросов, которым может соответствовать правило. Список не может быть пустым.

    Примечание. Если вы укажете условие правила requestMethods, то запросы, не относящиеся к HTTP(S), также будут исключены. Если же вы укажете условие excludedRequestMethods, то этого не произойдет.

  • resourceTypes

    ResourceType[] необязательный

    Список типов ресурсов, которым может соответствовать правило. Список не может быть пустым.

    Примечание. Это значение необходимо указать для правил allowAllRequests. Оно может включать только типы ресурсов sub_frame и main_frame.

  • responseHeaders

    HeaderInfo[] optional

    Chrome 128 и более поздних версий

    Правило применяется, если запрос соответствует любому условию заголовка ответа в этом списке (если указано).

  • tabIds

    number[] optional

    Chrome 92 и более поздних версий;

    Список tabs.Tab.id, которым должно соответствовать правило. Идентификатор tabs.TAB_ID_NONE соответствует запросам, которые не поступают из вкладки. Список не может быть пустым. Поддерживается только для правил на уровне сеанса.

  • topDomains

    string[] необязательно

    Chrome 145+

    Правило будет сопоставлять сетевые запросы, только если домен связанного фрейма верхнего уровня совпадает с одним из доменов в списке topDomains. Если список не указан, правило применяется к запросам, связанным со всеми доменами фреймов верхнего уровня. Список не может быть пустым.

    Примечания

    • Субдомены, например a.example.com, также разрешены.
    • Записи должны состоять только из символов ASCII.
    • Для интернационализированных доменов используйте кодировку Punycode.
    • Субдомены перечисленных доменов также сопоставляются.
    • Для запросов, не связанных с фреймом верхнего уровня (например, запросов, инициированных ServiceWorker), вместо этого учитывается домен инициатора запроса.
  • urlFilter

    Строка (необязательно)

    Шаблон, который сопоставляется с URL сетевого запроса. Поддерживаемые конструкции:

    * – подстановочный знак, соответствующий любому количеству символов.

    | – левый/правый якорь. Если этот символ используется в начале или конце шаблона, он указывает на начало или конец URL соответственно.

    || – якорь доменного имени. Если он используется в начале шаблона, то указывает на начало домена или субдомена в URL.

    ^ – разделитель. Соответствует любому символу, кроме букв, цифр и следующих знаков: _, -, . и %. Это также соответствует концу URL.

    Таким образом, urlFilter состоит из следующих частей: (необязательный левый якорь или якорь доменного имени) + шаблон + (необязательный правый якорь).

    Если он не указан, сопоставляются все URL. Пустая строка не допускается.

    Шаблон не может начинаться с ||*. Вместо нее следует использовать *.

    Примечание. Можно указать только одно значение: urlFilter или regexFilter.

    Примечание. urlFilter должен состоять только из символов ASCII. Сопоставление выполняется с URL, в котором хост закодирован в формате Punycode (для интернационализованных доменов), а все остальные символы, не входящие в набор ASCII, закодированы в UTF-8. Например, если URL запроса – http://abc.рф?q=ф, то urlFilter будет сопоставляться с URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145+

Перечисление

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Свойства

  • включено

    Логическое значение

    Включен ли набор правил по умолчанию.

  • id

    string

    Непустая строка, уникально идентифицирующая набор правил. Идентификаторы, начинающиеся с символа подчеркивания, зарезервированы для внутреннего использования.

  • путь

    string

    Путь к набору правил JSON относительно каталога расширения.

RulesMatchedDetails

Свойства

  • rulesMatchedInfo

    MatchedRuleInfo[]

    Правила, соответствующие заданному фильтру.

TabActionCountUpdate

Chrome 89 и более поздних версий;

Свойства

  • больше

    число

    Значение, на которое увеличивается количество действий на вкладке. Отрицательные значения уменьшают количество.

  • tabId

    число

    Вкладка, для которой нужно обновить количество действий.

TestMatchOutcomeResult

Chrome 103 и более поздних версий;

Свойства

  • matchedRules

    MatchedRule[]

    Правила (если есть), которые соответствуют гипотетическому запросу.

TestMatchRequestDetails

Chrome 103 и более поздних версий;

Свойства

  • инициатор

    Строка (необязательно)

    URL инициатора (если есть) для гипотетического запроса.

  • method

    RequestMethod необязательный

    Стандартный метод HTTP гипотетического запроса. По умолчанию для HTTP-запросов используется значение "get". Для запросов, не относящихся к HTTP, этот параметр игнорируется.

  • responseHeaders

    Объект (необязательно)

    Chrome 129 и более поздних версий

    Заголовки, которые будут предоставлены гипотетическим ответом, если запрос не будет заблокирован или перенаправлен до отправки. Представлен в виде объекта, который сопоставляет название заголовка со списком строковых значений. Если не указать этот параметр, гипотетический ответ будет возвращать пустые заголовки, которые могут соответствовать правилам, проверяющим отсутствие заголовков. Пример: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number (необязательно)

    Идентификатор вкладки, в которой выполняется гипотетический запрос. Не обязательно должен соответствовать идентификатору реальной вкладки. Значение по умолчанию – -1, что означает, что запрос не связан с вкладкой.

  • topUrl

    Строка (необязательно)

    Chrome 145+

    URL фрейма верхнего уровня, связанного с запросом (если есть).

  • тип

    ResourceType

    Тип ресурса гипотетического запроса.

  • url

    string

    URL гипотетического запроса.

UnsupportedRegexReason

Chrome 87 и более поздних версий;

Описывает причину, по которой регулярное выражение не поддерживается.

Перечисление

"syntaxError"
Регулярное выражение содержит синтаксическую ошибку или использует функции, недоступные в синтаксисе RE2.

"memoryLimitExceeded"
Регулярное выражение превышает лимит памяти.

UpdateRuleOptions

Chrome 87 и более поздних версий;

Свойства

  • addRules

    Rule[] необязательный

    Правила, которые нужно добавить.

  • removeRuleIds

    number[] optional

    Идентификаторы правил, которые нужно удалить. Недействительные идентификаторы будут игнорироваться.

UpdateRulesetOptions

Chrome 87 и более поздних версий;

Свойства

  • disableRulesetIds

    string[] необязательно

    Набор идентификаторов, соответствующих статическому Ruleset, который нужно отключить.

  • enableRulesetIds

    string[] необязательно

    Набор идентификаторов, соответствующих статическому Ruleset, который нужно включить.

UpdateStaticRulesOptions

Chrome 111 и более поздних версий

Свойства

  • disableRuleIds

    number[] optional

    Набор идентификаторов, соответствующих правилам в Ruleset, которые нужно отключить.

  • enableRuleIds

    number[] optional

    Набор идентификаторов, соответствующих правилам в Ruleset, которые нужно включить.

  • rulesetId

    string

    Идентификатор, соответствующий статическому объекту Ruleset.

URLTransform

Свойства

  • fragment

    Строка (необязательно)

    Новый фрагмент для запроса. Должен быть пустым (в этом случае существующий фрагмент удаляется) или начинаться с символа "#".

  • хост

    Строка (необязательно)

    Новый хост для запроса.

  • пароль

    Строка (необязательно)

    Новый пароль для запроса.

  • путь

    Строка (необязательно)

    Новый путь для запроса. Если поле пустое, существующий путь будет удален.

  • порт

    Строка (необязательно)

    Новый порт для запроса. Если оставить поле пустым, существующий порт будет удален.

  • запрос

    Строка (необязательно)

    Новый запрос. Должен быть пустым (в этом случае существующий запрос удаляется) или начинаться с символа "?".

  • queryTransform

    QueryTransform необязательный

    Добавление, удаление или замена пар "ключ-значение" в запросе.

  • схема

    Строка (необязательно)

    Новая схема для запроса. Допустимые значения: http, https, ftp и chrome-extension.

  • имя пользователя

    Строка (необязательно)

    Новое имя пользователя для запроса.

Свойства

DYNAMIC_RULESET_ID

Идентификатор набора правил для динамических правил, добавленных расширением.

Значение

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Интервал времени в минутах, в течение которого можно совершать звонки в MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules. Дополнительные вызовы будут сразу же отклоняться с ошибкой runtime.lastError. Примечание. Вызовы getMatchedRules, связанные с жестом пользователя, не учитываются в квоте.

Значение

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 и более поздних версий;

Минимальное количество статических правил, гарантированное расширению во всех его включенных наборах статических правил. Правила сверх этого лимита будут учитываться в общем лимите на статические правила.

Значение

30 000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Количество вызовов getMatchedRules за период GETMATCHEDRULES_QUOTA_INTERVAL.

Значение

20

MAX_NUMBER_OF_DYNAMIC_RULES

Максимальное количество динамических правил, которые может добавить расширение.

Значение

30 000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 и более поздних версий;

Максимальное количество статических Rulesets, которые расширение может включить одновременно.

Значение

50

MAX_NUMBER_OF_REGEX_RULES

Максимальное количество правил регулярных выражений, которые может добавить расширение. Это ограничение применяется отдельно к набору динамических правил и к правилам, указанным в файле ресурсов.

Значение

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 и более поздних версий

Максимальное количество правил в области действия сеанса, которые может добавить расширение.

Значение

5000

MAX_NUMBER_OF_STATIC_RULESETS

Максимальное количество статических Rulesets, которое расширение может указать в ключе манифеста "rule_resources".

Значение

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 и более поздних версий

Максимальное количество "небезопасных" динамических правил, которые может добавить расширение.

Значение

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 и более поздних версий

Максимальное количество "небезопасных" правил на уровне сеанса, которые может добавить расширение.

Значение

5000

SESSION_RULESET_ID

Chrome 90 и более поздних версий

Идентификатор набора правил для правил на уровне сеанса, добавленных расширением.

Значение

"_session"

Методы

getAvailableStaticRuleCount()

Promise Chrome 89 и более поздние версии 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
): Promise<number>

Возвращает количество статических правил, которые расширение может включить до достижения общего ограничения на статические правила.

Параметры

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (count: number) => void

    • количество

      число

Возвраты

  • Promise<number>

    Chrome 91 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getDisabledRuleIds()

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

Возвращает список статических правил в заданном Ruleset, которые в настоящее время отключены.

Параметры

  • Параметры

    GetDisabledRuleIdsOptions

    Указывает набор правил для запроса.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Возвраты

  • Promise<number[]>

    Promise, который разрешается со списком идентификаторов, соответствующих отключенным правилам в этом наборе правил.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getDynamicRules()

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

Возвращает текущий набор динамических правил для расширения. При необходимости можно отфильтровать список полученных правил, указав filter.

Параметры

  • фильтр

    GetRulesFilter необязательный

    Chrome 111 и более поздних версий

    Объект для фильтрации списка полученных правил.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (rules: Rule[]) => void

    • правила

      Rule[]

Возвраты

  • Promise<Rule[]>

    Chrome 91 и более поздних версий

    Promise, который разрешается с набором динамических правил. Объект Promise может быть отклонен в случае временных внутренних ошибок.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getEnabledRulesets()

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

Возвращает идентификаторы для текущего набора включенных статических наборов правил.

Параметры

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

Возвраты

  • Promise<string[]>

    Chrome 91 и более поздних версий

    Объект Promise, который распознается как список идентификаторов, где каждый идентификатор соответствует включенному статическому Ruleset.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getMatchedRules()

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

Возвращает все правила, соответствующие расширению. Вызывающие абоненты могут отфильтровать список сопоставленных правил, указав filter. Этот метод доступен только для расширений с разрешением "declarativeNetRequestFeedback" или с разрешением "activeTab", предоставленным для tabId, указанного в filter. Примечание. Правила, не связанные с активным документом, которые были сопоставлены более пяти минут назад, не будут возвращены.

Параметры

  • фильтр

    MatchedRulesFilter необязательно

    Объект для фильтрации списка сопоставленных правил.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (details: RulesMatchedDetails) => void

Возвраты

  • Chrome 91 и более поздних версий

    Объект Promise, который разрешается после получения списка сопоставленных правил. В случае ошибки объект Promise будет отклонен. Это может произойти по разным причинам, например из-за недостаточных разрешений или превышения квоты.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getSessionRules()

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

Возвращает текущий набор правил для расширения в рамках сеанса. При необходимости можно отфильтровать список полученных правил, указав filter.

Параметры

  • фильтр

    GetRulesFilter необязательный

    Chrome 111 и более поздних версий

    Объект для фильтрации списка полученных правил.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (rules: Rule[]) => void

Возвраты

  • Promise<Rule[]>

    Chrome 91 и более поздних версий

    Promise, который разрешается с набором правил на уровне сеанса.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

isRegexSupported()

Promise Chrome 87 и более поздние версии 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

Проверяет, будет ли заданное регулярное выражение поддерживаться в качестве условия правила regexFilter.

Параметры

  • regexOptions

    RegexOptions

    Регулярное выражение для проверки.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (result: IsRegexSupportedResult) => void

Возвраты

  • Chrome 91 и более поздних версий

    Объект Promise, который возвращает сведения о том, поддерживается ли регулярное выражение, и причину, если оно не поддерживается.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

setExtensionActionOptions()

Promise Chrome 88 и более поздних версий 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): Promise<void>

Определяет, должно ли количество действий для вкладок отображаться в виде текста на значке действия расширения, и позволяет увеличивать это количество.

Параметры

  • Параметры

    ExtensionActionOptions

  • обратный вызов

    function необязательно

    Chrome 89 и более поздних версий;

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 91 и более поздних версий

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

testMatchOutcome()

Promise Chrome 103 и более поздних версий 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

Проверяет, соответствует ли какое-либо из правил declarativeNetRequest расширения гипотетическому запросу. Примечание. Этот параметр доступен только для распакованных расширений, так как он предназначен для использования во время разработки расширения.

Параметры

Возвраты

  • Promise, который разрешается с подробными сведениями о сопоставленных правилах.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

updateDynamicRules()

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

Изменяет текущий набор динамических правил для расширения. Сначала удаляются правила с идентификаторами, указанными в options.removeRuleIds, а затем добавляются правила, указанные в options.addRules. Примечания

  • Это обновление выполняется как единая атомарная операция: либо все указанные правила добавляются и удаляются, либо возвращается ошибка.
  • Эти правила сохраняются между сеансами браузера и обновлениями расширений.
  • Статические правила, указанные в пакете расширения, нельзя удалить с помощью этой функции.
  • MAX_NUMBER_OF_DYNAMIC_RULES – максимальное количество динамических правил, которые может добавить расширение. Количество небезопасных правил не должно превышать MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Параметры

  • Параметры

    UpdateRuleOptions

    Chrome 87 и более поздних версий;
  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 91 и более поздних версий

    Обещание, которое выполняется после завершения обновления. В случае ошибки обещание будет отклонено, а набор правил останется без изменений. Это может произойти по разным причинам, например из-за недопустимого формата правила, повторяющегося идентификатора правила, превышения лимита на количество правил, внутренних ошибок и т. д.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

updateEnabledRulesets()

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

Обновляет набор включенных статических наборов правил для расширения. Сначала удаляются наборы правил с идентификаторами, указанными в options.disableRulesetIds, а затем добавляются наборы правил, указанные в options.enableRulesetIds. Обратите внимание, что набор включенных статических наборов правил сохраняется между сеансами, но не между обновлениями расширений. Это значит, что ключ манифеста rule_resources будет определять набор включенных статических наборов правил при каждом обновлении расширения.

Параметры

  • Параметры

    UpdateRulesetOptions

    Chrome 87 и более поздних версий;
  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 91 и более поздних версий

    Обещание, которое выполняется после завершения обновления. В случае ошибки обещание будет отклонено, а набор включенных наборов правил останется без изменений. Это может произойти по разным причинам, например из-за недействительных идентификаторов наборов правил, превышения лимита на количество правил или внутренних ошибок.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

updateSessionRules()

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

Изменяет текущий набор правил для расширения в рамках сеанса. Сначала удаляются правила с идентификаторами, указанными в options.removeRuleIds, а затем добавляются правила, указанные в options.addRules. Примечания

  • Это обновление выполняется как единая атомарная операция: либо все указанные правила добавляются и удаляются, либо возвращается ошибка.
  • Эти правила не сохраняются между сеансами и хранятся в памяти.
  • MAX_NUMBER_OF_SESSION_RULES – максимальное количество правил сеанса, которое может добавить расширение.

Параметры

  • Параметры

    UpdateRuleOptions

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 91 и более поздних версий

    Обещание, которое выполняется после завершения обновления. В случае ошибки обещание будет отклонено, а набор правил останется без изменений. Это может произойти по разным причинам, например из-за недопустимого формата правила, повторяющегося идентификатора правила, превышения лимита на количество правил и т. д.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

updateStaticRules()

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

Отключает и включает отдельные статические правила в Ruleset. Изменения в правилах, относящихся к отключенному Ruleset, вступят в силу при следующем включении.

Параметры

  • Параметры

    UpdateStaticRulesOptions

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Обещание, которое выполняется после завершения обновления. В случае ошибки обещание будет отклонено, а включенные статические правила останутся без изменений.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onRuleMatchedDebug

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

Срабатывает, когда правило соответствует запросу. Доступно только для распакованных расширений с разрешением "declarativeNetRequestFeedback", поскольку предназначено только для отладки.

Параметры