chrome.userScripts

Descrição

Use a API userScripts para executar scripts de usuário no contexto deles.

Permissões

userScripts

Para usar a API chrome.userScripts, adicione a permissão "userScripts" ao manifesto.json e "host_permissions" para os sites em que você quer executar scripts.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Disponibilidade

Chrome 120 ou mais recente MV3+

Conceitos e uso

Um script de usuário é um pouco de código injetado em uma página da Web para modificar sua aparência ou comportamento. Os scripts são criados pelos usuários ou baixados de um repositório de scripts ou de uma extensão de script de usuário.

Modo de desenvolvedor para usuários de extensões

Como desenvolvedor de extensão, você já ativou o modo de desenvolvedor na sua instalação do Chrome. Para extensões de script de usuário, seus usuários também precisarão ativar o modo de desenvolvedor. Veja as instruções que você pode copiar e colar na sua documentação.

  1. Acesse a página "Extensões" digitando chrome://extensions em uma nova guia. Por padrão, os URLs do chrome:// não podem ser vinculados.

  2. Ative o modo de desenvolvedor clicando no botão ao lado de Modo de desenvolvedor.

    Página "Extensões"

    Página "Extensões" (chrome://extensions)

É possível determinar se o modo de desenvolvedor está ativado verificando se o chrome.userScripts gera um erro. Exemplo:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Trabalhe em mundos isolados

Os scripts de usuário e de conteúdo podem ser executados em um mundo isolado ou no mundo principal. Um mundo isolado é um ambiente de execução que não pode ser acessado por uma página de host ou outras extensões. Isso permite que um script de usuário altere seu ambiente JavaScript sem afetar a página do host ou outras extensões scripts de usuário e conteúdo. Por outro lado, os scripts de usuário (e scripts de conteúdo) não são visíveis para a página de host ou para os scripts de usuário e de conteúdo de outras extensões. Os scripts em execução no mundo principal são acessíveis para páginas de hospedagem e outras extensões e são visíveis para páginas de hospedagem e para outras extensões. Para selecionar o mundo, transmita "USER_SCRIPT" ou "MAIN" ao chamar userScripts.register().

Para configurar uma Política de Segurança de Conteúdo para o mundo USER_SCRIPT, chame userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Mensagens

Assim como os scripts de conteúdo e os documentos fora da tela, os scripts de usuário se comunicam com outras partes de uma extensão usando mensagens, o que significa que eles podem chamar runtime.sendMessage() e runtime.connect() como qualquer outra parte de uma extensão. No entanto, eles são recebidos usando manipuladores de eventos dedicados (ou seja, eles não usam onMessage ou onConnect). Esses gerenciadores são chamados de runtime.onUserScriptMessage e runtime.onUserScriptConnect. Manipuladores dedicados facilitam a identificação de mensagens de scripts de usuário, que são um contexto menos confiável.

Antes de enviar uma mensagem, chame configureWorld() com o argumento messaging definido como true. Os argumentos csp e messaging podem ser transmitidos ao mesmo tempo.

chrome.userScripts.configureWorld({
  messaging: true
});

Atualizações de extensão

Os scripts de usuário são apagados quando uma extensão é atualizada. Você pode adicioná-las novamente executando o código no manipulador de eventos runtime.onInstalled no service worker de extensão. Responda apenas ao motivo "update" transmitido ao callback do evento.

Exemplo

Este exemplo é da amostra de userScript no nosso repositório de exemplos.

Registrar um script

O exemplo a seguir mostra uma chamada básica para register(). O primeiro argumento é uma matriz de objetos que definem os scripts a serem registrados. Há mais opções do que as mostradas aqui.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Tipos

ExecutionWorld

O mundo JavaScript para execução de um script de usuário.

Enumeração

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

"USER_SCRIPT"
Especifica o ambiente de execução específico dos scripts de usuário e está isento da CSP da página.

RegisteredUserScript

Propriedades

  • allFrames

    booleano opcional

    Se definido como verdadeiro, ele será injetado em todos os frames, mesmo que não seja o que está no topo 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.

  • excludeGlobs

    string[] opcional

    Especifica padrões de caracteres curinga em páginas em que o script do usuário NÃO será injetado.

  • excludeMatches

    string[] opcional

    Exclui páginas em que esse script de usuário 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 usuário especificado na chamada da API. Esta propriedade não pode começar com "_" já que é reservado como um prefixo para IDs de script gerados.

  • includeGlobs

    string[] opcional

    Especifica padrões de caracteres curinga em páginas em que o script do usuário será injetado.

  • A lista de objetos ScriptSource que definem as origens dos scripts a serem injetadas nas páginas correspondentes.

  • correspondências

    string[] opcional

    Especifica em quais páginas esse script de usuário será injetado. Consulte Padrões de correspondência para mais detalhes sobre a sintaxe dessas strings. Essa propriedade precisa ser especificada para ${ref:register}.

  • 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

    O ambiente de execução JavaScript para executar o script. O padrão é `USER_SCRIPT`.

ScriptSource

Propriedades

  • código

    string opcional

    String com o código JavaScript a ser injetado. É preciso especificar exatamente file ou code.

  • arquivo

    string opcional

    O caminho do arquivo JavaScript a ser injetado relativo ao diretório raiz da extensão. É preciso especificar exatamente file ou code.

UserScriptFilter

Propriedades

  • ids

    string[] opcional

    getScripts só retorna scripts com os IDs especificados nessa lista.

WorldProperties

Propriedades

  • CSP

    string opcional

    Especifica o csp mundial. O padrão é o csp mundial `ISOLATED`.

  • mensagens

    booleano opcional

    Especifica se as APIs de mensagens estão expostas. O padrão é false.

Métodos

configureWorld()

Promessa 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Configura o ambiente de execução `USER_SCRIPT`.

Parâmetros

  • properties

    WorldProperties

    Contém a configuração mundial do script do usuário.

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

getScripts()

Promessa 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Retorna todos os scripts de usuário registrados dinamicamente para esta extensão.

Parâmetros

Retorna

  • Promise&lt;RegisteredUserScript[]&gt;

    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.

register()

Promessa 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Registra um ou mais scripts de usuário para esta extensão.

Parâmetros

  • Contém uma lista de scripts de usuário a serem registrados.

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

unregister()

Promessa 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Cancela o registro de todos os scripts de usuário registrados dinamicamente para esta extensão.

Parâmetros

  • filtro

    UserScriptFilter opcional

    Se especificado, esse método cancela o registro apenas dos scripts de usuário que correspondem a ele.

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

update()

Promessa 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Atualiza um ou mais scripts de usuário para esta extensão.

Parâmetros

  • Contém uma lista de scripts de usuário 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.