browser.scripting

Descrição

Use a API chrome.scripting para executar scripts em diferentes contextos.

Permissões

scripting

Disponibilidade

Chrome 88+ browser.* desde o Chrome 148 MV3+

Manifesto

Para usar a API browser.scripting, declare a permissão "scripting" no manifesto, além das permissões de host para as 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 browser.scripting para injetar JavaScript e CSS em sites. Isso é semelhante ao que você pode fazer com scripts de conteúdo. No entanto, ao usar o namespace browser.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 em que o JavaScript ou o CSS será injetado.

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

function getTabId() { ... }

browser.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 como true.

function getTabId() { ... }

browser.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 frame, consulte a API browser.webNavigation.

function getTabId() { ... }

browser.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 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 vai injetar o arquivo script.js no frame principal da guia.

function getTabId() { ... }

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

Funções de ambiente de execução

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

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

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

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

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

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

Para contornar esse problema, use a propriedade args:

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

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

Strings de ambiente de execução

Se você estiver injetando CSS em uma página, também poderá especificar uma string para 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; }";

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

Processar 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 é garantido como o primeiro índice na matriz resultante. Todos os outros frames estão em uma ordem não determinística.

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

browser.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 vai aguardar que ela seja 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;
}

browser.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 que a extensão registrou anteriormente.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await browser.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return browser.scripting.unregisterContentScripts({ ids: 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 browser.scripting, instale o exemplo de script do repositório de exemplos de extensões do Chrome.

Tipos

ContentScriptFilter

Chrome 96+ browser.* desde o Chrome 148

Propriedades

CSSInjection

Propriedades

  • css

    string opcional

    Uma string que contém o CSS a ser injetado. É preciso especificar exatamente um files ou css.

  • arquivos

    string[] opcional

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

  • origem

    StyleOrigin opcional

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

  • destino

    InjectionTarget

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

ExecutionWorld

Chrome 95+ browser.* desde o Chrome 148

O mundo JavaScript em que um script será executado.

Enumeração

"ISOLATED"
Especifica o mundo isolado, que é o ambiente de execução exclusivo dessa 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+ browser.* desde o Chrome 148

    O documento associado à injeção.

  • frameId

    número

    Chrome 90+ browser.* desde o Chrome 148

    O frame associado à injeção.

  • resultado

    any optional

    O resultado da execução do script.

InjectionTarget

Propriedades

  • allFrames

    booleano opcional

    Se o script precisa ser injetado em todos os frames da guia. O padrão é "falso". Isso não pode ser verdadeiro se frameIds for especificado.

  • documentIds

    string[] opcional

    Chrome 106+ browser.* desde o Chrome 148

    Os IDs de documentIds específicos para injeção. Não defina esse campo se frameIds estiver definido.

  • frameIds

    number[] opcional

    Os IDs de frames específicos para injeção.

  • tabId

    número

    O ID da guia em que o script será injetado.

RegisteredContentScript

Chrome 96+ browser.* desde o Chrome 148

Propriedades

  • allFrames

    booleano opcional

    Se especificado como verdadeiro, ele será injetado em todos os frames, mesmo que o frame não seja o mais alto na guia. Cada frame é verificado de forma independente para os requisitos para URLs. Ele não será injetado em frames filhos se os requisitos para URLs não forem atendidos. O padrão é falso, o que significa que apenas 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 as 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 "_", porque esse caractere é 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 nessa matriz.

  • matchOriginAsFallback

    booleano opcional

    Chrome 119+ browser.* desde o Chrome 148

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

  • 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 esse script de conteúdo vai 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+ browser.* desde o Chrome 148

    O "mundo" do JavaScript em que o script será executado. O valor padrão é ISOLATED.

ScriptInjection

Propriedades

  • args

    any[] optional

    Chrome 92+ browser.* desde o Chrome 148

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

  • arquivos

    string[] opcional

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

  • injectImmediately

    booleano opcional

    Chrome 102+ browser.* desde o Chrome 148

    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, já que ela pode ter sido carregada antes de o script chegar ao destino.

  • destino

    InjectionTarget

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

  • mundo

    ExecutionWorld opcional

    Chrome 95+ browser.* desde o Chrome 148

    O "mundo" do JavaScript em que o script será executado. O valor padrão é ISOLATED.

  • func

    void optional

    Chrome 92+ browser.* desde o Chrome 148

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

    A função func é semelhante a: 

    () => {...}

StyleOrigin

A origem de uma mudança de estilo. Consulte as origens de estilo para mais informações.

Enumeração

"AUTOR"

"USER"

Métodos

executeScript()

browser.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

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 vai esperar que ela seja resolvida e vai retornar o valor resultante.

Parâmetros

Retorna

  • Promise<InjectionResult[]>

    Chrome 90+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida após a conclusão da injeção. A matriz resultante contém o resultado da execução de cada frame em que a injeção foi bem-sucedida.

getRegisteredContentScripts()

Chrome 96+ browser.* desde o Chrome 148 
browser.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Parâmetros

  • filtro

    ContentScriptFilter opcional

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

Retorna

insertCSS()

browser.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

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

Parâmetros

  • injeção

    CSSInjection

    Os detalhes dos estilos a serem inseridos.

Retorna

  • Promessa<void>

    Chrome 90+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida após a conclusão da inserção.

registerContentScripts()

Chrome 96+ browser.* desde o Chrome 148 
browser.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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.

Retorna

  • Promessa<void>

    Retorna uma promessa que é resolvida quando os scripts são totalmente registrados ou rejeitada se ocorre um erro.

removeCSS()

Chrome 90+ browser.* desde o Chrome 148 
browser.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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

Parâmetros

  • injeção

    CSSInjection

    Os detalhes dos estilos a serem removidos. As propriedades css, files e origin precisam corresponder exatamente à folha de estilo inserida por insertCSS. A tentativa de remover uma folha de estilo inexistente não causa nenhum efeito.

Retorna

  • Promessa<void>

    Retorna uma promessa que é resolvida após a conclusão da remoção.

unregisterContentScripts()

Chrome 96+ browser.* desde o Chrome 148 
browser.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

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

Parâmetros

  • filtro

    ContentScriptFilter opcional

    Se especificado, cancela apenas a inscrição de scripts de conteúdo dinâmico que correspondem ao filtro. Caso contrário, todos os scripts de conteúdo dinâmico da extensão serão cancelados.

Retorna

  • Promessa<void>

    Retorna uma promessa que é resolvida quando os scripts são cancelados ou rejeitada se ocorre um erro.

updateContentScripts()

Chrome 96+ browser.* desde o Chrome 148 
browser.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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 atual se for especificada neste 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.

Retorna

  • Promessa<void>

    Retorna uma promessa que é resolvida quando os scripts são atualizados ou rejeitada se ocorre um erro.