chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Descrição

Use a API chrome.declarativeContent para realizar ações dependendo do conteúdo de uma página, sem precisar de permissão para ler o conteúdo dela.

Permissões

declarativeContent

.

Uso

A API Declarative Content permite ativar a ação da extensão dependendo do URL de uma página da Web ou se um seletor de CSS corresponde a um elemento na página, sem precisar adicionar permissões de host ou injetar um script de conteúdo.

Use a permissão activeTab para interagir com uma página depois que o usuário clicar na ação da extensão.

Regras

As regras consistem em condições e ações. Se alguma das condições for atendida, todas as ações serão executadas. As ações são setIcon e showAction.

O PageStateMatcher vai corresponder às páginas da Web se, e somente se, todos os critérios listados forem atendidos. Ele pode corresponder a um URL de página, um seletor composto de CSS ou o estado de favorito de uma página. A regra a seguir ativa a ação da extensão nas páginas do Google quando um campo de senha está presente:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Para também ativar a ação da extensão para o Google Sites com um vídeo, adicione uma segunda condição, já que cada condição é suficiente para acionar todas as ações especificadas:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

O evento onPageChanged testa se alguma regra tem pelo menos uma condição atendida e executa as ações. As regras persistem nas sessões de navegação. Portanto, durante a instalação da extensão, use primeiro removeRules para limpar as regras instaladas anteriormente e, em seguida, use addRules para registrar novas.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Com a permissão activeTab, sua extensão não vai mostrar nenhum aviso de permissão e, quando o usuário clicar na ação da extensão, ela será executada apenas nas páginas relevantes.

Correspondência de URL da página

O PageStateMatcher.pageurl corresponde quando os critérios de URL são atendidos. Os critérios mais comuns são uma concatenação de host, caminho ou URL, seguida por "Contém", "É igual a", "Prefixo" ou "Sufixo". A tabela a seguir contém alguns exemplos:

Critérios Correspondências
{ hostSuffix: 'google.com' } Todos os URLs do Google
{ pathPrefix: '/docs/extensions' } URLs da documentação da extensão
{ urlContains: 'developer.chrome.com' } Todos os URLs de documentos para desenvolvedores do Chrome

Todos os critérios diferenciam maiúsculas de minúsculas. Para uma lista completa de critérios, consulte UrlFilter.

Correspondência de CSS

As condições PageStateMatcher.css precisam ser seletores compostos, ou seja, não é possível incluir combinadores, como espaços em branco ou ">", nos seletores. Isso ajuda o Chrome a corresponder os seletores com mais eficiência.

Seletores compostos (OK) Seletores complexos (não recomendado)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

As condições de CSS só correspondem aos elementos mostrados: se um elemento que corresponde ao seu seletor for display:none ou um dos elementos pai for display:none, isso não vai fazer com que a condição corresponda. Elementos estilizados com visibility:hidden, posicionados fora da tela ou ocultos por outros elementos ainda podem corresponder à sua condição.

Correspondência de estado marcado como favorito

A condição PageStateMatcher.isBookmarked permite a correspondência do estado de favorito do URL atual no perfil do usuário. Para usar essa condição, a permissão "bookmarks" precisa ser declarada no manifesto da extensão.

Tipos

Tipo

ImageData

PageStateMatcher

Corresponde ao estado de uma página da Web com base em vários critérios.

Propriedades

  • construtor

    void

    A função constructor é semelhante a: 

    (arg: PageStateMatcher) => {...}

  • css

    string[] opcional

    Será acionado se todos os seletores de CSS na matriz corresponderem aos elementos exibidos em um frame com a mesma origem do frame principal da página. Todos os seletores nessa matriz precisam ser seletores compostos para acelerar a correspondência. Observação: listar centenas de seletores de CSS ou seletores de CSS que correspondem centenas de vezes por página pode deixar os sites mais lentos.

  • isBookmarked

    booleano opcional

    Chrome 45+

    Corresponde se o estado de favorito da página for igual ao valor especificado. Requer a permissão de favoritos.

  • pageUrl

    UrlFilter opcional

    Corresponde se as condições do UrlFilter forem atendidas para o URL de nível superior da página.

RequestContentScript

Ação de evento declarativa que injeta um script de conteúdo.

AVISO: essa ação ainda é experimental e não é compatível com as versões estáveis do Chrome.

Propriedades

  • construtor

    void

    A função constructor é semelhante a: 

    (arg: RequestContentScript) => {...}

  • allFrames

    booleano opcional

    Se o script de conteúdo é executado em todos os frames da página correspondente ou apenas no frame superior. O padrão é false.

  • css

    string[] opcional

    Nomes de arquivos CSS a serem injetados como parte do script de conteúdo.

  • js

    string[] opcional

    Nomes de arquivos JavaScript a serem injetados como parte do script de conteúdo.

  • matchAboutBlank

    booleano opcional

    Se o script de conteúdo será inserido em about:blank e about:srcdoc. O padrão é false.

SetIcon

Ação de evento declarativa que define o ícone quadrado de n-dip para a ação de página ou ação do navegador da extensão enquanto as condições correspondentes são atendidas. Essa ação pode ser usada sem permissões de host, mas a extensão precisa ter uma ação de página ou de navegador.

É preciso especificar exatamente um imageData ou path. Ambos são dicionários que mapeiam um número de pixels para uma representação de imagem. A representação da imagem em imageData é um objeto ImageData, por exemplo, de um elemento canvas, enquanto a representação da imagem em path é o caminho para um arquivo de imagem relativo ao manifesto da extensão. Se scale pixels de tela couberem em um pixel independente de dispositivo, o ícone scale * n será usado. Se essa escala estiver ausente, outra imagem será redimensionada para o tamanho necessário.

Propriedades

  • construtor

    void

    A função constructor é semelhante a: 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | objeto opcional

    Um objeto ImageData ou um dicionário {size -> ImageData} que representa um ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem usada será escolhida de acordo com a densidade de pixels da tela. Se o número de pixels de imagem que cabem em uma unidade de espaço de tela for igual a scale, uma imagem com tamanho scale * n será selecionada, em que n é o tamanho do ícone na interface. É necessário especificar pelo menos uma imagem. Observe que details.imageData = foo é equivalente a details.imageData = {'16': foo}.

ShowAction

Chrome 97+

Uma ação de evento declarativa que define a ação da barra de ferramentas da extensão como um estado ativado enquanto as condições correspondentes são atendidas. Essa ação pode ser usada sem permissões de host. Se a extensão tiver a permissão activeTab, clicar na ação de página vai conceder acesso à guia ativa.

Nas páginas em que as condições não forem atendidas, a ação da barra de ferramentas da extensão vai ficar em escala de cinza, e clicar nela vai abrir o menu de contexto, em vez de acionar a ação.

Propriedades

ShowPageAction

Descontinuado desde o Chrome 97

Use declarativeContent.ShowAction.

Uma ação de evento declarativa que define a ação de página da extensão como um estado ativado enquanto as condições correspondentes são atendidas. Essa ação pode ser usada sem permissões de host, mas a extensão precisa ter uma ação de página. Se a extensão tiver a permissão activeTab, clicar na ação de página vai conceder acesso à guia ativa.

Nas páginas em que as condições não forem atendidas, a ação da barra de ferramentas da extensão vai ficar em escala de cinza, e clicar nela vai abrir o menu de contexto, em vez de acionar a ação.

Propriedades

Eventos

onPageChanged

Fornece a API Declarative Event, que consiste em addRules, removeRules e getRules.

Condições

PageStateMatcher

Ações

RequestContentScript

SetIcon

ShowPageAction

ShowAction