Descrição
Use a API chrome.devtools.inspectedWindow
para interagir com a janela inspecionada: consiga o ID da guia da página inspecionada, avalie o código no contexto da janela inspecionada, recarregue a página ou acesse a lista de recursos dentro da página.
Manifesto
Use chrome.devtools.inspectedWindow
para interagir com a janela inspecionada: consiga o ID da guia da
página inspecionada, avalie o código no contexto da janela inspecionada, recarregue a página ou veja
a lista de recursos dentro da página.
Consulte o Resumo das APIs do DevTools para uma introdução geral ao uso das APIs das Ferramentas para desenvolvedores.
Visão geral
A propriedade tabId
fornece o identificador de guias que pode ser usado com as chamadas de API
chrome.tabs.*
. No entanto, a API chrome.tabs.*
não é exposta às páginas de extensão
das Ferramentas para desenvolvedores devido a considerações de segurança. Será necessário transmitir o ID da guia para a página em
segundo plano e invocar as funções da API chrome.tabs.*
nela.
O método reload
pode ser usado para atualizar a página inspecionada. Além disso, o autor da chamada pode especificar
uma substituição para a string do user agent, um script que será injetado no início do carregamento da página ou uma
opção para forçar a atualização de recursos armazenados em cache.
Use a chamada getResources
e o evento onResourceContent
para receber a lista de recursos (documentos, folhas de estilo, scripts, imagens etc.) na página inspecionada. Os métodos getContent
e
setContent
da classe Resource
com o evento onResourceContentCommitted
podem
ser usados para oferecer suporte à modificação do conteúdo do recurso, por exemplo, por um editor externo.
Como executar código na janela inspecionada
O método eval
permite que as extensões executem o código JavaScript no contexto da
página inspecionada. Esse método é eficiente quando usado no contexto certo e perigoso quando usado incorretamente. Use o método tabs.executeScript
, a menos que você precise da funcionalidade específica
fornecida pelo método eval
.
Estas são as principais diferenças entre os métodos eval
e tabs.executeScript
:
- O método
eval
não usa um mundo isolado para o código que está sendo avaliado, de modo que o estado JavaScript da janela inspecionada possa ser acessado pelo código. Use esse método quando for necessário acessar o estado JavaScript da página inspecionada. - O contexto de execução do código que está sendo avaliado inclui a API Developer Tools Console.
Por exemplo, o código pode usar
inspect
e$0
. - O código avaliado pode retornar um valor que é transmitido para o callback da extensão. O valor retornado precisa ser um objeto JSON válido, ou seja, pode conter apenas tipos JavaScript primitivos e referências acíclicas a outros objetos JSON. Preste atenção ao processar os dados recebidos da página inspecionada: o contexto de execução é essencialmente controlado pela página inspecionada. Uma página maliciosa pode afetar os dados retornados à extensão.
Uma página pode incluir vários contextos de execução JavaScript diferentes. Cada frame tem o próprio contexto, além de um contexto extra para cada extensão que tem scripts de conteúdo em execução nele.
Por padrão, o método eval
é executado no contexto do frame principal da página inspecionada.
O método eval
usa um segundo argumento opcional que pode ser usado para especificar o contexto em que
o código é avaliado. Esse objeto options pode conter uma ou mais das seguintes chaves:
frameURL
- Use para especificar um frame diferente do frame principal da página inspecionada.
contextSecurityOrigin
- Use para selecionar um contexto dentro do frame especificado de acordo com a origem da Web.
useContentScriptContext
- Se verdadeiro, execute o script no mesmo contexto que os scripts de conteúdo das extensões. Equivalente a especificar a própria origem da Web das extensões como a origem de segurança de contexto. Isso pode ser usado para trocar dados com o script de conteúdo.
Exemplos
O código a seguir verifica a versão do jQuery usada pela página inspecionada:
chrome.devtools.inspectedWindow.eval(
"jQuery.fn.jquery",
function(result, isException) {
if (isException) {
console.log("the page is not using jQuery");
} else {
console.log("The page is using jQuery v" + result);
}
}
);
Para testar essa API, instale os exemplos da API DevTools no repositório chrome-extension-samples.
Tipos
Resource
Um recurso na página inspecionada, como um documento, um script ou uma imagem.
Propriedades
-
url
string
O URL do recurso.
-
getContent
void
Extrai o conteúdo do recurso.
A função
getContent
tem esta aparência:(callback: function) => {...}
-
callback
função
O parâmetro
callback
tem esta aparência:(content: string, encoding: string) => void
-
conteúdo
string
Conteúdo do recurso (possivelmente codificado).
-
Codificação
string
Vai ser vazio se o conteúdo não estiver codificado. Caso contrário, codifica o nome. Atualmente, apenas a codificação de base64 é suportada.
-
-
-
setContent
void
Define o conteúdo do recurso.
A função
setContent
tem esta aparência:(content: string, commit: boolean, callback?: function) => {...}
-
conteúdo
string
Novo conteúdo do recurso. No momento, apenas recursos com o tipo texto são compatíveis.
-
commit
boolean
"True", se o usuário terminou de editar o recurso e o novo conteúdo precisa ser mantido; "false", se é uma alteração pequena enviada pelo usuário em andamento.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(error?: object) => void
-
error
objeto opcional
Definido como indefinido se o conteúdo do recurso tiver sido definido. Caso contrário, descreve o erro.
-
-
Propriedades
tabId
O ID da guia que está sendo inspecionada. Esse ID pode ser usado com chrome.tabs.* API.
Tipo
number
Métodos
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
Avalia uma expressão JavaScript no contexto do frame principal da página inspecionada. A expressão precisa ser avaliada como um objeto compatível com JSON. Caso contrário, uma exceção será gerada. A função de avaliação pode informar um erro do lado do DevTools ou uma exceção do JavaScript que ocorre durante a avaliação. Em ambos os casos, o parâmetro result
do callback é undefined
. No caso de um erro no lado do DevTools, o parâmetro isException
não é nulo e tem isError
definido como verdadeiro e code
definido como um código de erro. No caso de um erro de JavaScript, isException
é definido como verdadeiro e value
é definido como o valor da string do objeto gerado.
Parâmetros
-
expressão
string
Uma expressão a ser avaliada.
-
opções
objeto opcional
O parâmetro "options" pode conter uma ou mais opções.
-
frameURL
string opcional
Se especificada, a expressão é avaliada no iframe cujo URL corresponde ao especificado. Por padrão, a expressão é avaliada no frame superior da página inspecionada.
-
scriptExecutionContext
string opcional
Chrome 107 ou mais recenteAvalie a expressão no contexto de um script de conteúdo de uma extensão que corresponda à origem especificada. Se fornecido, scriptExecutionContext vai substituir a configuração "true" em useContentScriptContext.
-
useContentScriptContext
booleano opcional
Avalie a expressão no contexto do script de conteúdo da extensão de chamada, desde que o script de conteúdo já esteja injetado na página inspecionada. Caso contrário, a expressão não será avaliada, e o callback será invocado com o parâmetro de exceção definido como um objeto que tenha o campo
isError
definido como verdadeiro e o campocode
definido comoE_NOTFOUND
.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: object, exceptionInfo: object) => void
-
resultado
objeto
O resultado da avaliação.
-
exceptionInfo
objeto
Um objeto que fornece detalhes se uma exceção ocorreu durante a avaliação da expressão.
-
código
string
Defina se o erro ocorreu no lado do DevTools antes da avaliação da expressão.
-
descrição
string
Defina se o erro ocorreu no lado do DevTools antes da avaliação da expressão.
-
detalhes
qualquer um[]
Defina se o erro ocorreu no lado do DevTools antes da avaliação da expressão. Contém a matriz dos valores que podem ser substituídos na string de descrição para fornecer mais informações sobre a causa do erro.
-
isError
boolean
Defina se o erro ocorreu no lado do DevTools antes da avaliação da expressão.
-
isException
boolean
Defina se o código avaliado produz uma exceção não processada.
-
valor
string
Defina se o código avaliado produz uma exceção não processada.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
Recupera a lista de recursos da página inspecionada.
Parâmetros
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
Recarrega a página inspecionada.
Parâmetros
-
reloadOptions
objeto opcional
-
ignoreCache
booleano opcional
Quando definido como verdadeiro, o carregador ignora o cache de todos os recursos da página inspecionada carregados antes do disparo do evento
load
. O efeito é semelhante a pressionar Ctrl+Shift+R na janela inspecionada ou dentro da janela Ferramentas para desenvolvedores. -
injectedScript
string opcional
Se especificado, o script será injetado em cada frame da página inspecionada imediatamente após o carregamento, antes de qualquer um dos scripts do frame. O script não será injetado após recarregamentos subsequentes, por exemplo, se o usuário pressionar Ctrl+R.
-
userAgent
string opcional
Se especificada, a string vai substituir o valor do cabeçalho HTTP
User-Agent
, que é enviado ao carregar os recursos da página inspecionada. A string também vai substituir o valor da propriedadenavigator.userAgent
retornada para qualquer script em execução na página inspecionada.
-
Eventos
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
Disparado quando um novo recurso é adicionado à página inspecionada.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(resource: Resource) => void
-
recurso
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
Disparado quando uma nova revisão do recurso é confirmada (por exemplo, o usuário salva uma versão editada do recurso nas Ferramentas para desenvolvedores).