chrome.declarativeContent

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

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.

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 esta: 

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

  • css

    string[] opcional

    Será verdadeiro 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 listar seletores de CSS que correspondem a centenas de vezes por página pode deixar os sites mais lentos.

  • isBookmarked

    booleano opcional

    Chrome 45 e versões mais recentes

    Faz correspondência se o estado de página com o marcador de 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 é semelhante a esta: 

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

  • allFrames

    booleano opcional

    Define 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 dos arquivos CSS que serão 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 do host, mas a extensão precisa ter uma ação de página ou de navegador.

É preciso especificar exatamente um entre 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 se encaixarem 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 esta: 

    (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 o tamanho scale * n será selecionada, em que n é o tamanho do ícone na IU. É necessário especificar pelo menos uma imagem. details.imageData = foo é equivalente a details.imageData = {'16': foo}.

ShowAction

Chrome 97 e versões mais recentes

Uma ação de evento declarativa que define a ação da barra de ferramentas da extensão para um estado ativado enquanto as condições correspondentes são atendidas. Essa 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 concede 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 tons de cinza, e clicar nela vai abrir o menu de contexto em vez de acionar a ação.

Propriedades

ShowPageAction

Suspensa desde o Chrome 97

Use declarativeContent.ShowAction.

Uma ação de evento declarativa que define a ação da página da extensão para um estado ativado enquanto as condições correspondentes são atendidas. Essa ação pode ser usada sem permissões do host, mas a extensão precisa ter uma ação da página. Se a extensão tiver a permissão activeTab, clicar na ação da página vai 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 fica em escala de cinza, e clicar nela abre o menu de contexto em vez de acionar a ação.

Propriedades

Eventos

onPageChanged

Fornece a API de eventos declarativos, que consiste em addRules, removeRules e getRules.

Condições

PageStateMatcher

Ações

RequestContentScript

SetIcon

ShowPageAction

ShowAction