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

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 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 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 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 padrão e preferencial é 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.

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.

getScripts()

Promessa

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

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

Parâmetros

• filtro

  UserScriptFilter opcional

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

• callback

  função opcional

  O parâmetro callback tem este formato:

  (scripts: RegisteredUserScript[]) => void

  • scripts

    RegisteredUserScript[]

Retorna

• Promise<RegisteredUserScript[]>

  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

• callback

  função opcional

  O parâmetro callback tem este formato:

  (worlds: WorldProperties[]) => void

  • mundos

    WorldProperties[]

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

• scripts

  RegisteredUserScript[]

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

Desregistra 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

• scripts

  RegisteredUserScript[]

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