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 chrome.userScripts, adicione a permissão "userScripts" ao seu manifest.json e "host_permissions" para 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 de usuário é um trecho 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 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á ativou o modo de desenvolvedor na instalação do Chrome. Para extensões de script de usuário, seus usuários também precisam ativar o modo de desenvolvedor. Veja a seguir 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. Por padrão, chrome:// URLs não são vinculáveis.

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

Tanto os scripts de usuário quanto os de conteúdo podem ser executados em um mundo isolado ou no mundo principal. Um mundo isolado é um ambiente de execução inacessível para uma página de host ou outras extensões. Isso permite que um script de usuário altere o ambiente JavaScript sem afetar a página do host ou os scripts de usuário e de conteúdo de outras extensões. Por outro lado, os scripts de usuário (e scripts de conteúdo) não ficam visíveis para a página de hospedagem ou para os scripts de usuário e de conteúdo de outras extensões. Os scripts em execução na interface 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().

Se quiser configurar uma política de segurança de conteúdo para o USER_SCRIPT, chame userScripts.configureWorld():

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

Mensagens

Assim como os scripts de conteúdo e 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 faria. No entanto, eles são recebidos usando manipuladores de eventos dedicados (ou seja, que não usam onMessage ou onConnect) e são chamados 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.

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

Atualizações de extensões

Os scripts do usuário são apagados quando uma extensão é atualizada. Para adicioná-los novamente, execute 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 é um exemplo de userScript do nosso repositório.

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á outras opções além das mostradas aqui.

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

Tipos

ExecutionWorld

O mundo em JavaScript onde um script de usuário será executado.

Tipo enumerado

"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 do usuário e isento da CSP da página.

RegisteredUserScript

Propriedades

• allFrames

  booleano opcional

  Se verdadeiro, ele é injetado em todos os frames, mesmo que não seja o primeiro frame na guia. Cada frame é verificado de forma independente para verificar os requisitos de URL. Ele não será injetado 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 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 um "_", já que está reservada como um prefixo para IDs de script gerados.

• includeGlobs

  string[] opcional

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

• js

  ScriptSource[]

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

• correspondências

  string[] opcional

  Especifica em quais páginas este 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`.

ScriptSource

Propriedades

• código

  string opcional

  String com o código JavaScript a ser injetado. É necessário especificar exatamente um entre file ou code.

• arquivo

  string opcional

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

UserScriptFilter

Propriedades

• ids

  string[] opcional

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

WorldProperties

Propriedades

• CPP

  string opcional

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

• mensagens

  booleano opcional

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

Métodos

configureWorld()

Promessa

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

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

Parâmetros

• properties

  WorldProperties

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

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

getScripts()

Promessa

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

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

Parâmetros

• Função filter

  UserScriptFilter opcional

  Se especificado, esse método retorna apenas os scripts de usuário correspondentes.

• callback

  função optional

  O parâmetro callback tem esta aparência:

  (scripts: RegisteredUserScript[])=>void

  • scripts

    RegisteredUserScript[]

Retorna

• Promise<RegisteredUserScript[]>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

register()

Promessa

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

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

Parâmetros

• scripts

  RegisteredUserScript[]

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

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado 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 esta extensão.

Parâmetros

• Função filter

  UserScriptFilter opcional

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

• callback

  função optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.

update()

Promessa

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

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

Parâmetros

• scripts

  RegisteredUserScript[]

  Contém uma lista de scripts de usuário a serem atualizados. Uma propriedade só é 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 optional

  O parâmetro callback tem esta aparência:

  ()=>void

Retorna

• Promise<void>

  Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.