Esta página foi traduzida pela API Cloud Translation.

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"));

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

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

ids

string[] opcional

Se especificado, getRegisteredContentScripts vai retornar apenas scripts com um ID especificado nessa lista.

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'.
target

InjectionTarget

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.
target

InjectionTarget

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

Injeção

ScriptInjection

Os detalhes do script a ser injetado.

Retorna

Promise<InjectionResult[]>

Chrome 90 ou mais recente

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

Promise<RegisteredContentScript[]>

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

scripts

RegisteredContentScript[]

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

scripts

RegisteredContentScript[]

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>

chrome.scripting Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Permissões

Disponibilidade

Manifesto

Conceitos e uso

Destinos de injeção

Código injetado

Arquivos

Funções de tempo de execução

Strings de tempo de execução

Processar os resultados

Promessas

Exemplos

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

Tipos

ContentScriptFilter

Propriedades

CSSInjection

Propriedades

ExecutionWorld

Enumeração

InjectionResult

Propriedades

InjectionTarget

Propriedades

RegisteredContentScript

Propriedades

ScriptInjection

Propriedades

StyleOrigin

Enumeração

Métodos

executeScript()

Parâmetros

Retorna

getRegisteredContentScripts()

Parâmetros

Retorna

insertCSS()

Parâmetros

Retorna

registerContentScripts()

Parâmetros

Retorna

removeCSS()

Parâmetros

Retorna

unregisterContentScripts()

Parâmetros

Retorna

updateContentScripts()

Parâmetros

Retorna

chrome.scripting