Manifesto - scripts de conteúdo

A chave "content_scripts" especifica um arquivo JavaScript ou CSS carregado estaticamente a ser usado sempre que for aberta uma página que corresponda a um determinado padrão de URL. 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". 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 iniciais (/) são cortadas automaticamente. A chave "run_at" especifica quando cada arquivo será injetado.

"css": matriz
Opcional. Uma matriz de caminhos de arquivos CSS, injetados 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 nessa 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 cortadas automaticamente.

URLs de correspondência

Apenas a propriedade "matches" é obrigatória. Em seguida, use "exclude_matches", "include_globs" e "exclude_globs" para personalizar em quais URLs injetar o código. A chave "matches" aciona um aviso.

"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 em que os scripts de conteúdo serão injetados. Consulte a sintaxe em Padrões de correspondência.
"include_globs": matriz
Opcional. Aplicado após as correspondências para incluir apenas os URLs que também correspondem a este glob. que serve para emular a palavra-chave @include Greasemonkey.
"exclude_globs": matriz
Opcional. Aplicado após as correspondências para excluir URLs que correspondem a este glob. que serve para 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 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 Globs e URL

"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 de URL especificados. Se definido como false, ele só injetará 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

Booleano "all_frames"
Opcional. O padrão é false, o que significa que apenas o frame superior é correspondido. Se definida como verdadeira, ela será injetada em todos os frames, mesmo que não seja o frame superior da guia. Cada frame é verificado de maneira independente para cumprir 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. O valor padrão é false. Define se o script precisa injetar 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. Define se o script deve 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, como about:, data:, blob: e filesystem:.

Ambiente e ambiente de execução

Por padrão, os scripts de conteúdo são injetados quando o carregamento do documento e de todos os recursos são concluídos 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 alterar esses padrões nas seguintes chaves:

"run_at" a document_start | document_end | document_idle
Opcional. Especifica quando o script deve 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" a ISOLATED | MAIN
Opcional. O mundo JavaScript no qual um script pode 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 compartilhará o ambiente de execução com o JavaScript da página host. Consulte Trabalho em mundos isolados para saber mais.
.

Exemplo

Consulte o tutorial Executar em todas as páginas para criar uma extensão que insira um script de conteúdo no manifesto.