chrome.declarativeContent

Descrição

Permissões

Conceitos e uso

A API Declarative Content permite ativar a ação da extensão dependendo do URL de uma página da Web ou de um seletor de CSS corresponder 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 a páginas da Web somente se todos os critérios listados forem atendidos. Ele pode corresponder a um URL da página, um seletor composto CSS ou ao estado marcado como 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() ]
};

Se quiser ativar a ação da extensão para sites Google 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 em todas as sessões de navegação. Portanto, durante a instalação da extensão, use removeRules para limpar as regras instaladas anteriormente e 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 exibirá 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 do 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 de "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 de documentos de extensão
{ urlContains: 'developer.chrome.com' }	Todos os URLs dos documentos dos 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, o que significa que não é possível incluir combinadores como espaços em branco ou ">" nos seletores. Isso ajuda o Chrome a fazer a correspondência entre os seletores com mais eficiência.

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

As condições de CSS correspondem apenas aos elementos exibidos: se um elemento que corresponde ao seletor for display:none ou um dos elementos pais for display:none, a condição não fará com que a condição seja correspondente. Elementos estilizados com visibility:hidden, posicionados fora da tela ou ocultos por outros elementos ainda podem corresponder à condição.

Correspondência de estado nos favoritos

A condição PageStateMatcher.isBookmarked permite a correspondência do estado marcado como 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.