chrome.userScripts

Descrição

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

Permissões

userScripts

Para usar a API chrome.userScripts, adicione a permissão "userScripts" ao arquivo manifest.json e "host_permissions" aos 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 trecho de código injetado em uma página da Web para modificar a aparência ou o comportamento dela. Os scripts são criados pelos usuários ou transferidos por download de um repositório de scripts ou de uma extensão de script do usuário.

Modo de desenvolvedor para usuários de extensões

Como desenvolvedor de extensões, você já tem o modo de desenvolvedor ativado na sua instalação do Chrome. Para extensões de script do usuário, os usuários também precisam ativar o modo de desenvolvedor. Confira as instruções que você pode copiar e colar na sua própria documentação.

  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 "Extensões"

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

É possível determinar se o modo de desenvolvedor está ativado verificando se 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;
  }
}

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 gerenciadores de eventos dedicados, ou seja, eles não usam onMessage ou onConnect. Esses gerenciadores 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 userScript no 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.

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

    Pendente

    Se especificado, especifica um ID de mundo do script do usuário específico para execução. Válido apenas se world for omitido ou for USER_SCRIPT. Se omitido, o script será executado no mundo padrão do script do usuário. 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.

WorldProperties

Propriedades

  • csp

    string opcional

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

  • mensagens

    booleano opcional

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

  • worldId

    string opcional

    Pendente

    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.

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

  • filtro

    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.