chrome.declarativeNetRequest

refresh date: 2026-09-25 robots: noindex

Descrição

A API chrome.declarativeNetRequest é usada para bloquear ou modificar solicitações de rede especificando regras declarativas. Isso permite que as extensões modifiquem as solicitações de rede sem interceptá-las e visualizar o conteúdo, oferecendo mais privacidade.

Permissões

declarativeNetRequest
declarativeNetRequestWithHostAccess

declarativeNetRequestFeedback
host_permissions

Uma ou mais dessas permissões acionam um aviso. As permissões `declarativeNetRequest` e `declarativeNetRequestWithHostAccess` oferecem os mesmos recursos, e ambas exigem permissões de host. No entanto, a segunda evita avisos de permissão de host.

Disponibilidade

Chrome 84 ou mais recente

Manifesto

Além das permissões descritas acima, certos tipos de conjuntos de regras, especificamente os estáticos, exigem a declaração da chave de manifesto "declarative_net_request", que precisa ser um dicionário com uma única chave chamada "rule_resources". Essa chave é uma matriz que contém dicionários do tipo Ruleset, conforme mostrado abaixo. O nome "Ruleset" não aparece no JSON do manifesto porque é apenas uma matriz. Os conjuntos de regras estáticos são explicados mais adiante neste documento.

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

Conceitos e uso

Para usar essa API, especifique um ou mais conjuntos de regras. Um conjunto de regras contém uma matriz de regras. Uma única regra faz o seguinte:

• Bloquear uma solicitação de rede.
• Faça upgrade do esquema (http para https).
• Impedir que uma solicitação seja bloqueada ao negar qualquer regra de bloqueio correspondente.
• Redirecionar uma solicitação de rede.
• Modificar cabeçalhos de solicitação ou resposta.

Há três tipos de conjuntos de regras, gerenciados de maneiras ligeiramente diferentes.

Dinâmico

Persistem em sessões do navegador e upgrades de extensão e são gerenciados usando JavaScript enquanto uma extensão está em uso.

Sessão

Limpo quando o navegador é fechado e quando uma nova versão da extensão é instalada. As regras de sessão são gerenciadas usando JavaScript enquanto uma extensão está em uso.

Estático

Empacotado, instalado e atualizado quando uma extensão é instalada ou atualizada. As regras estáticas são armazenadas em arquivos de regras formatados em JSON e listadas no arquivo de manifesto.

As próximas seções explicam os tipos de conjunto de regras em detalhes.

Conjuntos de regras dinâmicos e no escopo da sessão

Os conjuntos de regras dinâmicas e de sessão são gerenciados usando JavaScript enquanto uma extensão está em uso.

• As regras dinâmicas persistem entre as sessões do navegador e as atualizações de extensão.
• As regras de sessão são apagadas quando o navegador é fechado e quando uma nova versão da extensão é instalada.

Há apenas um de cada tipo de conjunto de regras. Uma extensão pode adicionar ou remover regras dinamicamente chamando updateDynamicRules() e updateSessionRules(), desde que os limites de regras não sejam excedidos. Para mais informações sobre limites de regras, consulte Limites de regras. Confira um exemplo disso em exemplos de código.

Conjuntos de regras estáticos

Ao contrário das regras dinâmicas e de sessão, as regras estáticas são empacotadas, instaladas e atualizadas quando uma extensão é instalada ou atualizada. Elas são armazenadas em arquivos de regras no formato JSON, que são indicados para a extensão usando as chaves "declarative_net_request" e "rule_resources", conforme descrito acima, além de um ou mais dicionários Ruleset. Um dicionário Ruleset contém um caminho para o arquivo de regras, um ID para o conjunto de regras contido no arquivo e se o conjunto de regras está ativado ou desativado. Os dois últimos são importantes quando você ativa ou desativa um conjunto de regras de forma programática.

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

Para testar arquivos de regras, carregue a extensão descompactada. Os erros e avisos sobre regras estáticas inválidas só são exibidos para extensões descompactadas. As regras estáticas inválidas em extensões compactadas são ignoradas.

Ativar e desativar regras e conjuntos de regras estáticos

Tanto as regras estáticas individuais quanto os conjuntos de regras estáticas completos podem ser ativados ou desativados no ambiente de execução.

O conjunto de regras e conjuntos de regras estáticos ativados é mantido em todas as sessões do navegador. Nenhum deles é mantido após as atualizações da extensão, o que significa que apenas as regras que você escolheu deixar nos arquivos de regras estarão disponíveis após uma atualização.

Por motivos de desempenho, também há limites para o número de regras e conjuntos de regras que podem ser ativados ao mesmo tempo. Chame getAvailableStaticRuleCount() para verificar o número de regras adicionais que podem ser ativadas. Para mais informações sobre limites de regras, consulte Limites de regras.

Para ativar ou desativar regras estáticas, chame updateStaticRules(). Esse método usa um objeto UpdateStaticRulesOptions, que contém matrizes de IDs de regras para ativar ou desativar. Os IDs são definidos usando a chave "id" do dicionário Ruleset.

Para ativar ou desativar conjuntos de regras estáticos, chame updateEnabledRulesets(). Esse método usa um objeto UpdateRulesetOptions, que contém matrizes de IDs de conjuntos de regras para ativar ou desativar. Os IDs são definidos usando a chave "id" do dicionário Ruleset.

Regras de build

Independentemente do tipo, uma regra começa com quatro campos, conforme mostrado abaixo. Enquanto as chaves "id" e "priority" usam um número, as chaves "action" e "condition" podem fornecer várias condições de bloqueio e redirecionamento. A regra a seguir bloqueia todas as solicitações de script originadas de "foo.com" para qualquer URL com "abc" como uma substring.

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

Caracteres de correspondência de urlFilter

A chave "condition" de uma regra permite que uma chave "urlFilter" atue em URLs em um domínio especificado. Você cria padrões usando tokens de correspondência de padrões. Confira alguns exemplos abaixo.

urlFilter	Correspondências	Não corresponde
"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

Priorização de regras

As regras são acionadas por solicitações enviadas de páginas da Web. Se várias regras corresponderem a uma solicitação específica, elas precisarão ser priorizadas. Esta seção explica como elas são priorizadas. A priorização acontece em duas etapas.

1. A prioridade é determinada para regras dentro de uma extensão.
2. Se mais de uma extensão puder aplicar uma regra a uma solicitação, a prioridade será determinada para todas as extensões que corresponderem a uma solicitação específica.

Pense na correspondência da seguinte forma: qualquer regra que uma extensão específica priorize será priorizada em relação às regras de outras extensões.

Atenção: evite escrever regras com a mesma ação e prioridade que precisam ser executadas em uma ordem específica. As regras com a mesma ação e prioridade (por exemplo, regras de redirecionamento com prioridade 1) são executadas em uma ordem arbitrária que não é definida e pode mudar entre as execuções ou versões do navegador, mesmo quando distribuídas entre vários tipos de conjunto de regras (por exemplo, uma regra estática e uma regra de sessão). Isso acontece em todos os navegadores.

Priorização de regras em uma extensão

Em uma única extensão, a priorização é definida usando o seguinte processo:

1. A regra com a maior prioridade definida pelo desenvolvedor (ou seja, o campo "priority") é retornada.

2. Se houver mais de uma regra com a prioridade mais alta definida pelo desenvolvedor, as regras serão priorizadas usando o campo "action", na seguinte ordem:

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

3. Se o tipo de ação não for block ou redirect, todas as regras modifyHeaders correspondentes serão avaliadas. Se houver regras com uma prioridade definida pelo desenvolvedor menor do que a prioridade especificada para allow e allowAllRequests, elas serão ignoradas.

4. Se várias regras modificarem o mesmo cabeçalho, a modificação será determinada pelo campo "priority" definido pelo desenvolvedor e pelas operações especificadas.

   • Se uma regra adicionar ao final de um cabeçalho, as regras de prioridade mais baixa só poderão adicionar ao final desse cabeçalho. Não é permitido definir e remover operações.
   • Se uma regra definir um cabeçalho, as regras de prioridade mais baixa só poderão ser anexadas a esse cabeçalho. Nenhuma outra modificação é permitida.
   • Se uma regra remover um cabeçalho, as regras de prioridade mais baixa não poderão mais modificá-lo.

Priorização de regras entre extensões

Se apenas uma extensão tiver uma regra que corresponda a uma solicitação, essa regra será aplicada. No entanto, se mais de uma extensão corresponder a uma solicitação, o seguinte processo será usado:

1. As regras são priorizadas usando o campo "action", na seguinte ordem:

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

2. Se mais de uma regra corresponder, a extensão instalada mais recentemente terá prioridade.

Limites das regras

Há uma sobrecarga de desempenho para carregar e avaliar regras no navegador. Por isso, alguns limites se aplicam ao usar a API. Os limites dependem do tipo de regra que você está usando.

Regras estáticas

As regras estáticas são aquelas especificadas em arquivos de regras declarados no arquivo de manifesto. Uma extensão pode especificar até 50 conjuntos de regras estáticos como parte da chave de manifesto "rule_resources", mas apenas 10 desses conjuntos podem ser ativados por vez. O último é chamado de MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Coletivamente, esses conjuntos de regras têm pelo menos 30.000 regras garantidas. Isso é chamado de GUARANTEED_MINIMUM_STATIC_RULES.

O número de regras disponíveis depois disso depende de quantas regras estão ativadas por todas as extensões instaladas no navegador de um usuário. Para encontrar esse número no ambiente de execução, chame getAvailableStaticRuleCount(). Confira um exemplo disso em exemplos de código.

Regras dinâmicas e de sessão

Os limites aplicados às regras dinâmicas e de sessão são mais simples do que as regras estáticas. O número total de ambos não pode exceder 5.000. Isso é chamado de MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

Regras que usam regex

Todos os tipos de regras podem usar expressões regulares. No entanto, o número total de regras de regex de cada tipo não pode exceder 1.000. Isso é chamado de MAX_NUMBER_OF_REGEX_RULES.

Além disso, cada regra precisa ter menos de 2 KB depois de compilada. Isso se correlaciona aproximadamente com a complexidade da regra. Se você tentar carregar uma regra que exceda esse limite, vai aparecer um aviso como o abaixo, e a regra será ignorada.

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

Interações com service workers

Uma declarativeNetRequest só se aplica a solicitações que chegam à pilha de rede. Isso inclui respostas do cache HTTP, mas pode não incluir respostas que passam pelo gerenciador onfetch de um service worker. A declarativeNetRequest não afeta as respostas geradas pelo service worker ou recuperadas de CacheStorage, mas afeta as chamadas para fetch() feitas em um service worker.

Recursos acessíveis pela Web

Uma regra declarativeNetRequest não pode redirecionar uma solicitação de recurso público para um recurso que não seja acessível pela Web. Isso aciona um erro. Isso é válido mesmo que o recurso acessível pela Web especificado seja de propriedade da extensão de redirecionamento. Para declarar recursos para declarativeNetRequest, use a matriz "web_accessible_resources" do manifesto.

Exemplos

Exemplos de código

Atualizar regras dinâmicas

O exemplo a seguir mostra como chamar updateDynamicRules(). O procedimento para updateSessionRules() é o mesmo.

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

Atualizar conjuntos de regras estáticos

O exemplo a seguir mostra como ativar e desativar conjuntos de regras considerando o número de conjuntos de regras estáticos disponíveis e o número máximo de conjuntos de regras estáticos ativados. Isso é feito quando o número de regras estáticas necessárias excede o número permitido. Para que isso funcione, alguns dos seus conjuntos de regras precisam ser instalados com alguns deles desativados (definindo "Enabled" como false no arquivo de manifesto).

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

Exemplos de regras

Os exemplos abaixo mostram como o Chrome prioriza as regras em uma extensão. Ao analisá-las, talvez seja útil abrir as regras de priorização em uma janela separada.

A chave "priority"

Esses exemplos exigem permissão de host para *://*.example.com/*.

Para determinar a prioridade de um URL específico, consulte as chaves "priority" (definida pelo desenvolvedor), "action" e "urlFilter". Esses exemplos se referem ao arquivo de regra de exemplo mostrado abaixo deles.

Navegação para https://google.com

Duas regras cobrem esse URL: as regras com os IDs 1 e 4. A regra com o ID 1 é aplicada porque as ações "block" têm uma prioridade maior do que as ações "redirect". As regras restantes não se aplicam porque são para URLs mais longos.

Navegação para https://google.com/1234

Devido ao URL mais longo, a regra com o ID 2 agora corresponde, além das regras com os IDs 1 e 4. A regra com ID 2 é aplicada porque "allow" tem uma prioridade maior que "block" e "redirect".

Navegação para https://google.com/12345

As quatro regras correspondem a esse URL. A regra com o ID 3 é aplicada porque a prioridade definida pelo desenvolvedor é a mais alta do grupo.

[
  {
    "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"] }
  },
]

Redirecionamentos

O exemplo abaixo requer permissão de host para *://*.example.com/*.

O exemplo a seguir mostra como redirecionar uma solicitação de example.com para uma página dentro da própria extensão. O caminho da extensão /a.jpg é resolvido como chrome-extension://EXTENSION_ID/a.jpg, em que EXTENSION_ID é o ID da extensão. Para que isso funcione, o manifesto precisa declarar /a.jpg como um recurso acessível pela Web.

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

O exemplo a seguir usa a chave "transform" para redirecionar para um subdomínio de example.com. Ele usa uma âncora de nome de domínio ("||") para interceptar solicitações com qualquer esquema de example.com. A chave "scheme" em "transform" especifica que os redirecionamentos para o subdomínio sempre usarão "https".

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

O exemplo a seguir usa expressões regulares para redirecionar de https://www.abc.xyz.com/path para https://abc.xyz.com/path. Na chave "regexFilter", observe como os pontos são escapados e que o grupo de captura seleciona "abc" ou "def". A chave "regexSubstitution" especifica a primeira correspondência retornada da expressão regular usando "\1". Nesse caso, "abc" é capturado do URL redirecionado e colocado na substituição.

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

Cabeçalhos

O exemplo a seguir remove todos os cookies de um frame principal e de todos os subframes.

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

Tipos

DomainType

Descreve se a solicitação é própria ou de terceiros para o frame em que foi originada. Uma solicitação é considerada própria se tiver o mesmo domínio (eTLD+1) do frame em que ela foi originada.

Enumeração

"firstParty"
A solicitação de rede é própria do frame em que foi originada.

"thirdParty"
A solicitação de rede é de terceiros para o frame em que foi originada.

ExtensionActionOptions

Chrome 88+

Propriedades

• displayActionCountAsBadgeText

  booleano opcional

  Se a contagem de ações de uma página deve ser mostrada automaticamente como o texto do selo da extensão. Essa preferência é mantida entre as sessões.

• tabUpdate

  TabActionCountUpdate opcional

  Chrome 89+

  Detalhes de como a contagem de ações da guia deve ser ajustada.

GetDisabledRuleIdsOptions

Chrome 111+

Propriedades

• rulesetId

  string

  O ID correspondente a um Ruleset estático.

GetRulesFilter

Chrome 111+

Propriedades

• ruleIds

  number[] opcional

  Se especificado, somente as regras com IDs correspondentes serão incluídas.

HeaderInfo

Chrome 128+

Propriedades

• excludedValues

  string[] opcional

  Se especificada, essa condição não será correspondida se o cabeçalho existir, mas o valor dele tiver pelo menos um elemento nessa lista. Isso usa a mesma sintaxe de padrão de correspondência que values.

• cabeçalho

  string

  O nome do cabeçalho. Essa condição só vai corresponder ao nome se values e excludedValues não forem especificados.

• values

  string[] opcional

  Se especificada, essa condição será atendida se o valor do cabeçalho corresponder a pelo menos um padrão nessa lista. Isso é compatível com a correspondência de valores de cabeçalho que não diferencia maiúsculas de minúsculas, além das seguintes construções:

  '*' : corresponde a qualquer número de caracteres.

  ? : corresponde a zero ou um caractere.

  "*" e "?" podem ser escapados com uma barra invertida, por exemplo, "\*" e "\?"

HeaderOperation

Chrome 86+

Descreve as operações possíveis para uma regra "modifyHeaders".

Enumeração

"append"
Adiciona uma nova entrada para o cabeçalho especificado. Ao modificar os cabeçalhos de uma solicitação, essa operação só é compatível com cabeçalhos específicos.

"set"
Define um novo valor para o cabeçalho especificado, removendo todos os cabeçalhos com o mesmo nome.

"remove"
Remove todas as entradas do cabeçalho especificado.

IsRegexSupportedResult

Chrome 87 ou mais recente

Propriedades

• isSupported

  booleano

• reason

  UnsupportedRegexReason opcional

  Especifica o motivo pelo qual a expressão regular não é aceita. Fornecido apenas se isSupported for falso.

MatchedRule

Propriedades

• ruleId

  número

  O ID de uma regra correspondente.

• rulesetId

  string

  ID do Ruleset a que esta regra pertence. Para uma regra originada do conjunto de regras dinâmicas, o valor será igual a DYNAMIC_RULESET_ID.

MatchedRuleInfo

Propriedades

• regra

  MatchedRule

• tabId

  número

  O tabId da guia de origem da solicitação, se ela ainda estiver ativa. Caso contrário, -1.

• timeStamp

  número

  A hora em que a regra foi correspondida. Os carimbos de data/hora vão corresponder à convenção do JavaScript para horários, ou seja, o número de milissegundos desde a época.

MatchedRuleInfoDebug

Propriedades

• solicitação

  RequestDetails

  Detalhes sobre a solicitação que correspondeu à regra.

• regra

  MatchedRule

MatchedRulesFilter

Propriedades

• minTimeStamp

  número optional

  Se especificado, corresponde apenas às regras após o carimbo de data/hora fornecido.

• tabId

  número optional

  Se especificado, corresponde apenas às regras da guia fornecida. Corresponde a regras não associadas a nenhuma guia ativa se definido como -1.

ModifyHeaderInfo

Chrome 86+

Propriedades

• cabeçalho

  string

  O nome do cabeçalho a ser modificado.

• operação

  HeaderOperation

  A operação a ser realizada em um cabeçalho.

• valor

  string opcional

  O novo valor do cabeçalho. Precisa ser especificado para as operações append e set.

QueryKeyValue

Propriedades

• chave

  string

• replaceOnly

  booleano opcional

  Chrome 94 ou mais recente

  Se for verdadeiro, a chave de consulta será substituída apenas se já estiver presente. Caso contrário, a chave também será adicionada se estiver ausente. O padrão é "falso".

• valor

  string

QueryTransform

Propriedades

• addOrReplaceParams

  QueryKeyValue[] opcional

  A lista de pares de chave-valor de consulta a serem adicionados ou substituídos.

• removeParams

  string[] opcional

  A lista de chaves de consulta a serem removidas.

Redirect

Propriedades

• extensionPath

  string opcional

  Caminho relativo ao diretório da extensão. Precisa começar com "/".

• regexSubstitution

  string opcional

  Padrão de substituição para regras que especificam um regexFilter. A primeira correspondência de regexFilter no URL será substituída por esse padrão. Em regexSubstitution, dígitos de escape com barra invertida (\1 a \9) podem ser usados para inserir os grupos de captura correspondentes. \0 indica o texto correspondente inteiro.

• transform

  URLTransform opcional

  Transformações de URL a serem realizadas.

• url

  string opcional

  O URL de redirecionamento. Não são permitidos redirecionamentos para URLs de JavaScript.

RegexOptions

Chrome 87 ou mais recente

Propriedades

• isCaseSensitive

  booleano opcional

  Se o regex especificado diferencia maiúsculas de minúsculas. O padrão é verdadeiro.

• Regex

  string

  A expressão regular a ser verificada.

• requireCapturing

  booleano opcional

  Se o regex especificado requer captura. A captura só é necessária para regras de redirecionamento que especificam uma ação regexSubstition. O valor padrão é falso.

RequestDetails

Propriedades

• documentId

  string opcional

  Chrome 106+

  O identificador exclusivo do documento do frame, se essa solicitação for para um frame.

• documentLifecycle

  DocumentLifecycle opcional

  Chrome 106+

  O ciclo de vida do documento do frame, se essa solicitação for para um frame.

• frameId

  número

  O valor 0 indica que a solicitação ocorre no frame principal. Um valor positivo indica o ID de um subframe em que a solicitação ocorre. Se o documento de um (sub)frame for carregado (type é main_frame ou sub_frame), frameId vai indicar o ID desse frame, não o do frame externo. Os IDs de frame são exclusivos em uma guia.

• frameType

  FrameType opcional

  Chrome 106+

  O tipo do frame, se a solicitação for para um frame.

• iniciador

  string opcional

  A origem em que a solicitação foi iniciada. Isso não muda com os redirecionamentos. Se for uma origem opaca, a string "null" será usada.

• método

  string

  Método HTTP padrão.

• parentDocumentId

  string opcional

  Chrome 106+

  O identificador exclusivo do documento pai do frame, se essa solicitação for para um frame e tiver um pai.

• parentFrameId

  número

  ID do frame que envolve o frame que enviou a solicitação. Defina como -1 se não houver um frame pai.

• requestId

  string

  O ID da solicitação. Os IDs de solicitação são exclusivos em uma sessão do navegador.

• tabId

  número

  O ID da guia em que a solicitação ocorre. Defina como -1 se a solicitação não estiver relacionada a uma guia.

• tipo

  ResourceType

  O tipo de recurso da solicitação.

• url

  string

  O URL da solicitação.

RequestMethod

Chrome 91+

Descreve o método de solicitação HTTP de uma solicitação de rede.

Enumeração

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Descreve o tipo de recurso da solicitação de rede.

Enumeração

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Propriedades

• ação

  RuleAction

  A ação a ser realizada se houver correspondência com essa regra.

• condição

  RuleCondition

  A condição em que essa regra é acionada.

• ID

  número

  Um ID que identifica uma regra de maneira exclusiva. Obrigatório e precisa ser >= 1.

• prioridade

  número optional

  Prioridade da regra. O padrão é 1. Quando especificado, precisa ser >= 1.

RuleAction

Propriedades

• Redirecionar

  Redirecionamento opcional

  Descreve como o redirecionamento deve ser realizado. Válido apenas para regras de redirecionamento.

• requestHeaders

  ModifyHeaderInfo[] opcional

  Chrome 86+

  Os cabeçalhos da solicitação a serem modificados para a solicitação. Válido apenas se RuleActionType for "modifyHeaders".

• responseHeaders

  ModifyHeaderInfo[] opcional

  Chrome 86+

  Os cabeçalhos de resposta a serem modificados para a solicitação. Válido apenas se RuleActionType for "modifyHeaders".

• tipo

  RuleActionType

  O tipo de ação a ser realizada.

RuleActionType

Descreve o tipo de ação a ser realizada se uma determinada RuleCondition for correspondente.

Enumeração

"block"
Bloqueia a solicitação de rede.

"redirect"
Redireciona a solicitação de rede.

"allow"
Permite a solicitação de rede. A solicitação não será interceptada se houver uma regra de permissão correspondente.

"upgradeScheme"
Faz upgrade do esquema do URL da solicitação de rede para https se a solicitação for http ou ftp.

"modifyHeaders"
Modifica os cabeçalhos de solicitação/resposta da solicitação de rede.

"allowAllRequests"
Permite todas as solicitações em uma hierarquia de frames, incluindo a própria solicitação de frame.

RuleCondition

Propriedades

• domainType

  DomainType opcional

  Especifica se a solicitação de rede é própria ou de terceiros para o domínio de origem. Se omitido, todas as solicitações serão aceitas.

• domínios

  string[] opcional

  Descontinuado desde o Chrome 101

  Use initiatorDomains

  A regra só vai corresponder às solicitações de rede originadas da lista de domains.

• excludedDomains

  string[] opcional

  Descontinuado desde o Chrome 101

  Use excludedInitiatorDomains

  A regra não vai corresponder às solicitações de rede originadas da lista de excludedDomains.

• excludedInitiatorDomains

  string[] opcional

  Chrome 101+

  A regra não vai corresponder às solicitações de rede originadas da lista de excludedInitiatorDomains. Se a lista estiver vazia ou for omitida, nenhum domínio será excluído. Isso tem precedência sobre initiatorDomains.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter apenas caracteres ASCII.
  • Use a codificação punycode para domínios internacionalizados.
  • Isso corresponde ao iniciador da solicitação, não ao URL dela.
  • Os subdomínios dos domínios listados também são excluídos.
• excludedRequestDomains

  string[] opcional

  Chrome 101+

  A regra não vai corresponder às solicitações de rede quando os domínios corresponderem a um da lista de excludedRequestDomains. Se a lista estiver vazia ou for omitida, nenhum domínio será excluído. Isso tem precedência sobre requestDomains.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter apenas caracteres ASCII.
  • Use a codificação punycode para domínios internacionalizados.
  • Os subdomínios dos domínios listados também são excluídos.
• excludedRequestMethods

  RequestMethod[] opcional

  Chrome 91+

  Lista de métodos de solicitação que não correspondem à regra. Somente requestMethods ou excludedRequestMethods deve ser especificado. Se nenhum deles for especificado, todos os métodos de solicitação serão correspondidos.

• excludedResourceTypes

  ResourceType[] opcional

  Lista de tipos de recursos que não correspondem à regra. Somente resourceTypes ou excludedResourceTypes deve ser especificado. Se nenhum deles for especificado, todos os tipos de recursos, exceto "main_frame", serão bloqueados.

• excludedResponseHeaders

  HeaderInfo[] opcional

  Chrome 128+

  A regra não será correspondente se a solicitação corresponder a qualquer condição de cabeçalho de resposta nesta lista (se especificada). Se excludedResponseHeaders e responseHeaders forem especificados, a propriedade excludedResponseHeaders terá precedência.

• excludedTabIds

  number[] opcional

  Chrome 92+

  Lista de tabs.Tab.id que não devem corresponder à regra. Um ID de tabs.TAB_ID_NONE exclui solicitações que não se originam de uma guia. Compatível apenas com regras no escopo da sessão.

• excludedTopDomains

  string[] opcional

  Chrome 145+

  A regra não vai corresponder às solicitações de rede quando o domínio do frame de nível superior associado corresponder a um da lista de excludedTopDomains. Se a lista estiver vazia ou for omitida, nenhum domínio será excluído. Isso tem precedência sobre topDomains.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter apenas caracteres ASCII.
  • Use a codificação punycode para domínios internacionalizados.
  • Os subdomínios dos domínios listados também são excluídos.
  • Para solicitações sem frame de nível superior associado (por exemplo, solicitações iniciadas pelo ServiceWorker), o domínio do iniciador da solicitação é considerado.
• initiatorDomains

  string[] opcional

  Chrome 101+

  A regra só vai corresponder às solicitações de rede originadas da lista de initiatorDomains. Se a lista for omitida, a regra será aplicada a solicitações de todos os domínios. Não é permitido usar uma lista vazia.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter apenas caracteres ASCII.
  • Use a codificação punycode para domínios internacionalizados.
  • Isso corresponde ao iniciador da solicitação, não ao URL dela.
  • Os subdomínios dos domínios listados também são correspondentes.
• isUrlFilterCaseSensitive

  booleano opcional

  Se o urlFilter ou o regexFilter (o que for especificado) diferencia maiúsculas de minúsculas. O padrão é false

• regexFilter

  string opcional

  Expressão regular para corresponder ao URL da solicitação de rede. Isso segue a sintaxe RE2.

  Observação: só é possível especificar urlFilter ou regexFilter.

  Observação: o regexFilter precisa ser composto apenas por caracteres ASCII. Isso é comparado com um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e todos os outros caracteres não ASCII são codificados em UTF-8.

• requestDomains

  string[] opcional

  Chrome 101+

  A regra só vai corresponder às solicitações de rede quando o domínio corresponder a um da lista de requestDomains. Se a lista for omitida, a regra será aplicada a solicitações de todos os domínios. Não é permitido usar uma lista vazia.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter apenas caracteres ASCII.
  • Use a codificação punycode para domínios internacionalizados.
  • Os subdomínios dos domínios listados também são correspondentes.
• requestMethods

  RequestMethod[] opcional

  Chrome 91+

  Lista de métodos de solicitação HTTP que podem ser correspondidos pela regra. Não é permitido usar uma lista vazia.

  Observação: especificar uma condição de regra requestMethods também vai excluir solicitações que não sejam HTTP(S), enquanto especificar excludedRequestMethods não vai.

• resourceTypes

  ResourceType[] opcional

  Lista de tipos de recursos que podem ser correspondidos pela regra. Não é permitido usar uma lista vazia.

  Observação: isso precisa ser especificado para regras allowAllRequests e pode incluir apenas os tipos de recurso sub_frame e main_frame.

• responseHeaders

  HeaderInfo[] opcional

  Chrome 128+

  A regra será correspondente se a solicitação corresponder a qualquer condição de cabeçalho de resposta nesta lista (se especificada).

• tabIds

  number[] opcional

  Chrome 92+

  Lista de tabs.Tab.id que a regra precisa corresponder. Um ID de tabs.TAB_ID_NONE corresponde a solicitações que não se originam de uma guia. Não é permitido usar uma lista vazia. Compatível apenas com regras no escopo da sessão.

• topDomains

  string[] opcional

  Chrome 145+

  A regra só vai corresponder às solicitações de rede quando o domínio do frame de nível superior associado corresponder a um da lista de topDomains. Se a lista for omitida, a regra será aplicada às solicitações associadas a todos os domínios de frame de nível superior. Não é permitido usar uma lista vazia.

  Observações:

  • Subdomínios como "a.example.com" também são permitidos.
  • As entradas precisam conter apenas caracteres ASCII.
  • Use a codificação punycode para domínios internacionalizados.
  • Os subdomínios dos domínios listados também são correspondentes.
  • Para solicitações sem frame de nível superior associado (por exemplo, solicitações iniciadas pelo ServiceWorker), o domínio do iniciador da solicitação é considerado.
• urlFilter

  string opcional

  O padrão que é comparado com o URL da solicitação de rede. Construções compatíveis:

  '*': caractere curinga que corresponde a qualquer número de caracteres.

  '|': âncora esquerda/direita. Se usado em uma das extremidades do padrão, especifica o início/fim do URL, respectivamente.

  '||': âncora de nome de domínio. Se usado no início do padrão, especifica o início de um (sub)domínio do URL.

  '^': caractere separador. Corresponde a qualquer coisa, exceto uma letra, um dígito ou um dos seguintes: _, -, . ou %. Isso também corresponde ao final do URL.

  Portanto, urlFilter é composto pelas seguintes partes: (âncora opcional à esquerda/nome de domínio) + padrão + (âncora opcional à direita).

  Se omitido, todos os URLs serão correspondidos. Não é permitido usar uma string vazia.

  Não é permitido um padrão que comece com ||*. Use *.

  Observação: só é possível especificar urlFilter ou regexFilter.

  Observação: o urlFilter precisa ser composto apenas por caracteres ASCII. Isso é comparado com um URL em que o host é codificado no formato punycode (no caso de domínios internacionalizados) e todos os outros caracteres não ASCII são codificados em UTF-8. Por exemplo, quando o URL da solicitação é http://abc.рф?q=ф, o urlFilter é comparado com o URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145+

Enumeração

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Propriedades

• ativado

  booleano

  Se o conjunto de regras está ativado por padrão.

• ID

  string

  Uma string não vazia que identifica o conjunto de regras de forma exclusiva. Os IDs que começam com "_" são reservados para uso interno.

• caminho

  string

  O caminho do conjunto de regras JSON em relação ao diretório da extensão.

RulesMatchedDetails

Propriedades

• rulesMatchedInfo

  MatchedRuleInfo[]

  Regras que correspondem ao filtro fornecido.

TabActionCountUpdate

Chrome 89+

Propriedades

• increment

  número

  O valor para incrementar a contagem de ações da guia. Valores negativos diminuem a contagem.

• tabId

  número

  A guia em que a contagem de ações será atualizada.

TestMatchOutcomeResult

Chrome 103+

Propriedades

• matchedRules

  MatchedRule[]

  As regras (se houver) que correspondem à solicitação hipotética.

TestMatchRequestDetails

Chrome 103+

Propriedades

• iniciador

  string opcional

  O URL do iniciador (se houver) para a solicitação hipotética.

• método

  RequestMethod opcional

  Método HTTP padrão da solicitação hipotética. O padrão é "get" para solicitações HTTP e é ignorado para solicitações não HTTP.

• responseHeaders

  objeto optional

  Chrome 129+

  Os cabeçalhos fornecidos por uma resposta hipotética se a solicitação não for bloqueada ou redirecionada antes de ser enviada. Representado como um objeto que mapeia um nome de cabeçalho para uma lista de valores de string. Se não for especificado, a resposta hipotética retornará cabeçalhos de resposta vazios, que podem corresponder a regras que correspondem à inexistência de cabeçalhos. Por exemplo, {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

• tabId

  número optional

  O ID da guia em que a solicitação hipotética ocorre. Não precisa corresponder a um ID de guia real. O padrão é -1, o que significa que a solicitação não está relacionada a uma guia.

• topUrl

  string opcional

  Chrome 145+

  O URL do frame de nível superior associado (se houver) para a solicitação.

• tipo

  ResourceType

  O tipo de recurso da solicitação hipotética.

• url

  string

  O URL da solicitação hipotética.

UnsupportedRegexReason

Chrome 87 ou mais recente

Descreve o motivo pelo qual uma determinada expressão regular não é aceita.

Enumeração

"syntaxError"
A expressão regular está sintaticamente incorreta ou usa recursos não disponíveis na sintaxe RE2.

"memoryLimitExceeded"
A expressão regular excede o limite de memória.

UpdateRuleOptions

Chrome 87 ou mais recente

Propriedades

• addRules

  Regra[] opcional

  Regras a serem adicionadas.

• removeRuleIds

  number[] opcional

  IDs das regras a serem removidas. Os IDs inválidos serão ignorados.

UpdateRulesetOptions

Chrome 87 ou mais recente

Propriedades

• disableRulesetIds

  string[] opcional

  O conjunto de IDs correspondentes a um Ruleset estático que precisa ser desativado.

• enableRulesetIds

  string[] opcional

  O conjunto de IDs correspondentes a um Ruleset estático que precisa ser ativado.

UpdateStaticRulesOptions

Chrome 111+

Propriedades

• disableRuleIds

  number[] opcional

  Conjunto de IDs correspondentes às regras no Ruleset que serão desativadas.

• enableRuleIds

  number[] opcional

  Conjunto de IDs correspondentes às regras no Ruleset a serem ativadas.

• rulesetId

  string

  O ID correspondente a um Ruleset estático.

URLTransform

Propriedades

• fragment

  string opcional

  O novo fragmento da solicitação. Deve estar vazio, caso em que o fragmento atual é limpo, ou começar com "#".

• host

  string opcional

  O novo host da solicitação.

• senha

  string opcional

  A nova senha da solicitação.

• caminho

  string opcional

  O novo caminho para a solicitação. Se estiver vazio, o caminho atual será limpo.

• porta

  string opcional

  A nova porta para a solicitação. Se estiver vazio, a porta atual será limpa.

• consulta

  string opcional

  A nova consulta para a solicitação. Precisa estar vazio, caso em que a consulta atual é apagada, ou começar com "?".

• queryTransform

  QueryTransform opcional

  Adicione, remova ou substitua pares de chave-valor de consulta.

• planejar

  string opcional

  O novo esquema da solicitação. Os valores permitidos são "http", "https", "ftp" e "chrome-extension".

• nome de usuário

  string opcional

  O novo nome de usuário da solicitação.

Propriedades

DYNAMIC_RULESET_ID

ID do conjunto de regras dinâmicas adicionadas pela extensão.

Valor

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Intervalo de tempo em que as chamadas de MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules podem ser feitas, especificado em minutos. As chamadas adicionais vão falhar imediatamente e definir runtime.lastError. Observação: as chamadas getMatchedRules associadas a uma interação inicial estão isentas da cota.

Valor

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+

O número mínimo de regras estáticas garantidas para uma extensão em todos os conjuntos de regras estáticas ativados. As regras acima desse limite serão contabilizadas no limite global de regras estáticas.

Valor

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

O número de vezes que getMatchedRules pode ser chamado em um período de GETMATCHEDRULES_QUOTA_INTERVAL.

Valor

20

MAX_NUMBER_OF_DYNAMIC_RULES

O número máximo de regras dinâmicas que uma extensão pode adicionar.

Valor

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ou mais recente

O número máximo de Rulesets estáticos que uma extensão pode ativar de uma só vez.

Valor

50

MAX_NUMBER_OF_REGEX_RULES

O número máximo de regras de expressão regular que uma extensão pode adicionar. Esse limite é avaliado separadamente para o conjunto de regras dinâmicas e as especificadas no arquivo de recursos de regras.

Valor

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

O número máximo de regras com escopo de sessão que uma extensão pode adicionar.

Valor

5000

MAX_NUMBER_OF_STATIC_RULESETS

O número máximo de Rulesets estáticos que uma extensão pode especificar como parte da chave de manifesto "rule_resources".

Valor

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120+

O número máximo de regras dinâmicas "não seguras" que uma extensão pode adicionar.

Valor

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+

O número máximo de regras de escopo de sessão "não seguras" que uma extensão pode adicionar.

Valor

5000

SESSION_RULESET_ID

Chrome 90+

ID do conjunto de regras no escopo da sessão adicionadas pela extensão.

Valor

"_session"

Métodos

getAvailableStaticRuleCount()

Promessa Chrome 89+

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

Retorna o número de regras estáticas que uma extensão pode ativar antes que o limite global de regras estáticas seja atingido.

Parâmetros

• callback

  função optional

  O parâmetro callback é semelhante a:

  (count: number) => void

  • contagem

    número

Retorna

• Promise<number>

  Chrome 91+

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getDisabledRuleIds()

Promessa Chrome 111+

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

Retorna a lista de regras estáticas no Ruleset fornecido que estão desativadas no momento.

Parâmetros

• opções

  GetDisabledRuleIdsOptions

  Especifica o conjunto de regras a ser consultado.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (disabledRuleIds: number[]) => void

  • disabledRuleIds

    number[]

Retorna

• Promise<number[]>

  Promessa que é resolvida com uma lista de IDs que correspondem às regras desativadas nesse conjunto de regras.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getDynamicRules()

Promessa

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

Retorna o conjunto atual de regras dinâmicas da extensão. Os autores da chamada podem filtrar a lista de regras buscadas especificando um filter.

Parâmetros

• filtro

  GetRulesFilter opcional

  Chrome 111+

  Um objeto para filtrar a lista de regras buscadas.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (rules: Rule[]) => void

  • regras

    Regra[]

Retorna

• Promise<Rule[]>

  Chrome 91+

  Promessa que é resolvida com o conjunto de regras dinâmicas. A promessa pode ser rejeitada em caso de erros internos temporários.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getEnabledRulesets()

Promessa

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

Retorna os IDs do conjunto atual de conjuntos de regras estáticas ativados.

Parâmetros

• callback

  função optional

  O parâmetro callback é semelhante a:

  (rulesetIds: string[]) => void

  • rulesetIds

    string[]

Retorna

• Promise<string[]>

  Chrome 91+

  Promessa que é resolvida com uma lista de IDs, em que cada ID corresponde a um Ruleset estático ativado.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getMatchedRules()

Promessa

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

Retorna todas as regras correspondentes à extensão. Os autores da chamada podem filtrar a lista de regras correspondentes especificando um filter. Esse método está disponível apenas para extensões com a permissão "declarativeNetRequestFeedback" ou com a permissão "activeTab" concedida para o tabId especificado em filter. Observação: as regras não associadas a um documento ativo que foram correspondidas há mais de cinco minutos não serão retornadas.

Parâmetros

• filtro

  MatchedRulesFilter opcional

  Um objeto para filtrar a lista de regras correspondentes.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (details: RulesMatchedDetails) => void

  • detalhes

    RulesMatchedDetails

Retorna

• Promise<RulesMatchedDetails>

  Chrome 91+

  Promessa que é resolvida quando a lista de regras correspondentes é buscada. Em caso de erro, a promessa será rejeitada. Isso pode acontecer por vários motivos, como permissões insuficientes ou exceder a cota.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getSessionRules()

Promessa Chrome 90+

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

Retorna o conjunto atual de regras com escopo de sessão para a extensão. Os autores da chamada podem filtrar a lista de regras buscadas especificando um filter.

Parâmetros

• filtro

  GetRulesFilter opcional

  Chrome 111+

  Um objeto para filtrar a lista de regras buscadas.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (rules: Rule[]) => void

  • regras

    Regra[]

Retorna

• Promise<Rule[]>

  Chrome 91+

  Promessa que é resolvida com o conjunto de regras com escopo de sessão.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

isRegexSupported()

Promise Chrome 87+

chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
): Promise<IsRegexSupportedResult>

Verifica se a expressão regular fornecida será aceita como uma condição de regra regexFilter.

Parâmetros

• regexOptions

  RegexOptions

  A expressão regular a ser verificada.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (result: IsRegexSupportedResult) => void

  • resultado

    IsRegexSupportedResult

Retorna

• Promise<IsRegexSupportedResult>

  Chrome 91+

  Promessa que é resolvida com detalhes que consistem em saber se a expressão regular é compatível e o motivo, se não for.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setExtensionActionOptions()

Promise Chrome 88+

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
): Promise<void>

Configura se a contagem de ações para guias precisa ser mostrada como o texto do selo da ação da extensão e fornece uma maneira de incrementar essa contagem.

Parâmetros

• opções

  ExtensionActionOptions

• callback

  função optional

  Chrome 89+

  O parâmetro callback é semelhante a:

  () => void

Retorna

• Promessa<void>

  Chrome 91+

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

testMatchOutcome()

Promessa Chrome 103+

chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
): Promise<TestMatchOutcomeResult>

Verifica se alguma das regras de declarativeNetRequest da extensão corresponde a uma solicitação hipotética. Observação: disponível apenas para extensões descompactadas, já que é destinado apenas para uso durante o desenvolvimento de extensões.

Parâmetros

• solicitação

  TestMatchRequestDetails

• callback

  função optional

  O parâmetro callback é semelhante a:

  (result: TestMatchOutcomeResult) => void

  • resultado

    TestMatchOutcomeResult

Retorna

• Promise<TestMatchOutcomeResult>

  Promessa que é resolvida com os detalhes das regras correspondentes.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

updateDynamicRules()

Promessa

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

Modifica o conjunto atual de regras dinâmicas da extensão. As regras com IDs listados em options.removeRuleIds são removidas primeiro e, em seguida, as regras fornecidas em options.addRules são adicionadas. Observações:

• Essa atualização acontece como uma única operação atômica: ou todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
• Essas regras são mantidas entre as sessões do navegador e as atualizações da extensão.
• As regras estáticas especificadas como parte do pacote de extensão não podem ser removidas usando essa função.
• MAX_NUMBER_OF_DYNAMIC_RULES é o número máximo de regras dinâmicas que uma extensão pode adicionar. O número de regras não seguras não pode exceder MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Parâmetros

• opções

  UpdateRuleOptions

  Chrome 87 ou mais recente
• callback

  função optional

  O parâmetro callback é semelhante a:

  () => void

Retorna

• Promessa<void>

  Chrome 91+

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada e nenhuma alteração será feita no conjunto de regras. Isso pode acontecer por vários motivos, como formato de regra inválido, ID de regra duplicado, limite de contagem de regras excedido, erros internos, entre outros.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

updateEnabledRulesets()

Promessa

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

Atualiza o conjunto de regras estáticas ativadas para a extensão. Os conjuntos de regras com IDs listados em options.disableRulesetIds são removidos primeiro e, em seguida, os conjuntos de regras listados em options.enableRulesetIds são adicionados. O conjunto de conjuntos de regras estáticos ativados é mantido entre as sessões, mas não entre as atualizações da extensão. Ou seja, a chave de manifesto rule_resources vai determinar o conjunto de conjuntos de regras estáticos ativados em cada atualização da extensão.

Parâmetros

• opções

  UpdateRulesetOptions

  Chrome 87 ou mais recente
• callback

  função optional

  O parâmetro callback é semelhante a:

  () => void

Retorna

• Promessa<void>

  Chrome 91+

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada, e nenhuma alteração será feita no conjunto de regras ativadas. Isso pode acontecer por vários motivos, como IDs de conjunto de regras inválidos, limite de contagem de regras excedido ou erros internos.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

updateSessionRules()

Promessa Chrome 90+

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

Modifica o conjunto atual de regras com escopo de sessão para a extensão. As regras com IDs listados em options.removeRuleIds são removidas primeiro e, em seguida, as regras fornecidas em options.addRules são adicionadas. Observações:

• Essa atualização acontece como uma única operação atômica: ou todas as regras especificadas são adicionadas e removidas ou um erro é retornado.
• Essas regras não são mantidas entre as sessões e são armazenadas na memória.
• MAX_NUMBER_OF_SESSION_RULES é o número máximo de regras de sessão que uma extensão pode adicionar.

Parâmetros

• opções

  UpdateRuleOptions

• callback

  função optional

  O parâmetro callback é semelhante a:

  () => void

Retorna

• Promessa<void>

  Chrome 91+

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada e nenhuma alteração será feita no conjunto de regras. Isso pode acontecer por vários motivos, como formato de regra inválido, ID de regra duplicado, limite de contagem de regras excedido, entre outros.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

updateStaticRules()

Promessa Chrome 111+

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

Desativa e ativa regras estáticas individuais em um Ruleset. As mudanças nas regras de um Ruleset desativado vão entrar em vigor na próxima vez que ele for ativado.

Parâmetros

• opções

  UpdateStaticRulesOptions

• callback

  função optional

  O parâmetro callback é semelhante a:

  () => void

Retorna

• Promessa<void>

  Promessa que é resolvida quando a atualização é concluída. Em caso de erro, a promessa será rejeitada, e nenhuma mudança será feita nas regras estáticas ativadas.

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onRuleMatchedDebug

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

Disparado quando uma regra corresponde a uma solicitação. Disponível apenas para extensões descompactadas com a permissão "declarativeNetRequestFeedback", já que ela é destinada apenas para fins de depuração.

Parâmetros

• callback

  função

  O parâmetro callback é semelhante a:

  (info: MatchedRuleInfoDebug) => void

  • informações

    MatchedRuleInfoDebug