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
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.
- Acesse a página "Extensões" digitando
chrome://extensions
em uma nova guia. Por padrão,chrome://
URLs não são vinculáveis. Ative o modo de desenvolvedor clicando no botão ao lado de Modo de desenvolvedor.
É 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
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
oucode
. -
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
oucode
.
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()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Configura o ambiente de execução do `USER_SCRIPT`
.
Parâmetros
-
properties
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()
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
-
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()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Registra um ou mais scripts de usuário para esta extensão.
Parâmetros
-
scripts
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()
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()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Atualiza um ou mais scripts de usuário para esta extensão.
Parâmetros
-
scripts
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.