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.
Permissões
declarativeContent
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.
Tipos
ImageDataType
Consulte https://developer.mozilla.org/en-US/docs/Web/API/ImageData.
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) => {...}
-
arg
-
retorna
-
-
css
string[] opcional
Faz correspondência se todos os seletores de CSS na matriz correspondem 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 centenas de vezes por página pode deixar os sites mais lentos.
-
isBookmarked
booleano opcional
Chrome 45 ou mais recenteCorresponde se o estado da página adicionado aos favoritos é igual ao valor especificado. Requer a permissão de favoritos.
-
pageUrl
UrlFilter opcional
Corresponde se as condições de
UrlFilter
são 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 versões estáveis do Chrome.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: RequestContentScript) => {...}
-
retorna
-
-
allFrames
booleano opcional
Indica se o script de conteúdo é executado em todos os frames da página correspondente ou somente no frame superior. O padrão é
false
. -
css
string[] opcional
São os nomes dos arquivos CSS a serem injetados como parte do script de conteúdo.
-
js
string[] opcional
São os nomes dos arquivos JavaScript a serem injetados como parte do script de conteúdo.
-
matchAboutBlank
booleano opcional
Define se o script de conteúdo em
about:blank
eabout:srcdoc
deve ser inserido. 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. 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.
É necessário especificar exatamente um entre imageData
ou path
. Ambos são dicionários que mapeiam alguns pixels para uma representação de imagem. A representação de imagem em imageData
é um objeto ImageData. Por exemplo, de um elemento canvas
, enquanto a representação de imagem em path
é o caminho para um arquivo de imagem relativo ao manifesto da extensão. Se scale
pixels de 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) => {...}
-
arg
-
retorna
-
-
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 de imagem que cabem em uma unidade de espaço de tela for igual ascale
, uma imagem com tamanhoscale * n
será selecionada, em que n é o tamanho do ícone na interface. É necessário especificar pelo menos uma imagem. Observe quedetails.imageData = foo
é equivalente adetails.imageData = {'16': foo}
.
ShowAction
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 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á exibida em escala de cinza. Ao clicar nela, o menu de contexto será aberto em vez de acionar a ação.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: ShowAction) => {...}
-
arg
-
retorna
-
ShowPageAction
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á exibida em escala de cinza. Ao clicar nela, o menu de contexto será aberto em vez de acionar a ação.
Propriedades
-
construtor
void
A função
constructor
tem esta aparência:(arg: ShowPageAction) => {...}
-
arg
-
retorna
-
Eventos
onPageChanged
Fornece a API declarativa de eventos que consiste em addRules
, removeRules
e getRules
.