Manifesto - scripts de conteúdo

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"]
    }
  ],
  ...
}
Correspondências
https://www.example.com/foo/bar
https://the.example.com/foo/
Sem correspondência
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
Sem correspondência
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
Sem correspondência
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
Sem correspondência
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 frame about: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, como about:, data:, blob: e filesystem:.

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.