Descrição
Use a API chrome.scripting
para executar o script em contextos diferentes.
Permissões
scripting
Disponibilidade
Manifesto
Para usar a API chrome.scripting
, declare a permissão "scripting"
no manifesto, além das permissões de host para as páginas injetarem scripts. Use a chave "host_permissions"
ou a permissão "activeTab"
, que concede permissões temporárias de host. O exemplo a seguir usa a permissão activeTab.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
Conceitos e uso
Você pode usar a API chrome.scripting
para injetar JavaScript e CSS nos
sites. Isso é parecido com o que é possível fazer com scripts
de conteúdo. No entanto, ao usar o namespace chrome.scripting
, as extensões
podem tomar decisões no momento da execução.
Destinos de injeção
Use o parâmetro target
para especificar um destino para injetar JavaScript ou
CSS.
O único campo obrigatório é tabId
. Por padrão, uma injeção será executada no
frame principal da guia especificada.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
Para execução em todos os frames da guia especificada, defina o booleano allFrames
como true
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
Também é possível injetar em frames específicos de uma guia especificando IDs de frame
individuais. Para mais informações sobre IDs de frames, consulte a
API chrome.webNavigation
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
Código injetado
As extensões podem especificar o código a ser injetado por um arquivo externo ou uma variável de ambiente de execução.
Arquivos
Os arquivos são especificados como strings que são caminhos relativos ao diretório raiz da
extensão. O código a seguir injetará o arquivo script.js
no frame principal da guia.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
Funções do ambiente de execução
Ao injetar JavaScript com scripting.executeScript()
, você pode especificar uma
função a ser executada em vez de um arquivo. Essa função precisa ser uma variável
disponível para o contexto da extensão atual.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
Contorne isso usando a propriedade args
:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
Strings do ambiente de execução
Ao injetar CSS em uma página, você também pode especificar uma string a ser usada na propriedade css
. Essa opção está disponível apenas para scripting.insertCSS()
. Não
é possível executar uma string usando scripting.executeScript()
.
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
Processar os resultados
Os resultados da execução de JavaScript são transmitidos para a extensão. Um único resultado é incluído por frame. O frame principal é o primeiro índice na matriz resultante. Todos os outros frames estão em uma ordem não determinista.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
scripting.insertCSS()
não retorna resultados.
Promessas
Se o valor resultante da execução do script for uma promessa, o Chrome aguardará a liquidação da promessa e retornará o valor resultante.
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
Exemplos
Cancelar o registro de todos os scripts de conteúdo dinâmico
O snippet a seguir contém uma função que cancela o registro de todos os scripts de conteúdo dinâmico registrados anteriormente pela extensão.
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
Para testar a API chrome.scripting
, instale a amostra de script do repositório de exemplos de extensão do Chrome (links em inglês).
Tipos
ContentScriptFilter
Propriedades
-
ids
string[] opcional
Se especificado,
getRegisteredContentScripts
só retornará scripts com um ID especificado nesta lista.
CSSInjection
Propriedades
-
css
string opcional
String com o CSS a ser injetado. É necessário especificar exatamente um entre
files
oucss
. -
arquivos
string[] opcional
O caminho dos arquivos CSS a serem injetados, relativo ao diretório raiz da extensão. É necessário especificar exatamente um entre
files
oucss
. -
origem
StyleOrigin opcional
A origem do estilo da injeção. O valor padrão é
'AUTHOR'
. -
destino
Detalhes que especificam o destino em que o CSS deve ser inserido.
ExecutionWorld
O mundo em JavaScript onde um script será executado.
Tipo enumerado
"ISOLATED"
Especifica o mundo isolado, que é o ambiente de execução exclusivo da extensão.
"MAIN"
Especifica o mundo principal do DOM, que é o ambiente de execução compartilhado com o JavaScript da página host.
InjectionResult
Propriedades
-
documentId
string
Chrome 106 ou mais recenteO documento associado à injeção.
-
frameId
number
Chrome 90 ou mais recenteO frame associado à injeção.
-
resultado
Qualquer opção opcional
O resultado da execução do script.
InjectionTarget
Propriedades
-
allFrames
booleano opcional
Indica se o script precisa injetar em todos os frames na guia. O padrão é "false". Isso não poderá ser verdadeiro se
frameIds
for especificado. -
documentIds
string[] opcional
Chrome 106 ou mais recenteOs IDs de documentIds específicos a serem injetados. Isso não poderá ser definido se
frameIds
estiver definido. -
frameIds
number[] opcional
São os IDs de frames específicos a serem injetados.
-
tabId
number
O ID da guia em que injetar.
RegisteredContentScript
Propriedades
-
allFrames
booleano opcional
Se especificado como "true", ele será injetado em todos os frames, mesmo que o frame não seja o mais acima 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.
-
css
string[] opcional
A lista de arquivos CSS a serem injetados nas páginas correspondentes. Eles são injetados na ordem em que aparecem nessa matriz, antes que qualquer DOM seja construído ou exibido para a página.
-
excludeMatches
string[] opcional
Exclui páginas em que esse script de conteúdo seria injetado. Consulte Padrões de correspondência para mais detalhes sobre a sintaxe dessas strings.
-
id
string
O ID do script de conteúdo, especificado na chamada de API. Não pode começar com "_", já que ele está reservado como prefixo para IDs de script gerados.
-
js
string[] opcional
A lista de arquivos JavaScript a serem injetados nas páginas correspondentes. Eles são injetados na ordem em que aparecem nesta matriz.
-
matchOriginAsFallback
booleano opcional
Chrome 119 ou mais recenteIndica se o script pode ser injetado em frames em que o URL contém um esquema não compatível. Especificamente: sobre:, dados:, blob: ou sistema de arquivos:. Nesses casos, a origem do URL é verificada para determinar se o script precisa ser injetado. Se a origem for
null
(como é o caso de "data: URLs"), a origem usada será o frame que criou o frame atual ou o que iniciou a navegação até esse frame. Esse pode não ser o frame pai. -
correspondências
string[] opcional
Especifica em quais páginas este script de conteúdo será injetado. Consulte Padrões de correspondência para mais detalhes sobre a sintaxe dessas strings. Precisa ser especificado para
registerContentScripts
. -
persistAcrossSessions
booleano opcional
Especifica se este script de conteúdo persistirá em sessões futuras. O padrão é "true".
-
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
Chrome 102 ou mais recenteO "mundo" JavaScript no qual executar o script. O valor padrão é
ISOLATED
.
ScriptInjection
Propriedades
-
args
qualquer[] opcional
Chrome 92 ou mais recenteOs argumentos a serem transmitidos para a função fornecida. Isso só será válido se o parâmetro
func
for especificado. Esses argumentos precisam ser serializáveis por JSON. -
arquivos
string[] opcional
O caminho dos arquivos JS ou CSS a serem injetados, relativo ao diretório raiz da extensão. É necessário especificar exatamente um entre
files
oufunc
. -
injectImmediately
booleano opcional
Chrome 102 ou mais recenteDefine se a injeção precisa ser acionada no destino o mais rápido possível. Isso não garante que a injeção ocorrerá antes do carregamento da página, já que ela pode já ter sido carregada no momento em que o script atingir o destino.
-
destino
Detalhes que especificam o destino em que o script será injetado.
-
mundo
ExecutionWorld opcional
Chrome 95 ou mais recenteO "mundo" JavaScript no qual executar o script. O valor padrão é
ISOLATED
. -
func
void optional
Chrome 92 ou mais recenteUma função JavaScript a ser injetada. Essa função será serializada e desserializada para injeção. Isso significa que todos os parâmetros vinculados e contextos de execução serão perdidos. É necessário especificar exatamente um entre
files
oufunc
.A função
func
tem esta aparência:() => {...}
StyleOrigin
Origem de uma alteração de estilo. Confira as origens de estilo para mais informações.
Tipo enumerado
Métodos
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
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
for definida, o script vai injetar sem aguardar, mesmo que a página não tenha concluído o carregamento. Se o script for avaliado como uma promessa, o navegador aguardará a liquidação da promessa e retornará o valor resultante.
Parâmetros
-
Injeção
Detalhes do script que será injetado.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(results: InjectionResult[]) => void
-
resultados
-
Retorna
-
Promise<InjectionResult[]>
Chrome 90 ou mais recentePromessas 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.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Retorna todos os scripts de conteúdo registrados dinamicamente para esta extensão que correspondem ao filtro especificado.
Parâmetros
-
Função filter
ContentScriptFilter opcional
Um objeto para filtrar os scripts registrados dinamicamente da extensão.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(scripts: RegisteredContentScript[]) => void
-
scripts
-
Retorna
-
Promise<RegisteredContentScript[]>
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.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
Insere uma folha de estilo CSS em um contexto de destino. Se vários frames forem especificados, as injeções malsucedidas serão ignoradas.
Parâmetros
-
Injeção
Detalhes dos estilos a serem inseridos.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 90 ou mais recentePromessas 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.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Registra um ou mais scripts de conteúdo para esta extensão.
Parâmetros
-
scripts
Contém uma lista de scripts a serem registrados. Se houver erros durante a análise de script/validação de arquivo, ou se os IDs especificados já existirem, nenhum script será registrado.
-
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.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
Remove uma folha de estilo CSS inserida anteriormente por essa extensão de um contexto de destino.
Parâmetros
-
Injeção
Detalhes dos estilos a serem removidos. Observe que as propriedades
css
,files
eorigin
precisam corresponder exatamente à folha de estilo inserida porinsertCSS
. A tentativa de remover uma folha de estilo inexistente é um ambiente autônomo. -
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.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Cancela o registro dos scripts de conteúdo para esta extensão.
Parâmetros
-
Função filter
ContentScriptFilter opcional
Se especificado, somente cancela o registro de scripts de conteúdo dinâmico que correspondem ao filtro. Caso contrário, o registro de todos os scripts de conteúdo dinâmico da extensão será cancelado.
-
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.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Atualiza um ou mais scripts de conteúdo para esta extensão.
Parâmetros
-
scripts
Contém uma lista de scripts 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.