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 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 corresponde a páginas da Web se e somente se todos os critérios listados forem atendidos. Ele pode corresponder a um URL da página, a um seletor composto de CSS ou ao estado de página adicionada aos favoritos. A regra a seguir ativa a ação da extensão em 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 ativar a ação da extensão em sites do Google com um vídeo, adicione uma segunda condição, já que cada uma é 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 em todas as sessões de navegação. Portanto, durante a instalação da extensão, primeiro use removeRules para limpar as regras instaladas anteriormente e depois 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 avisos de permissão, e, quando o usuário clicar na ação da extensão, ela será executada apenas em 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 da documentação 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 OK)
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 a elementos mostrados. Se um elemento que corresponde ao seu seletor for display:none ou um dos elementos pai dele for display:none, isso não fará com que a condição corresponda. Elementos estilizados com visibility:hidden, posicionados fora da tela ou ocultos por outros elementos ainda podem fazer com que sua condição corresponda.

Correspondência de estado de favoritos

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 tem esta aparência: 

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

  • css

    string[] opcional

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

  • isBookmarked

    booleano opcional

    Chrome 45 ou mais recente

    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 builds estáveis do Chrome.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

    (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

    Define 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 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 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 os pixels da tela scale couberem em um pixel independente do dispositivo, o ícone scale * n será usado. Se essa escala estiver faltando, outra imagem será redimensionada para o tamanho necessário.

Propriedades

  • construtor

    void

    A função constructor tem esta aparência: 

    (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 da imagem que cabem em uma unidade de espaço da tela for igual a scale, uma imagem de 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 ou mais recente

Uma ação de evento declarativa que define a ação da barra de ferramentas da extensão como ativada 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 da página concederá acesso à guia ativa.

Nas páginas em que as condições não são atendidas, a ação da barra de ferramentas da extensão será em escala de cinza. Ao clicar nela, o menu de contexto será aberto 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 ativada 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 da página concederá acesso à guia ativa.

Nas páginas em que as condições não são atendidas, a ação da barra de ferramentas da extensão será em escala de cinza. Ao clicar nela, o menu de contexto será aberto 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