Manifesto - scripts de conteúdo

A chave "content_scripts" especifica um arquivo JavaScript ou CSS carregado estaticamente para ser usado sempre que uma página que corresponde a um determinado padrão do URL for aberta. As extensões também podem injetar scripts de conteúdo de forma programática. Consulte Como injetar scripts para mais detalhes.

Manifesto

Estas são as chaves compatíveis com "content_scripts". Somente a chave "matches" e "js" ou "css" são obrigatórios.

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 iniciais (/) são cortadas automaticamente. A chave "run_at" especifica quando cada arquivo será injetado.

"css": matriz
Opcional. Uma matriz de caminhos de arquivo CSS, injetada na ordem dessa matriz e antes de qualquer construção de DOM ou renderização de página.
"js": matriz,
Opcional. Uma matriz de caminhos de arquivo JavaScript, injetados na ordem em que aparecem nessa matriz, após a injeção de arquivos CSS. Cada string na matriz precisa ser um caminho relativo para um recurso no diretório raiz da extensão. As barras iniciais ('/') são cortadas automaticamente.

URLs de correspondência

Somente a propriedade "matches" é obrigatória. Em seguida, use "exclude_matches", "include_globs" e "exclude_globs" para personalizar os URLs em que o código será injetado. A chave "matches" vai acionar um aviso.

"matches": matriz
Obrigatório. Especifica em quais padrões de URL os scripts de conteúdo serão injetados. Consulte Padrões de correspondência para ver a sintaxe.
"exclude_matches": matriz
Opcional. Exclui os padrões do URL em que os scripts de conteúdo serão injetados. Consulte Padrões de correspondência para ver a sintaxe.
"include_globs": matriz
Opcional. Aplicado após as correspondências para incluir apenas os URLs que também correspondem a esse glob. Destinado a emular a palavra-chave @include do Greasemonkey.
"exclude_globs": matriz
Opcional. Aplicado após as correspondências para excluir URLs que correspondem a esse glob. Destinado a emular a palavra-chave @exclude do Greasemonkey.

Os URLs glob são aqueles que contêm "curingas" * 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 dele corresponde a qualquer padrão "matches" e "include_globs".
  • E o URL não corresponde aos padrões "exclude_matches" ou "exclude_globs".

Exemplos de correspondência de globs e URLs

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Correspondências
https://www.example.com/foo/bar
https://the.example.com/foo/
Não corresponde
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"]
    }
  ],
  ...
}
Correspondências
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
Não corresponde
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"]
    }
  ],
  ...
}
Correspondências
https://history.example.com
https://.example.com/music
Não corresponde
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"]
    }
  ],
  ...
}
Correspondências
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
Não corresponde
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 para URLs especificados. Se definido como false, ele só será injetado no frame superior. Ele 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.

"all_frames" Booleano
Opcional. O padrão é false, o que significa que apenas o frame superior é correspondido. Se definido como verdadeiro, ele será injetado em todos os frames, mesmo que o frame não seja o mais alto na guia. Cada frame é verificado de forma independente quanto aos requisitos para URLs. Ele não será injetado em frames filhos se os requisitos para URLs não forem atendidos.
"match_about_blank": booleano
Opcional. O valor padrão é false. Se o script precisa ser injetado em um frame about:blank em que o URL pai corresponde a um dos padrões declarados em "matches".
"match_origin_as_fallback": booleano
Opcional. O valor padrão é false. Se o script deve ser injetado em frames criados por uma origem correspondente, mas cujo URL ou origem pode não corresponder diretamente ao padrão. Isso inclui frames com esquemas diferentes, como about:, data:, blob: e filesystem:.

Ambiente de execução e tempo 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 ficam 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 mudar 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á carregando.
  • "document_end": os recursos da página ainda estão carregando.
  • "document_idle": o DOM e os recursos terminaram de carregar. Esse é o padrão.
"world" - ISOLATED | MAIN
Opcional. O mundo JavaScript em que um script será executado. O padrão é "ISOLATED", que é o ambiente de execução exclusivo do script de conteúdo. Escolher o mundo "MAIN" significa que o script vai compartilhar o ambiente de execução com o JavaScript da página 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.