A chave "content_scripts"
especifica um arquivo JavaScript ou CSS carregado estaticamente que será usado sempre que uma página for aberta correspondente a um determinado padrão de URL. As extensões também podem injetar scripts de conteúdo de maneira programática. Consulte Como injetar scripts para mais detalhes.
Manifesto
Estas são as chaves aceitas para "content_scripts"
. Apenas a chave "matches"
e "js"
ou "css"
são obrigatórias.
manifest.json
{
"name": "My extension",
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"css": ["my-styles.css"],
"js": ["content-script.js"],
"exclude_matches": ["*://*/*foo*"],
"include_globs": ["*example.com/???s/*"],
"exclude_globs": ["*bar*"],
"all_frames": false,
"match_origin_as_fallback": false,
"match_about_blank": false,
"run_at": "document_idle",
"world": "ISOLATED",
}
],
...
}
Arquivos
Cada arquivo precisa conter um caminho relativo para um recurso no diretório raiz da extensão. As barras à esquerda (/
) são cortadas automaticamente. A chave "run_at"
especifica quando cada arquivo será injetado.
"css"
: matriz- Opcional. Uma matriz de caminhos de arquivos CSS, injetada na ordem dessa matriz e antes de qualquer construção do DOM ou renderização de página.
"js"
: matriz,- Opcional. Uma matriz de caminhos de arquivos JavaScript, injetados na ordem em que aparecem nesta matriz, depois que os arquivos css são injetados. Cada string na matriz precisa ser um caminho relativo para um recurso no diretório raiz da extensão. As barras iniciais ("/") são automaticamente cortadas.
URLs correspondentes
Apenas a propriedade "matches"
é obrigatória. Em seguida, use "exclude_matches"
, "include_globs"
e "exclude_globs"
para personalizar em quais URLs injetar código. A chave "matches"
acionará um alerta.
"matches"
: matriz- Obrigatório. Especifica em quais padrões de URL injetar os scripts de conteúdo. Consulte a sintaxe em Padrões de correspondência.
"exclude_matches"
: matriz- Opcional. Exclui os padrões de URL para injetar os scripts de conteúdo. Consulte a sintaxe em Padrões de correspondência.
"include_globs"
: matriz- Opcional. Aplicado após correspondências para incluir apenas os URLs que também correspondem a este glob. Destina-se a emular a palavra-chave @include Greasemonkey.
"exclude_globs"
: matriz- Opcional. Aplicado após as correspondências para excluir URLs que correspondem a este glob. Destina-se a emular a palavra-chave @exclude Greasemonkey.
URLs glob são aqueles que contêm "caracteres curinga" * e pontos de interrogação. O caractere curinga * corresponde a qualquer string de qualquer tamanho, incluindo uma string vazia, enquanto o ponto de interrogação ? corresponde a qualquer caractere único.
O script de conteúdo é injetado em uma página se:
- O URL dela corresponde a todos os padrões
"matches"
e"include_globs"
. - E o URL não corresponde aos padrões
"exclude_matches"
ou"exclude_globs"
.
Exemplos de correspondência de globos e URLs
"include_globs"
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"include_globs": ["https://???.example.com/foo/*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/foo/bar https://the.example.com/foo/
https://my.example.com/foo/bar https://example.com/foo/* https://www.example.com/foo
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"include_globs": ["*example.com/???s/*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/arts/index.html https://www.example.com/jobs/index.html
https://www.example.com/sports/index.html https://www.example.com/music/index.html
"exclude_globs"
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"exclude_globs": ["*science*"],
"js": ["content-script.js"]
}
],
...
}
https://history.example.com https://.example.com/music
https://science.example.com https://www.example.com/science
Exemplo de personalização avançada
manifest.json
{
...
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"exclude_matches": ["*://*/*business*"],
"include_globs": ["*example.com/???s/*"],
"exclude_globs": ["*science*"],
"js": ["content-script.js"]
}
],
...
}
https://www.example.com/arts/index.html https://.example.com/jobs/index.html
https://science.example.com https://www.example.com/jobs/business https://www.example.com/science
Frames
A chave "all_frames"
especifica se o script de conteúdo precisa ser injetado em todos os frames que correspondem aos requisitos de URL especificados. Se definido como false
, a injeção será feita apenas no frame superior. Pode ser usado com "match_about_blank"
para injetar em um frame about:blank
.
Para injetar em outros frames, como data:
, blob:
e filesystem:
, defina "match_origin_as_fallback"
como true
. Para mais detalhes, consulte Injetar em frames relacionados.
- Booleano
"all_frames"
- Opcional. O padrão é
false
, o que significa que somente o frame superior é correspondido. Se definida como "true", ela será injetada em todos os frames, mesmo que não seja o primeiro frame na guia. Cada frame é verificado de maneira independente para verificar os requisitos de URL. Ele não será injetado em frames filhos se os requisitos de URL não forem atendidos. "match_about_blank"
: booleano- Opcional. Por padrão, é configurado como
false
. Indica se o script precisa injetar em um frameabout:blank
em que o URL pai corresponde a um dos padrões declarados em"matches"
. "match_origin_as_fallback"
: booleano- Opcional. Por padrão, é configurado como
false
. Define se o script precisa injetar em frames que foram criados por uma origem correspondente, mas cujo URL ou origem pode não corresponder diretamente ao padrão. Isso inclui frames com esquemas diferentes, comoabout:
,data:
,blob:
efilesystem:
.
Tempo de execução e ambiente de execução
Por padrão, os scripts de conteúdo são injetados quando o documento e todos os recursos terminam de carregar e residem em um ambiente de execução isolado e particular que não pode ser acessado pela página ou por outras extensões. É possível alterar esses padrões nas seguintes chaves:
"run_at"
-document_start
|document_end
|document_idle
- Opcional. Especifica quando o script precisa ser injetado na página. Ele corresponde aos estados de carregamento de Document.readyState:
"document_start"
: o DOM ainda está sendo carregado."document_end"
: os recursos da página ainda estão sendo carregados"document_idle"
: o DOM e os recursos foram carregados. Esse é o padrão.
"world"
-ISOLATED
|MAIN
- Opcional. O mundo em JavaScript onde um script será executado. O padrão é
"ISOLATED"
, que é o ambiente de execução exclusivo do script de conteúdo. Escolher a configuração"MAIN"
significa que o script compartilhará o ambiente de execução com o JavaScript da página do host. Consulte Trabalhar em mundos isolados para saber mais.
Exemplo
Consulte o tutorial Executar em todas as páginas para criar uma extensão que injeta um script de conteúdo no manifesto.