chrome.declarativeContent

Descrição

Permissões

Conceitos e uso

A API de conteúdo declarativo 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 somente se todos os critérios listados forem atendidos. Ele pode corresponder a um URL da 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 ativar a ação da extensão para 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 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. 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 "Contains", "Equals", "Prefix" ou "Suffix". Confira alguns exemplos na tabela a seguir:

Critérios	Correspondências
{ hostSuffix: 'google.com' }	Todos os URLs do Google
{ pathPrefix: '/docs/extensions' }	URLs dos documentos da extensão
{ urlContains: 'developer.chrome.com' }	Todos os URLs dos 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, o que significa que não é possível incluir combinatores, como espaços em branco ou ">", nos seletores. Isso ajuda o Chrome a corresponder aos 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 do CSS só correspondem aos elementos exibidos: se um elemento que corresponde ao seletor for display:none ou um dos elementos pai for display:none, a condição não será correspondente. Elementos estilizados com visibility:hidden, posicionados fora da tela ou ocultos por outros elementos ainda podem fazer com que a condição corresponda.

Correspondência de estado com marcadores

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