chrome.scripting

Descrição

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

Permissões

scripting

Disponibilidade

Chrome 88 ou superior MV3+

Manifesto

Para usar a API chrome.scripting, declare a permissão "scripting" no manifesto, além das permissões de host nas páginas em que os scripts serão injetados. 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

Use a API chrome.scripting para injetar JavaScript e CSS em e sites. Isso é parecido com o que você pode fazer com conteúdos scripts. Mas, usando o namespace chrome.scripting, as extensões possam tomar decisões durante a execução.

Metas 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 é executada frame principal da guia especificada.

function getTabId() { ... }

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

Para executar em todos os frames da guia especificada, defina o booleano allFrames. para 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 um frame individual. do Google Ads. Para mais informações sobre IDs de frames, consulte a chrome.webNavigation API.

function getTabId() { ... }

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

Código injetado

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

Arquivos

Os arquivos são especificados como strings que são caminhos relativos à raiz da extensão. diretório. O código abaixo injetará o arquivo script.js na frame 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 um seja executada no lugar de um arquivo. Esta função precisa ser uma função variável disponível para o contexto de 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"));

É possível contornar esse problema 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 no css. Esta opção está disponível apenas para scripting.insertCSS(). você 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"));

Gerencie os resultados

Os resultados da execução do JavaScript são transmitidos para a extensão. Um único resultado é incluído por frame. O frame principal é o primeiro índice da 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 nenhum resultado.

Promessas

Se o valor resultante da execução do script for uma promessa, o Chrome aguardará pela promessa ser resolvida 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 todo o conteúdo dinâmico scripts 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});
  }
}

Para testar a API chrome.scripting, Instale o exemplo de script dos exemplos de extensão do Chrome repositório de dados.

Tipos

ContentScriptFilter

Chrome 96 ou versão mais recente

Propriedades

CSSInjection

Propriedades

  • css

    string opcional

    String com o CSS a ser injetado. É preciso especificar exatamente files ou css.

  • arquivos

    string[] opcional

    O caminho dos arquivos CSS a serem injetados, em relação ao diretório raiz da extensão. É preciso especificar exatamente files ou css.

  • origem

    StyleOrigin opcional

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

  • Detalhes que especificam o destino em que o CSS será inserido.

ExecutionWorld

Chrome 95 ou versão mais recente

O mundo JavaScript no qual um script pode ser executado.

Enumeração

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

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

InjectionResult

Propriedades

  • documentId

    string

    Chrome 106 ou versões mais recentes

    O documento associado à injeção.

  • frameId

    number

    Chrome 90 ou posterior

    O frame associado à injeção.

  • resultado

    opcional

    O resultado da execução do script.

InjectionTarget

Propriedades

  • allFrames

    booleano opcional

    Define se o script deve 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 versões mais recentes

    Os IDs de documentIds específicos em que os dados serão injetados. Isso não poderá ser definido se frameIds estiver definido.

  • frameIds

    number[] opcional

    São os IDs de frames específicos em que a injeção será realizada.

  • tabId

    number

    O ID da guia na qual injetar.

RegisteredContentScript

Chrome 96 ou versão mais recente

Propriedades

  • allFrames

    booleano opcional

    Se especificado como verdadeiro, ele será injetado em todos os frames, mesmo que não seja o frame superior da guia. Cada frame é verificado independentemente dos requisitos de URL. ele não injetará 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 de qualquer DOM ser construído ou exibido para a página.

  • excludeMatches

    string[] opcional

    Exclui páginas em que esse script de conteúdo seria injetado de outra forma. 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 é reservado como um prefixo para IDs de script gerados.

  • js

    string[] opcional

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

  • matchOriginAsFallback

    booleano opcional

    Chrome 119 ou versões mais recentes

    Indica se o script pode ser injetado em frames em que o URL contém um esquema não suportado. especificamente: about:, data:, blob: ou system:. Nesses casos, a origem do URL é verificada para determinar se o script deve ser injetado. Se a origem for null (como é o caso de dados: URLs), a origem usada será o frame que criou o frame atual ou que iniciou a navegação para esse frame. Esse pode não ser o frame principal.

  • correspondências

    string[] opcional

    Especifica em quais páginas esse 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 é verdadeiro.

  • 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 versões mais recentes

    O "mundo" do JavaScript para executar o script. O valor padrão é ISOLATED.

ScriptInjection

Propriedades

  • args

    any[] opcional

    Chrome 92 ou versões mais recentes

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

  • arquivos

    string[] opcional

    O caminho dos arquivos JS ou CSS a serem injetados, em relação ao diretório raiz da extensão. É preciso especificar exatamente files ou func.

  • injectImmediately

    booleano opcional

    Chrome 102 ou versões mais recentes

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

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

  • mundo

    ExecutionWorld opcional

    Chrome 95 ou versão mais recente

    O "mundo" do JavaScript para executar o script. O valor padrão é ISOLATED.

  • func

    void opcional

    Chrome 92 ou versões mais recentes

    Uma função JavaScript a ser injetada. Essa função será serializada e, em seguida, desserializada para injeção. Isso significa que todos os parâmetros vinculados e contexto de execução serão perdidos. É preciso especificar exatamente files ou func.

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

    () => {...}

StyleOrigin

A origem de uma alteração de estilo. Consulte as origens dos estilos para mais informações.

Enumeração

"AUTHOR"

"USUÁRIO"

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 estiver definida, o script será injetado sem esperar, mesmo que a página não tenha terminado de carregar. Se o script for avaliado como uma promessa, o navegador aguardará a conclusão da promessa e retornará o valor resultante.

Parâmetros

Retorna

  • Promise<InjectionResult[]>

    Chrome 90 ou posterior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getRegisteredContentScripts()

Promessa Chrome 96 ou versões mais recentes 
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

Retorna

  • Promise<RegisteredContentScript[]>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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

    Os detalhes dos estilos a serem inseridos.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 90 ou posterior

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

registerContentScripts()

Promessa Chrome 96 ou versões mais recentes 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

Parâmetros

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

removeCSS()

Promessa Chrome 90 ou versões mais recentes 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

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

Parâmetros

  • Injeção

    CSSInjection

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

unregisterContentScripts()

Promessa Chrome 96 ou versões mais recentes 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

Parâmetros

  • filtro

    ContentScriptFilter opcional

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

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

updateContentScripts()

Promessa Chrome 96 ou versões mais recentes 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

Parâmetros

  • Contém uma lista de scripts a serem atualizados. Uma propriedade só será 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 opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.