chrome.declarativeContent

Descrição

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

Permissões

declarativeContent

Conceitos e uso

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

Use a permissão activeTab para interagir com uma página depois que o usuário clicar no 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 executada. As ações são setIcon() e showAction().

O PageStateMatcher faz a correspondência de páginas da Web somente se todas elas estiverem listadas e os critérios sejam atendidos. Ele pode corresponder a um URL de página, um seletor composto de CSS. ou o estado marcado como favorito de uma página. 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 outra , 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 atendida e executa as ações. As regras persistem em todas as sessões de navegação. Portanto, durante tempo de instalação da extensão, use primeiro removeRules para limpar regras já instaladas e depois usar 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á nenhuma permissão. e, quando o usuário clicar na ação da extensão, ela será executada somente nas páginas relevantes.

Correspondência do URL da página

O PageStateMatcher.pageurl faz a correspondência quando os critérios de URL são atendidos. A Os critérios mais comuns são uma concatenação de host, caminho ou URL seguido de "contém", "igual a", "prefixo" ou Sufixo. Confira alguns exemplos na tabela a seguir:

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 de documentos do Chrome Developers

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 ">" no seu seletores. Isso ajuda o Chrome a fazer a correspondência dos seletores com mais eficiência.

Seletores compostos (OK) Seletores complexos (incorretos)
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 exibidos: se um elemento que corresponde ao seletor for display:none ou um dos elementos pais dele for display:none, isso não faz com que a condição seja são correspondentes. Elementos estilizados com visibility:hidden, posicionados fora da tela ou ocultos por outros elementos ainda pode corresponder à condição.

Correspondência de estado favorito

A condição PageStateMatcher.isBookmarked permite a correspondência dos estado favorito do URL atual no perfil do usuário. Para usar essa condição, o "favoritos" A permissão 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

    Faz correspondência 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 na matriz precisam ser seletores 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 deixar os sites mais lentos.

  • isBookmarked

    booleano opcional

    Chrome 45 ou superior

    Faz correspondência se o estado da página marcado como favorito for igual ao valor especificado. Requer a permissão de favoritos.

  • pageUrl

    UrlFilter opcional

    Corresponde se as condições de 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 tem suporte em 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 da página ou a ação do navegador da extensão enquanto as condições correspondentes são atendidas. Esta 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 imageData ou path. Ambos são dicionários que mapeiam uma série 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 da 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 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 dependendo da 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 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 ou versão mais recente

Uma ação de evento declarativa que define a action da barra de ferramentas da extensão como um estado ativado enquanto as condições correspondentes são atendidas. Esta ação pode ser usada sem permissões do 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 e um clique 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. Esta 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 e um clique 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