browser.userScripts

Descrição

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

Permissões

userScripts

Para usar a API User Scripts, browser.userScripts, adicione a permissão "userScripts" ao manifest.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+ browser.* desde o Chrome 148 MV3+

Conceitos e uso

Um script de usuário é um snippet de código injetado em uma página da Web para modificar a aparência ou o comportamento dela. Ao contrário de outros recursos de extensão, como scripts de conteúdo e a API browser.scripting, a API User Scripts permite executar código arbitrário. Essa API é necessária para extensões que executam scripts fornecidos pelo usuário que não podem ser enviados como parte do pacote da extensão.

Ativar o uso da API userScripts

Depois que a extensão receber permissão para usar a API userScripts, os usuários precisarão ativar uma opção específica para permitir que a extensão use a API. A alternância específica necessária e o comportamento da API quando desativada variam de acordo com a versão do Chrome.

Use a verificação a seguir para determinar qual botão o usuário precisa ativar, por exemplo, durante a integração de um novo usuário:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

As seções a seguir descrevem as diferentes opções e como ativá-las.

Versões do Chrome anteriores à 138 (alternância do modo de desenvolvedor)

Como desenvolvedor de extensões, você já tem o modo de desenvolvedor ativado na sua instalação do Chrome. Os usuários também precisam ativar o modo de desenvolvedor.

Você pode copiar e colar as seguintes instruções na documentação da sua extensão para os usuários.

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

  2. Ative o Modo de Desenvolvedor clicando no botão de alternância ao lado de Modo de desenvolvedor.

    A página de extensões do Chrome com o botão de alternância do modo de desenvolvedor em destaque

    Página de extensões (chrome://extensions)

Chrome 138 e versões mais recentes (botão "Permitir scripts do usuário")

O botão de ativação Permitir scripts de usuário está na página de detalhes de cada extensão (por exemplo, chrome://extensions/?id=YOUR_EXTENSION_ID).

Você pode copiar e colar as seguintes instruções na documentação da sua extensão para os usuários:

  1. Acesse a página "Extensões" digitando chrome://extensions em uma nova guia. Por padrão, os URLs de chrome:// não podem ser vinculados.
  2. Clique no botão "Detalhes" no card da extensão para ver informações detalhadas sobre ela.
  3. Clique no botão ao lado de Permitir scripts do usuário.
O botão "Permitir scripts de usuário" na página de detalhes da extensão
Botão de ativação "Permitir scripts de usuário" (chrome://extensions/?id=abc...)

Verificar a disponibilidade da API

Recomendamos a verificação a seguir para determinar se a API userScripts está ativada, já que ela funciona em todas as versões do Chrome. Essa verificação tenta chamar um método browser.userScripts() que sempre deve ser bem-sucedido quando a API está disponível. Se essa chamada gerar um erro, a API não estará disponível:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Trabalhar 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 host ou outras extensões. Isso permite que um script de usuário mude o ambiente JavaScript sem afetar a página host ou os scripts de usuário e de conteúdo de outras extensões. Por outro lado, os scripts de usuário (e de conteúdo) não são visíveis para a página host ou para os scripts de usuário e de conteúdo de outras extensões. Os scripts em execução no mundo principal podem ser acessados e visualizados por páginas de host e 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():

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

Mensagens

Assim como os scripts de conteúdo e os documentos fora da tela, os scripts do usuário se comunicam com outras partes de uma extensão usando mensagens (ou seja, 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, não usam onMessage ou onConnect). Esses manipuladores são chamados de runtime.onUserScriptMessage e runtime.onUserScriptConnect. Os gerenciadores 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.

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

Atualizações de extensões

Os scripts de usuário são apagados quando uma extensão é atualizada. Para adicioná-los de volta, execute o código no manipulador de eventos runtime.onInstalled no service worker da extensão. Responda apenas ao motivo "update" transmitido ao callback do evento.

Exemplo

Este exemplo é do exemplo 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 define os scripts a serem registrados. Há mais opções do que as mostradas aqui.

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

Tipos

ExecutionWorld

O mundo do JavaScript em que um script de usuário é executado.

Enumeração

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

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

InjectionResult

Chrome 135+ browser.* desde o Chrome 148

Propriedades

  • documentId

    string

    O documento associado à injeção.

  • erro

    string opcional

    O erro, se houver. error e result são mutuamente exclusivos.

  • frameId

    número

    O frame associado à injeção.

  • resultado

    any optional

    O resultado da execução do script.

InjectionTarget

Chrome 135+ browser.* desde o Chrome 148

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

    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.

RegisteredUserScript

Propriedades

  • allFrames

    booleano opcional

    Se for 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.

  • excludeGlobs

    string[] opcional

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

  • excludeMatches

    string[] opcional

    Exclui as páginas em que esse script de usuário seria injetado. 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 de API. Essa propriedade não pode começar com "_", porque esse caractere é reservado como prefixo para IDs de script gerados.

  • includeGlobs

    string[] opcional

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

  • js

    ScriptSource[] opcional

    A lista de objetos ScriptSource que definem as origens dos scripts a serem injetados nas páginas correspondentes. Essa propriedade precisa ser especificada para ${ref:register} e, quando especificada, precisa ser uma matriz não vazia.

  • 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 do JavaScript em que o script será executado. O padrão é `USER_SCRIPT`.

  • worldId

    string opcional

    Chrome 133+ browser.* desde o Chrome 148

    Especifica o ID do mundo do script do usuário em que ele será executado. Se omitido, o script será executado no mundo de script de usuário padrão. Válido apenas se world for omitido ou for USER_SCRIPT. Os valores com sublinhados iniciais (_) são reservados.

ScriptSource

Propriedades

  • código

    string opcional

    Uma string que contém o código JavaScript a ser injetado. É preciso especificar exatamente um file ou code.

  • arquivo

    string opcional

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

UserScriptFilter

Propriedades

  • ids

    string[] opcional

    getScripts retorna apenas scripts com os IDs especificados nessa lista.

UserScriptInjection

Chrome 135+ browser.* desde o Chrome 148

Propriedades

  • injectImmediately

    booleano opcional

    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.

  • A lista de objetos ScriptSource que definem as origens dos scripts a serem injetados no destino.

  • destino

    InjectionTarget

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

  • mundo

    ExecutionWorld opcional

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

  • worldId

    string opcional

    Especifica o ID do mundo do script do usuário em que ele será executado. Se omitido, o script será executado no mundo de script de usuário padrão. Válido apenas se world for omitido ou for USER_SCRIPT. Os valores com sublinhados iniciais (_) são reservados.

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.

  • worldId

    string opcional

    Chrome 133+ browser.* desde o Chrome 148

    Especifica o ID do mundo de script de usuário específico a ser atualizado. Se não for fornecido, atualiza as propriedades do mundo padrão do script do usuário. Os valores com sublinhados iniciais (_) são reservados.

Métodos

configureWorld()

browser.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

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

Parâmetros

  • propriedades

    WorldProperties

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

Retorna

  • Promessa<void>

    Promessa que é resolvida quando o mundo é configurado.

execute()

Chrome 135+ browser.* desde o Chrome 148 
browser.userScripts.execute(
  injection: UserScriptInjection,
): 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

getScripts()

browser.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

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

Parâmetros

  • filtro

    UserScriptFilter opcional

    Se especificado, esse método retorna apenas os scripts de usuário que correspondem a ele.

Retorna

  • Promessa que é resolvida com os scripts registrados. A promessa será rejeitada se ocorrer um erro.

getWorldConfigurations()

Chrome 133+ browser.* desde o Chrome 148 
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Recupera todas as configurações de mundo registradas.

Retorna

  • Promise<WorldProperties[]>

    Promessa que é resolvida com as configurações de mundo registradas.

register()

browser.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

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

Parâmetros

Retorna

  • Promessa<void>

    Promessa que é resolvida quando os scripts são totalmente registrados. A promessa será rejeitada se ocorrer um erro.

resetWorldConfiguration()

Chrome 133+ browser.* desde o Chrome 148 
browser.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

Redefine a configuração de um ambiente de script do usuário. Todos os scripts que forem injetados no mundo com o ID especificado vão usar a configuração padrão do mundo.

Parâmetros

  • worldId

    string opcional

    O ID do mundo do script do usuário que será redefinido. Se omitido, redefine a configuração do mundo padrão.

Retorna

  • Promessa<void>

    Promessa que é resolvida quando a configuração é redefinida.

unregister()

browser.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

Cancela o registro de todos os scripts de usuário registrados dinamicamente para essa 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.

Retorna

  • Promessa<void>

    Promessa que é resolvida quando os scripts são totalmente cancelados. A promessa será rejeitada se ocorrer um erro.

update()

browser.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

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

    Promessa que é resolvida quando os scripts são totalmente atualizados. A promessa será rejeitada se ocorrer um erro.