chrome.scripting

Descrição

Use a API chrome.scripting para executar scripts 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 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

É possível usar a API chrome.scripting para injetar JavaScript e CSS em sites. Isso é semelhante ao que você pode fazer com scripts de conteúdo. Mas, ao usar o namespace chrome.scripting, as extensões podem tomar decisões durante a execução.

Destinos de injeção

É possível usar o parâmetro target para especificar um destino em que injetar JavaScript ou CSS.

O único campo obrigatório é tabId. Por padrão, uma injeção é executada no 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 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 frame, 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"));

Código injetado

As extensões podem especificar o código a ser injetado usando um arquivo externo ou uma variável de tempo 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() { ... }  chrome.scripting     .executeScript({       target : {tabId : getTabId()},       files : [ "script.js" ],     })     .then(() => console.log("injected script file"));

Funções de tempo 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 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"));

Você pode solucionar 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 de tempo de execução

Se você estiver injetando CSS em uma página, também poderá 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 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 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 vai aguardar a conclusã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 que a extensão registrou anteriormente.

async function unregisterAllDynamicContentScripts() {   try {     const scripts = await chrome.scripting.getRegisteredContentScripts();     const scriptIds = scripts.map(script => script.id);     return chrome.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 chrome.scripting, instale a amostra de script do repositório Amostras de extensões do Chrome.

Tipos

ContentScriptFilter

Chrome 96+

Propriedades

CSSInjection

Propriedades

  • css

    string opcional

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

  • arquivos

    string[] opcional

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

  • origem

    StyleOrigin opcional

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

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

ExecutionWorld

Chrome 95+

O mundo JavaScript em que um script é 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 ou mais recente

    O documento associado à injeção.

  • frameId

    número

    Chrome 90 ou mais recente

    O frame associado à injeção.

  • resultado

    qualquer opcional

    O resultado da execução do script.

InjectionTarget

Propriedades

  • allFrames

    booleano opcional

    Define se o script deve ser injetado em todos os frames da guia. O padrão é "false". Não pode ser verdadeiro se frameIds for especificado.

  • documentIds

    string[] opcional

    Chrome 106 ou mais recente

    Os IDs de documentIds específicos a serem injetados. Não pode ser definido se frameIds estiver definido.

  • frameIds

    number[] opcional

    Os IDs de frames específicos para inserir.

  • tabId

    número

    O ID da guia em que será feita a injeção.

RegisteredContentScript

Chrome 96+

Propriedades

  • allFrames

    booleano opcional

    Se for especificado como "true", 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 quanto aos requisitos de URL. Ele não será injetado em frames filhos se os requisitos de URL não forem atendidos. O padrão é "false", o que significa que apenas o frame superior é correspondido.

  • css

    string[] opcional

    A lista de arquivos CSS a serem injetados em 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 o 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 um "_", já que ele é 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+

    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 até ele. Essa não é necessariamente a frame mãe.

  • correspondências

    string[] opcional

    Especifica em quais páginas o 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 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 preferido e padrão é document_idle.

  • mundo

    ExecutionWorld opcional

    Chrome 102 ou mais recente

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

ScriptInjection

Propriedades

  • args

    any[] opcional

    Chrome 92 ou mais recente

    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 de files ou func.

  • injectImmediately

    booleano opcional

    Chrome 102 ou mais recente

    Se a injeção deve ser acionada no destino assim que 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 quando o script atingir o destino.

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

  • mundo

    ExecutionWorld opcional

    Chrome 95+

    O "mundo" do JavaScript em que o script será executado. 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 o contexto de execução serão perdidos. É preciso especificar exatamente um de files ou func.

    A função func é assim: 

    () => {...}

StyleOrigin

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

Enumeração

"AUTHOR"

"USER"

Métodos

executeScript()

chrome.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 aguardar a conclusão da promessa e retornar o valor resultante.

Parâmetros

Retorna

getRegisteredContentScripts()

Chrome 96+ 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Parâmetros

  • filtrar

    ContentScriptFilter opcional

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

Retorna

insertCSS()

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

Insere uma folha de estilos 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

  • Promise<void>

    Chrome 90 ou mais recente

registerContentScripts()

Chrome 96+ 
chrome.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 de arquivo ou se os IDs especificados já existirem, nenhum script será registrado.

Retorna

  • Promise<void>

removeCSS()

Chrome 90 ou mais recente 
chrome.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

  • Promise<void>

unregisterContentScripts()

Chrome 96+ 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

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

Parâmetros

  • filtrar

    ContentScriptFilter opcional

    Se especificado, cancela apenas o registro dos 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

  • Promise<void>

updateContentScripts()

Chrome 96+ 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

Parâmetros

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

  • Promise<void>