chrome.userScripts

Descrição

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

Permissões

userScripts

Para usar a API User Scripts, chrome.userScripts, adicione a permissão "userScripts" ao arquivo 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+ MV3+

Conceitos e uso

Um script do 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 os scripts de conteúdo e a API chrome.scripting, a API User Scripts permite executar códigos arbitrários. Essa API é necessária para extensões que executam scripts fornecidos pelo usuário que não podem ser enviados como parte do pacote de extensão.

Ativar o uso da API userScripts

Depois que a extensão receber a permissão para usar a API userScripts, os usuários precisarão ativar uma chave específica para permitir que a extensão use a API. A chave 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 novos usuários:

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 os diferentes botões e como ativá-los.

Versões do Chrome anteriores à 138 (interruptor do modo de desenvolvedor)

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

Você pode copiar e colar as instruções a seguir na documentação da extensão para seus usuários.

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

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

    Página "Extensions" do Chrome com o botão do modo de desenvolvedor destacado

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

Chrome 138 e versões mais recentes (chave de ativação "Permitir scripts do usuário")

O botão de ativação Permitir scripts do 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 instruções a seguir na documentação da extensão para os usuários:

  1. Acesse a página "Extensões" digitando chrome://extensions em uma nova guia. Os URLs chrome:// não podem ser vinculados.
  2. Clique no botão "Detalhes" no card da extensão para conferir 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
Permitir a ativação de scripts de usuário (chrome://extensions/?id=abc...)

Verificar a disponibilidade da API

Recomendamos a verificação abaixo 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 chrome.userScripts() que sempre terá sucesso quando a API estiver 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.
    chrome.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 é acessível a uma página de destino ou outras extensões. Isso permite que um script do usuário mude o ambiente do JavaScript sem afetar a página de destino ou outros scripts de conteúdo e de usuário das extensões. Por outro lado, os scripts do usuário (e de conteúdo) não são visíveis para a página de host ou para os scripts do usuário e de conteúdo de outras extensões. Os scripts executados no mundo principal são acessíveis e ficam visíveis para as páginas de destino 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():

chrome.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 processadores dedicados facilitam a identificação de mensagens de scripts do 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ões

Os scripts do usuário são limpos quando uma extensão é atualizada. Para adicionar de volta, execute o código no gerenciador de eventos runtime.onInstalled no worker de serviço da extensão. Responda apenas ao motivo "update" transmitido para o callback de 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.

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

Tipos

ExecutionWorld

O mundo do JavaScript para um script do usuário ser 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 host.

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

InjectionResult

Chrome 135 e versões mais recentes

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

    qualquer opcional

    O resultado da execução do script.

InjectionTarget

Chrome 135 e versões mais recentes

Propriedades

  • allFrames

    booleano opcional

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

  • documentIds

    string[] opcional

    Os IDs de documentIds específicos para injetar. Não precisa ser definido se frameIds estiver definido.

  • frameIds

    number[] opcional

    Os IDs dos frames específicos para injetar.

  • tabId

    número

    O ID da guia em que será injetado.

RegisteredUserScript

Propriedades

  • allFrames

    booleano opcional

    Se for verdadeiro, ele será injetado em todos os frames, mesmo que não seja o principal na guia. Cada frame é verificado de forma independente para 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 é correspondente.

  • excludeGlobs

    string[] opcional

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

  • excludeMatches

    string[] opcional

    Exclui 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 do usuário especificado na chamada de API. Essa propriedade não pode começar com "_", porque ele é reservado como um prefixo para IDs de script gerados.

  • includeGlobs

    string[] opcional

    Especifica padrões de curinga para as páginas em que esse script do 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 do 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 e versões mais recentes

    Especifica o ID do mundo do script do usuário em que será executado. Se omitido, o script será executado no mundo padrão do script do usuário. 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 entre 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 entre file ou code.

UserScriptFilter

Propriedades

  • ids

    string[] opcional

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

UserScriptInjection

Chrome 135 e versões mais recentes

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 ocorra antes do carregamento da página, porque ela pode já ter sido carregada quando o script atinge o destino.

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

  • 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 será executado. Se omitido, o script será executado no mundo padrão do script do usuário. 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 do mundo. O padrão é o csp `ISOLATED` do mundo.

  • mensagens

    booleano opcional

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

  • worldId

    string opcional

    Chrome 133 e versões mais recentes

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

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 do mundo do script do usuário.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

execute()

Promessa Chrome 135+ 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  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 espera, mesmo que a página não tenha terminado de carregar. Se o script for avaliado como uma promessa, o navegador vai aguardar a promessa ser resolvida e retornar o valor resultante.

Parâmetros

Retorna

  • Promise<InjectionResult[]>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getScripts()

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

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

Parâmetros

Retorna

  • As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getWorldConfigurations()

Promessa Chrome 133+ 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Recupera todas as configurações de mundo registradas.

Parâmetros

Retorna

  • Promise<WorldProperties[]>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

register()

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

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

Parâmetros

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

resetWorldConfiguration()

Promessa Chrome 133+ 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Redefine a configuração de um mundo de script do usuário. Todos os scripts 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 a ser redefinido. Se omitido, redefine a configuração do mundo padrão.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

unregister()

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

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

Parâmetros

  • filtrar

    UserScriptFilter opcional

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

update()

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

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

Parâmetros

  • Contém uma lista de scripts do usuário a serem atualizados. Uma propriedade só será atualizada para o script atual se for especificada nesse objeto. Se houver erros durante a análise de script/validação de 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 este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.