Esta página foi traduzida pela API Cloud Translation.

Scripts de conteúdo

Os scripts de conteúdo são arquivos executados no contexto de páginas da Web. Usando o Modelo de Objeto de Documento (DOM) padrão, eles podem ler detalhes das páginas da Web que o navegador visita, fazer mudanças nelas e transmitir informações para a extensão pai.

Entender os recursos do script de conteúdo

Os scripts de conteúdo podem acessar diretamente as seguintes APIs de extensão:

Os scripts de conteúdo não podem acessar outras APIs diretamente. No entanto, eles podem acessá-los indiretamente trocando mensagens com outras partes da extensão.

Também é possível acessar outros arquivos na extensão usando um script de conteúdo, com APIs como fetch(). Para fazer isso, é necessário declará-los como recursos acessíveis pela Web. Isso também expõe os recursos a qualquer script próprio ou de terceiros em execução no mesmo site.

Trabalhar em mundos isolados

Os scripts de conteúdo ficam em um mundo isolado, permitindo que um script de conteúdo faça mudanças no ambiente JavaScript sem conflito com a página ou outros scripts de conteúdo de extensões.

Uma extensão pode ser executada em uma página da Web com um código semelhante ao exemplo a seguir.

webPage.html

<html>
  <button id="mybutton">click me</button>
  <script>
    var greeting = "hello, ";
    var button = document.getElementById("mybutton");
    button.person_name = "Bob";
    button.addEventListener(
        "click", () => alert(greeting + button.person_name + "."), false);
  </script>
</html>

Essa extensão pode injetar o script de conteúdo a seguir usando uma das técnicas descritas na seção Injetar scripts.

content-script.js

var greeting = "hola, ";
var button = document.getElementById("mybutton");
button.person_name = "Roberto";
button.addEventListener(
    "click", () => alert(greeting + button.person_name + "."), false);

Com essa mudança, os dois alertas aparecem em sequência quando o botão é clicado.

Injetar scripts

Os scripts de conteúdo podem ser declarados de forma estática, declarados de forma dinâmica ou injetados programaticamente.

Injetar com declarações estáticas

Use declarações de script de conteúdo estático em manifest.json para scripts que precisam ser executados automaticamente em um conjunto conhecido de páginas.

Os scripts declarados de forma estática são registrados no manifesto com a chave "content_scripts". Eles podem incluir arquivos JavaScript, CSS ou ambos. Todos os scripts de conteúdo de execução automática precisam especificar padrões de correspondência.

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.nytimes.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"]
   }
 ],
 ...
}

Nome	Tipo	Descrição
`matches`	matriz de strings	Obrigatório. Especifica em quais páginas esse script de conteúdo será injetado. Consulte Padrões de correspondência para detalhes sobre a sintaxe dessas strings e Padrões de correspondência e globs para informações sobre como excluir URLs.
`css`	matriz de strings	Opcional. A lista de arquivos CSS que serão injetados nas páginas correspondentes. Elas são injetadas na ordem em que aparecem nessa matriz, antes que qualquer DOM seja criado ou exibido para a página.
`js`	matriz de strings	Opcional. A lista de arquivos JavaScript que serão injetados nas páginas correspondentes. Os arquivos são injetados na ordem em que aparecem nessa matriz. Cada string nesta lista precisa conter um caminho relativo a um recurso no diretório raiz da extensão. As barras invertidas iniciais ("/") são removidas automaticamente.
`run_at`	RunAt	Opcional. Especifica quando o script precisa ser injetado na página. O valor padrão é `document_idle`.
`match_about_blank`	booleano	Opcional. Indica se o script precisa ser injetado em um frame `about:blank` em que o frame pai ou de abertura corresponde a um dos padrões declarados em `matches`. O padrão é "false".
`match_origin_as_fallback`	booleano	Opcional. Define se o script precisa ser injetado em frames que foram criados por uma origem correspondente, mas cujo URL ou origem não correspondem diretamente ao padrão. Isso inclui frames com esquemas diferentes, como `about:`, `data:`, `blob:` e `filesystem:`. Consulte também Como injetar em frames relacionados.
`world`	ExecutionWorld	Opcional. O mundo do JavaScript para um script ser executado. O padrão é `ISOLATED`. Consulte também Trabalhar em mundos isolados.

Injetar com declarações dinâmicas

Os scripts de conteúdo dinâmico são úteis quando os padrões de correspondência para scripts de conteúdo não são bem conhecidos ou quando os scripts de conteúdo não são sempre injetados em hosts conhecidos.

As declarações dinâmicas, introduzidas no Chrome 96, são semelhantes às declarações estáticas, mas o objeto do script de conteúdo é registrado no Chrome usando métodos no namespace chrome.scripting em vez de no manifest.json. A API Scripting também permite que os desenvolvedores de extensões faça o seguinte:

Registre scripts de conteúdo.
Receba uma lista de scripts de conteúdo registrados.
Atualize a lista de scripts de conteúdo registrados.
Remova os scripts de conteúdo registrados.

Assim como as declarações estáticas, as declarações dinâmicas podem incluir arquivos JavaScript, CSS ou ambos.

service-worker.js

chrome.scripting
  .registerContentScripts([{
    id: "session-script",
    js: ["content.js"],
    persistAcrossSessions: false,
    matches: ["*://example.com/*"],
    runAt: "document_start",
  }])
  .then(() => console.log("registration complete"))
  .catch((err) => console.warn("unexpected error", err))

service-worker.js

chrome.scripting
  .updateContentScripts([{
    id: "session-script",
    excludeMatches: ["*://admin.example.com/*"],
  }])
  .then(() => console.log("registration updated"));

service-worker.js

chrome.scripting
  .getRegisteredContentScripts()
  .then(scripts => console.log("registered content scripts", scripts));

service-worker.js

chrome.scripting
  .unregisterContentScripts({ ids: ["session-script"] })
  .then(() => console.log("un-registration complete"));

Injetar de maneira programática

Use a injeção programática para scripts de conteúdo que precisam ser executados em resposta a eventos ou em ocasiões específicas.

Para injetar um script de conteúdo de forma programática, sua extensão precisa de permissões do host para a página em que ela está tentando injetar scripts. As permissões do host podem ser concedidas pedindo-as como parte do manifesto da extensão ou usando temporariamente "activeTab".

Confira a seguir diferentes versões de uma extensão baseada em activeTab.

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab",
    "scripting"
  ],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_title": "Action Button"
  }
}

Os scripts de conteúdo podem ser injetados como arquivos.

content-script.js


document.body.style.backgroundColor = "orange";

service-worker.js:

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ["content-script.js"]
  });
});

Ou um corpo de função pode ser injetado e executado como um script de conteúdo.

service-worker.js:

function injectedFunction() {
  document.body.style.backgroundColor = "orange";
}

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target : {tabId : tab.id},
    func : injectedFunction,
  });
});

A função injetada é uma cópia da função referenciada na chamada chrome.scripting.executeScript(), não a função original. Como resultado, o corpo da função precisa ser independente. Referências a variáveis fora da função farão com que o script de conteúdo gere uma ReferenceError.

Ao injetar como uma função, você também pode transmitir argumentos para ela.

service-worker.js

function injectedFunction(color) {
  document.body.style.backgroundColor = color;
}

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target : {tabId : tab.id},
    func : injectedFunction,
    args : [ "orange" ],
  });
});

Excluir correspondências e globs

Para personalizar a correspondência de página especificada, inclua os seguintes campos em um registro declarativo.

Nome	Tipo	Descrição
`exclude_matches`	matriz de strings	Opcional. Exclui páginas em que esse script de conteúdo seria injetado. Consulte Padrões de correspondência para detalhes sobre a sintaxe dessas strings.
`include_globs`	matriz de strings	Opcional. Aplicado após `matches` para incluir apenas os URLs que também correspondem a esse glob. O objetivo é emular a palavra-chave `@include` do Greasemonkey.
`exclude_globs`	matriz de string	Opcional. Aplicado após `matches` para excluir URLs que correspondem a esse padrão. Destina-se a emular a palavra-chave `@exclude` Greasemonkey.

O script de conteúdo será injetado em uma página se as duas condições a seguir forem verdadeiras:

O URL corresponde a qualquer padrão matches e include_globs.
O URL também não corresponde a um padrão exclude_matches ou exclude_globs. Como a propriedade matches é obrigatória, exclude_matches, include_globs e exclude_globs só podem ser usados para limitar quais páginas serão afetadas.

A extensão a seguir injeta o script de conteúdo em https://www.nytimes.com/health, mas não em https://www.nytimes.com/business .

manifest.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

service-worker.js

chrome.scripting.registerContentScripts([{
  id : "test",
  matches : [ "https://*.nytimes.com/*" ],
  excludeMatches : [ "*://*/*business*" ],
  js : [ "contentScript.js" ],
}]);

As propriedades glob seguem uma sintaxe diferente e mais flexível do que os padrões de correspondência. As strings glob aceitáveis são URLs que podem conter asteriscos "coringa" e pontos de interrogação. O asterisco (*) corresponde a qualquer string de qualquer tamanho, incluindo a string vazia, enquanto o ponto de interrogação (?) corresponde a qualquer caractere único.

Por exemplo, o glob https://???.example.com/foo/\* corresponde a qualquer um dos seguintes:

https://www.example.com/foo/bar
https://the.example.com/foo/

No entanto, ela não corresponde aos seguintes:

https://my.example.com/foo/bar
https://example.com/foo/
https://www.example.com/foo

Essa extensão injeta o script de conteúdo em https://www.nytimes.com/arts/index.html e https://www.nytimes.com/jobs/index.htm*, mas não em https://www.nytimes.com/sports/index.html:

manifest.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Essa extensão injeta o script de conteúdo em https://history.nytimes.com e https://.nytimes.com/history, mas não em https://science.nytimes.com ou https://www.nytimes.com/science:

manifest.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Uma, todas ou algumas delas podem ser incluídas para alcançar o escopo correto.

manifest.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Tempo de execução

O campo run_at controla quando os arquivos JavaScript são injetados na página da Web. O valor preferido e padrão é "document_idle". Consulte o tipo RunAt para conferir outros valores possíveis.

manifest.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "run_at": "document_idle",
      "js": ["contentScript.js"]
    }
  ],
  ...
}

service-worker.js

chrome.scripting.registerContentScripts([{
  id : "test",
  matches : [ "https://*.nytimes.com/*" ],
  runAt : "document_idle",
  js : [ "contentScript.js" ],
}]);

Nome	Tipo	Descrição
`document_idle`	string	Boa opção. Use `"document_idle"` sempre que possível. O navegador escolhe um momento para injetar scripts entre `"document_end"` e imediatamente após o evento `window.onload` ser acionado. O momento exato da injeção depende da complexidade do documento e do tempo que ele leva para carregar, além de ser otimizado para a velocidade de carregamento da página. Os scripts de conteúdo executados em `"document_idle"` não precisam detectar o evento `window.onload`. Eles são executados com certeza após a conclusão do DOM. Se um script precisar ser executado após `window.onload`, a extensão poderá verificar se `onload` já foi acionado usando a propriedade `document.readyState`.
`document_start`	string	Os scripts são injetados após os arquivos de `css`, mas antes que qualquer outro DOM seja criado ou que qualquer outro script seja executado.
`document_end`	string	Os scripts são injetados imediatamente após o DOM ser concluído, mas antes que subrecursos como imagens e frames sejam carregados.

Especificar frames

Para scripts de conteúdo declarativo especificados no manifesto, o campo "all_frames" permite que a extensão especifique se os arquivos JavaScript e CSS precisam ser injetados em todos os frames que correspondem aos requisitos de URL especificados ou apenas no frame mais alto em uma aba:

manifest.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "all_frames": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Ao registrar scripts de conteúdo de forma programática usando chrome.scripting.registerContentScripts(...), o parâmetro allFrames pode ser usado para especificar se o script de conteúdo precisa ser injetado em todos os frames que correspondem aos requisitos de URL especificados ou apenas no frame mais alto em uma guia. Ele só pode ser usado com tabId e não pode ser usado se frameIds ou documentIds forem especificados:

service-worker.js

chrome.scripting.registerContentScripts([{
  id: "test",
  matches : [ "https://*.nytimes.com/*" ],
  allFrames : true,
  js : [ "contentScript.js" ],
}]);

As extensões podem querer executar scripts em frames relacionados a um frame correspondente, mas que não correspondem. Um cenário comum é para frames com URLs que foram criados por um frame correspondente, mas cujos URLs não correspondem aos padrões especificados do script.

Isso acontece quando uma extensão quer injetar em frames com URLs que têm esquemas about:, data:, blob: e filesystem:. Nesses casos, o URL não corresponde ao padrão do script de conteúdo (e, no caso de about: e data:, nem mesmo inclui o URL pai ou a origem no URL, como em about:blank ou data:text/html,<html>Hello, World!</html>). No entanto, esses frames ainda podem ser associados ao frame de criação.

Para injetar nesses frames, as extensões podem especificar a propriedade "match_origin_as_fallback" em uma especificação de script de conteúdo no manifesto.

manifest.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.google.com/*"],
      "match_origin_as_fallback": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Quando especificado e definido como true, o Chrome verifica a origem do iniciador do frame para determinar se ele corresponde, em vez de verificar o URL do próprio frame. Isso também pode ser diferente da origem do frame de destino (por exemplo, Os URLs data: têm uma origem nula.

O iniciador do frame é o frame que criou ou navegou pelo frame de destino. Embora seja comum que ele seja o pai ou abridor direto, ele pode não ser (como no caso de um frame navegando em um iframe dentro de um iframe).

Como isso compara a origem do frame inicializador, ele pode estar em qualquer caminho dessa origem. Para deixar essa implicação clara, o Chrome exige que todos os scripts de conteúdo especificados com "match_origin_as_fallback" definido como true também especifiquem um caminho de *.

Quando "match_origin_as_fallback" e "match_about_blank" são especificados, "match_origin_as_fallback" tem prioridade.

Comunicação com a página de incorporação

Embora os ambientes de execução dos scripts de conteúdo e as páginas que os hospedam estejam isolados uns dos outros, eles compartilham o acesso ao DOM da página. Se a página quiser se comunicar com o script de conteúdo ou com a extensão por meio dele, ela precisará fazer isso pelo DOM compartilhado.

Um exemplo pode ser feito usando window.postMessage():

content-script.js

var port = chrome.runtime.connect();

window.addEventListener("message", (event) => {
  // We only accept messages from ourselves
  if (event.source !== window) {
    return;
  }

  if (event.data.type && (event.data.type === "FROM_PAGE")) {
    console.log("Content script received: " + event.data.text);
    port.postMessage(event.data.text);
  }
}, false);

example.js

document.getElementById("theButton").addEventListener("click", () => {
  window.postMessage(
      {type : "FROM_PAGE", text : "Hello from the webpage!"}, "*");
}, false);

A página sem extensão, example.html, envia mensagens para si mesma. Essa mensagem é interceptada e inspecionada pelo script de conteúdo e depois postada no processo de extensão. Dessa forma, a página estabelece uma linha de comunicação com o processo de extensão. A reversão é possível por meios semelhantes.

Acessar arquivos de extensão

Para acessar um arquivo de extensão em um script de conteúdo, chame chrome.runtime.getURL() para receber o URL absoluto do recurso de extensão, conforme mostrado no exemplo a seguir (content.js):

content-script.js

let image = chrome.runtime.getURL("images/my_image.png")

Para usar fontes ou imagens em um arquivo CSS, use @@extension_id para construir um URL, conforme mostrado no exemplo a seguir (content.css):

content.css

body {
 background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

@font-face {
 font-family: 'Stint Ultra Expanded';
 font-style: normal;
 font-weight: 400;
 src: url('chrome-extension://__MSG_@@extension_id__/fonts/Stint Ultra Expanded.woff') format('woff');
}

Todos os recursos precisam ser declarados como recursos acessíveis na Web no arquivo manifest.json:

manifest.json

{
 ...
 "web_accessible_resources": [
   {
     "resources": [ "images/*.png" ],
     "matches": [ "https://example.com/*" ]
   },
   {
     "resources": [ "fonts/*.woff" ],
     "matches": [ "https://example.com/*" ]
   }
 ],
 ...
}

Proteja-se

Embora os mundos isolados ofereçam uma camada de proteção, o uso de scripts de conteúdo pode criar vulnerabilidades em uma extensão e na página da Web. Se o script de conteúdo receber conteúdo de um site separado, como ao chamar fetch(), filtre o conteúdo contra ataques de script entre sites antes de injetá-lo. Só se comunique por HTTPS para evitar ataques "man-in-the-middle".

Filtre as páginas da Web maliciosas. Por exemplo, os padrões a seguir são perigosos e não são permitidos no Manifest V3:

O que não fazer

content-script.js

const data = document.getElementById("json-data");
// WARNING! Might be evaluating an evil script!
const parsed = eval("(" + data + ")");

O que não fazer

content-script.js

const elmt_id = ...
// WARNING! elmt_id might be '); ... evil script ... //'!
window.setTimeout("animate(" + elmt_id + ")", 200);

Em vez disso, prefira APIs mais seguras que não executam scripts:

O que fazer

content-script.js

const data = document.getElementById("json-data")
// JSON.parse does not evaluate the attacker's scripts.
const parsed = JSON.parse(data);

O que fazer

content-script.js

const elmt_id = ...
// The closure form of setTimeout does not evaluate scripts.
window.setTimeout(() => animate(elmt_id), 200);

Scripts de conteúdo

Entender os recursos do script de conteúdo

Trabalhar em mundos isolados

Injetar scripts

Injetar com declarações estáticas

Injetar com declarações dinâmicas

Injetar de maneira programática

Excluir correspondências e globs

Tempo de execução

Especificar frames

Injetar em frames relacionados

Comunicação com a página de incorporação

Acessar arquivos de extensão

Proteja-se