chrome.scripting

Descrição

Use a API chrome.scripting para executar o script em contextos diferentes.

Permissões

scripting

Disponibilidade

Chrome 88+ MV3+

Manifesto

Para usar a API chrome.scripting, declare a permissão "scripting" no manifesto, além das permissões de host para as páginas injetarem scripts. Use a chave "host_permissions" ou a permissão "activeTab", que concede permissões temporárias de host. O exemplo a seguir usa a permissão activeTab.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

Conceitos e uso

Você pode usar a API chrome.scripting para injetar JavaScript e CSS nos sites. Isso é parecido com o que é possível fazer com scripts de conteúdo. No entanto, ao usar o namespace chrome.scripting, as extensões podem tomar decisões no momento da execução.

Destinos de injeção

Use o parâmetro target para especificar um destino para injetar JavaScript ou CSS.

O único campo obrigatório é tabId. Por padrão, uma injeção será executada no frame principal da guia especificada.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

Para execução em todos os frames da guia especificada, defina o booleano allFrames como true.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

Também é possível injetar em frames específicos de uma guia especificando IDs de frame individuais. Para mais informações sobre IDs de frames, consulte a API chrome.webNavigation.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

Observação:não é possível especificar as propriedades "frameIds" e "allFrames" ao mesmo tempo.

Código injetado

As extensões podem especificar o código a ser injetado por um arquivo externo ou uma variável de ambiente de execução.

Arquivos

Os arquivos são especificados como strings que são caminhos relativos ao diretório raiz da extensão. O código a seguir injetará o arquivo script.js no frame principal da guia.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

Funções do ambiente de execução

Ao injetar JavaScript com scripting.executeScript(), você pode especificar uma função a ser executada em vez de um arquivo. Essa função precisa ser uma variável disponível para o contexto da extensão atual.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

Contorne isso usando a propriedade args:

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

Strings do ambiente de execução

Ao injetar CSS em uma página, você também pode especificar uma string a ser usada na propriedade css. Essa opção está disponível apenas para scripting.insertCSS(). Não é possível executar uma string usando scripting.executeScript().

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

Processar os resultados

Os resultados da execução de JavaScript são transmitidos para a extensão. Um único resultado é incluído por frame. O frame principal é o primeiro índice na matriz resultante. Todos os outros frames estão em uma ordem não determinista.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() não retorna resultados.

Promessas

Se o valor resultante da execução do script for uma promessa, o Chrome aguardará a liquidação da promessa e retornará o valor resultante.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

Exemplos

Cancelar o registro de todos os scripts de conteúdo dinâmico

O snippet a seguir contém uma função que cancela o registro de todos os scripts de conteúdo dinâmico registrados anteriormente pela extensão.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts(scriptIds);
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

Importante:o cancelamento do registro de scripts de conteúdo não remove scripts ou estilos que já foram injetados.

Para testar a API chrome.scripting, instale a amostra de script do repositório de exemplos de extensão do Chrome (links em inglês).

Tipos

ContentScriptFilter

Chrome 96 ou mais recente

Propriedades

• ids

  string[] opcional

  Se especificado, getRegisteredContentScripts só retornará scripts com um ID especificado nesta lista.

CSSInjection

Propriedades

• css

  string opcional

  String com o CSS a ser injetado. É necessário especificar exatamente um entre files ou css.

• arquivos

  string[] opcional

  O caminho dos arquivos CSS a serem injetados, relativo ao diretório raiz da extensão. É necessário especificar exatamente um entre files ou css.

• origem

  StyleOrigin opcional

  A origem do estilo da injeção. O valor padrão é 'AUTHOR'.

• destino

  InjectionTarget

  Detalhes que especificam o destino em que o CSS deve ser inserido.

ExecutionWorld

Chrome 95 ou mais recente

O mundo em JavaScript onde um script será executado.

Tipo enumerado

"ISOLATED"
Especifica o mundo isolado, que é o ambiente de execução exclusivo da extensão.

"MAIN"
Especifica o mundo principal do DOM, que é o ambiente de execução compartilhado com o JavaScript da página host.

InjectionResult

Propriedades

• documentId

  string

  Chrome 106 ou mais recente

  O documento associado à injeção.

• frameId

  number

  Chrome 90 ou mais recente

  O frame associado à injeção.

• resultado

  Qualquer opção opcional

  O resultado da execução do script.

InjectionTarget

Propriedades

• allFrames

  booleano opcional

  Indica se o script precisa injetar em todos os frames na guia. O padrão é "false". Isso não poderá ser verdadeiro se frameIds for especificado.

• documentIds

  string[] opcional

  Chrome 106 ou mais recente

  Os IDs de documentIds específicos a serem injetados. Isso não poderá ser definido se frameIds estiver definido.

• frameIds

  number[] opcional

  São os IDs de frames específicos a serem injetados.

• tabId

  number

  O ID da guia em que injetar.

RegisteredContentScript

Chrome 96 ou mais recente

Propriedades

• allFrames

  booleano opcional

  Se especificado como "true", ele será injetado em todos os frames, mesmo que o frame não seja o mais acima na guia. Cada frame é verificado de forma independente para verificar os requisitos de URL. Ele não será injetado em frames filhos se os requisitos de URL não forem atendidos. O padrão é "false", ou seja, somente o frame superior é correspondido.

• css

  string[] opcional

  A lista de arquivos CSS a serem injetados nas páginas correspondentes. Eles são injetados na ordem em que aparecem nessa matriz, antes que qualquer DOM seja construído ou exibido para a página.

• excludeMatches

  string[] opcional

  Exclui páginas em que esse script de conteúdo seria injetado. Consulte Padrões de correspondência para mais detalhes sobre a sintaxe dessas strings.

• id

  string

  O ID do script de conteúdo, especificado na chamada de API. Não pode começar com "_", já que ele está reservado como prefixo para IDs de script gerados.

• js

  string[] opcional

  A lista de arquivos JavaScript a serem injetados nas páginas correspondentes. Eles são injetados na ordem em que aparecem nesta matriz.

• matchOriginAsFallback

  booleano opcional

  Chrome 119 ou mais recente

  Indica se o script pode ser injetado em frames em que o URL contém um esquema não compatível. Especificamente: sobre:, dados:, blob: ou sistema de arquivos:. Nesses casos, a origem do URL é verificada para determinar se o script precisa ser injetado. Se a origem for null (como é o caso de "data: URLs"), a origem usada será o frame que criou o frame atual ou o que iniciou a navegação até esse frame. Esse pode não ser o frame pai.

• correspondências

  string[] opcional

  Especifica em quais páginas este script de conteúdo será injetado. Consulte Padrões de correspondência para mais detalhes sobre a sintaxe dessas strings. Precisa ser especificado para registerContentScripts.

• persistAcrossSessions

  booleano opcional

  Especifica se este script de conteúdo persistirá em sessões futuras. O padrão é "true".

• runAt

  RunAt opcional

  Especifica quando os arquivos JavaScript são injetados na página da Web. O valor preferencial e padrão é document_idle.

• mundo

  ExecutionWorld opcional

  Chrome 102 ou mais recente

  O "mundo" JavaScript no qual executar o script. O valor padrão é ISOLATED.

ScriptInjection

Propriedades

• args

  qualquer[] opcional

  Chrome 92 ou mais recente

  Os argumentos a serem transmitidos para a função fornecida. Isso só será válido se o parâmetro func for especificado. Esses argumentos precisam ser serializáveis por JSON.

• arquivos

  string[] opcional

  O caminho dos arquivos JS ou CSS a serem injetados, relativo ao diretório raiz da extensão. É necessário especificar exatamente um entre files ou func.

• injectImmediately

  booleano opcional

  Chrome 102 ou mais recente

  Define se a injeção precisa ser acionada no destino o mais rápido possível. Isso não garante que a injeção ocorrerá antes do carregamento da página, já que ela pode já ter sido carregada no momento em que o script atingir o destino.

• destino

  InjectionTarget

  Detalhes que especificam o destino em que o script será injetado.

• mundo

  ExecutionWorld opcional

  Chrome 95 ou mais recente

  O "mundo" JavaScript no qual executar o script. O valor padrão é ISOLATED.

• func

  void optional

  Chrome 92 ou mais recente

  Uma função JavaScript a ser injetada. Essa função será serializada e desserializada para injeção. Isso significa que todos os parâmetros vinculados e contextos de execução serão perdidos. É necessário especificar exatamente um entre files ou func.

  A função func tem esta aparência:

  ()=> {...}

StyleOrigin

Origem de uma alteração de estilo. Confira as origens de estilo para mais informações.

Tipo enumerado

Métodos

executeScript()

Promessa

chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

Injeta um script em um contexto de destino. Por padrão, o script será executado em document_idle ou imediatamente se a página já tiver sido carregada. Se a propriedade injectImmediately for definida, o script vai injetar sem aguardar, mesmo que a página não tenha concluído o carregamento. Se o script for avaliado como uma promessa, o navegador aguardará a liquidação da promessa e retornará o valor resultante.

Parâmetros

• Injeção

  ScriptInjection

  Detalhes do script que será injetado.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  (results: InjectionResult[])=>void

  • resultados

    InjectionResult[]

Retorna

• Promise<InjectionResult[]>

  Chrome 90 ou mais recente

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getRegisteredContentScripts()

Promise Chrome 96+

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Retorna todos os scripts de conteúdo registrados dinamicamente para esta extensão que correspondem ao filtro especificado.

Parâmetros

• Função filter

  ContentScriptFilter opcional

  Um objeto para filtrar os scripts registrados dinamicamente da extensão.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  (scripts: RegisteredContentScript[])=>void

  • scripts

    RegisteredContentScript[]

Retorna

• Promise<RegisteredContentScript[]>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

insertCSS()

Promessa

chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

Insere uma folha de estilo CSS em um contexto de destino. Se vários frames forem especificados, as injeções malsucedidas serão ignoradas.

Parâmetros

• Injeção

  CSSInjection

  Detalhes dos estilos a serem inseridos.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Chrome 90 ou mais recente

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

registerContentScripts()

Promise Chrome 96+

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Registra um ou mais scripts de conteúdo para esta extensão.

Parâmetros

• scripts

  RegisteredContentScript[]

  Contém uma lista de scripts a serem registrados. Se houver erros durante a análise de script/validação de arquivo, ou se os IDs especificados já existirem, nenhum script será registrado.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

removeCSS()

Promessa Chrome 90 e versões mais recentes

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

Remove uma folha de estilo CSS inserida anteriormente por essa extensão de um contexto de destino.

Parâmetros

• Injeção

  CSSInjection

  Detalhes dos estilos a serem removidos. Observe que as propriedades css, files e origin precisam corresponder exatamente à folha de estilo inserida por insertCSS. A tentativa de remover uma folha de estilo inexistente é um ambiente autônomo.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

unregisterContentScripts()

Promise Chrome 96+

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Cancela o registro dos scripts de conteúdo para esta extensão.

Parâmetros

• Função filter

  ContentScriptFilter opcional

  Se especificado, somente cancela o registro de scripts de conteúdo dinâmico que correspondem ao filtro. Caso contrário, o registro de todos os scripts de conteúdo dinâmico da extensão será cancelado.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

updateContentScripts()

Promise Chrome 96+

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Atualiza um ou mais scripts de conteúdo para esta extensão.

Parâmetros

• scripts

  RegisteredContentScript[]

  Contém uma lista de scripts a serem atualizados. Uma propriedade só é atualizada para o script existente se ele for especificado nesse objeto. Se houver erros durante a análise do script/validação do arquivo, ou se os IDs especificados não corresponderem a um script totalmente registrado, nenhum script será atualizado.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.