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

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

Ponto-chave: cancelar o registro de scripts de conteúdo não remove scripts ou estilos já foi injetada.

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

• ids

  string[] opcional

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

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

• target

  InjectionTarget

  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.

• target

  InjectionTarget

  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

• Injeção

  ScriptInjection

  Os detalhes do script a ser injetado.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (results: InjectionResult[]) => void

  • resultados

    InjectionResult[]

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

• filtro

  ContentScriptFilter opcional

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

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (scripts: RegisteredContentScript[]) => void

  • scripts

    RegisteredContentScript[]

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

• scripts

  RegisteredContentScript[]

  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

• scripts

  RegisteredContentScript[]

  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.