Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

chrome.devtools.inspectedWindow

Descrição

Use a API chrome.devtools.inspectedWindow para interagir com a janela inspecionada: obtenha o ID da guia da página inspecionada, avalie o código no contexto da janela inspecionada, recarregue a página ou obtenha a lista de recursos na página.

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para usar essa API.

"devtools_page"

Use chrome.devtools.inspectedWindow para interagir com a janela inspecionada: obtenha o ID da guia da página inspecionada, avalie o código no contexto da janela inspecionada, recarregue a página ou obtenha a lista de recursos na página.

Consulte o resumo das APIs do DevTools para uma introdução geral ao uso das APIs das ferramentas de desenvolvimento.

Visão geral

A propriedade tabId fornece o identificador da guia que pode ser usado com as chamadas de API chrome.tabs.*. No entanto, observe que a API chrome.tabs.* não é exposta às páginas de extensão das Ferramentas para desenvolvedores por motivos de segurança. Você precisará transmitir o ID da guia para a página em segundo plano e invocar as funções da API chrome.tabs.* de lá.

O método reload pode ser usado para recarregar a página inspecionada. Além disso, o caller pode especificar uma substituição para a string de user agent, um script que será injetado no início do carregamento de página ou uma opção para forçar o recarregamento de recursos 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, junto com o evento onResourceContentCommitted, podem ser usados para oferecer suporte à modificação do conteúdo do recurso, por exemplo, por um editor externo.

Executar código na janela inspecionada

O método eval permite que as extensões executem código JavaScript no contexto da página inspecionada. Esse método é eficiente quando usado no contexto certo e perigoso quando usado de forma inadequada. 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. Portanto, o estado do JavaScript da janela inspecionada fica acessível ao 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 do console das Ferramentas para desenvolvedores. 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 (pode conter apenas tipos primitivos de JavaScript e referências acíclicas a outros objetos JSON). Tenha muito cuidado ao processar os dados recebidos da página inspecionada. O contexto de execução é controlado essencialmente 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 adicional para cada extensão que tem scripts de conteúdo em execução nesse frame.

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 principal da página inspecionada.
contextSecurityOrigin: Use para selecionar um contexto no frame especificado de acordo com a origem da Web.
useContentScriptContext: Se for verdadeiro, execute o script no mesmo contexto dos 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 do 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 (link em inglês).

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

Promessa

Recebe o conteúdo do recurso.

A função getContent tem esta aparência:
```
(callback?: function) => {...}
```
- callback
  
  função opcional
  
  O parâmetro callback tem esta aparência:
```
(response: object) => void
```
  - resposta
    
    objeto
    
    Pendente
    
    Um objeto que contém o conteúdo do recurso e a codificação dele.
    
    conteúdo
    
    string
    
    Conteúdo do recurso (possivelmente codificado).
    
    encoding
    
    string
    
    Vazio se o conteúdo não estiver codificado. Caso contrário, o nome da codificação. Atualmente, apenas a codificação de base64 é suportada.
- retorna
  Promise<object>
  
  Pendente
  
  Uma função que recebe o conteúdo do recurso quando a solicitação é concluída.
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setContent

void

Promessa

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 de texto são aceitos.
- commit
  
  booleano
  
  Verdadeiro se o usuário tiver terminado de editar o recurso e o novo conteúdo dele precisar ser mantido. Falso se for uma mudança pequena enviada durante a edição do recurso pelo usuário.
- callback
  
  função opcional
  
  O parâmetro callback tem esta aparência:
```
(error?: object) => void
```
  - erro
    
    objeto opcional
    
    Definido como "undefined" se o conteúdo do recurso foi definido com sucesso. Caso contrário, descreve o erro.
- retorna
  Promise<object>
  
  Pendente
  
  Uma função chamada após a conclusão da solicitação.
  
  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Propriedades

tabId

O ID da guia que está sendo inspecionada. Esse ID pode ser usado com chrome.tabs.* Secret Manager.

Tipo

número

Métodos

eval()

Promessa

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): Promise<object>

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 "eval" 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 do lado do DevTools, o parâmetro isException não é nulo e tem isError definido como "true" e code definido como um código de erro. No caso de um erro de JavaScript, isException é definido como "true" e value é definido como o valor de 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 será avaliada no iframe cujo URL corresponda ao especificado. Por padrão, a expressão é avaliada no frame superior da página inspecionada.
- scriptExecutionContext
  
  string opcional
  
  Chrome 107 ou mais recente
  
  Avalia a expressão no contexto de um script de conteúdo de uma extensão que corresponde à origem especificada. Se fornecido, scriptExecutionContext vai substituir a configuração "true" em useContentScriptContext.
- useContentScriptContext
  
  booleano opcional
  
  Avalia 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 tem o campo isError definido como "true" e o campo code definido como E_NOTFOUND.
callback

função opcional

O parâmetro callback tem esta aparência:
```
(response: object) => void
```
- resposta
  
  objeto
  
  Pendente
  
  O resultado da avaliação e as informações de exceção.
  - exceptionInfo
    
    objeto
    
    Um objeto que fornece detalhes se uma exceção ocorreu ao avaliar a expressão.
    
    código
    
    string
    
    Definido se o erro ocorreu no lado do DevTools antes da avaliação da expressão.
    
    descrição
    
    string
    
    Definido se o erro ocorreu no lado do DevTools antes da avaliação da expressão.
    
    detalhes
    
    any[]
    
    Definido 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
    
    booleano
    
    Definido se o erro ocorreu no lado do DevTools antes da avaliação da expressão.
    
    isException
    
    booleano
    
    Definido se o código avaliado gerar uma exceção não processada.
    
    valor
    
    string
    
    Definido se o código avaliado gerar uma exceção não processada.
  - resultado
    
    objeto
    
    O resultado da avaliação.

Retorna

Promise<object>

Pendente

Uma função chamada quando a avaliação é concluída.

As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getResources()

Promessa

chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

Recupera a lista de recursos da página inspecionada.

Parâmetros

callback

função opcional

O parâmetro callback tem esta aparência:
```
(resources: Resource[]) => void
```
- recursos
  
  Resource[]
  
  Os recursos na página.

Retorna

Promise<Resource[]>

Pendente

Uma função que recebe a lista de recursos quando a solicitação é concluída.

As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

Atualiza a página inspecionada.

Parâmetros

reloadOptions

objeto opcional
- ignoreCache
  
  booleano opcional
  
  Quando for "true", o carregador vai ignorar o cache de todos os recursos da página inspecionada carregados antes do evento load ser acionado. O efeito é semelhante a pressionar Ctrl+Shift+R na janela inspecionada ou na janela das Ferramentas para desenvolvedores.
- injectedScript
  
  string opcional
  
  Se especificado, o script será injetado em todos os frames 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 enviado durante o carregamento dos recursos da página inspecionada. A string também vai substituir o valor da propriedade navigator.userAgent retornada a 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
  
  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).

Parâmetros

callback

função

O parâmetro callback tem esta aparência:
```
(resource: Resource, content: string) => void
```
- recurso
  
  Recurso
- conteúdo
  
  string

chrome.devtools.inspectedWindow Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Manifesto

Visão geral

Executar código na janela inspecionada

Exemplos

Tipos

Resource

Propriedades

Propriedades

tabId

Tipo

Métodos

eval()

Parâmetros

Retorna

getResources()

Parâmetros

Retorna

reload()

Parâmetros

Eventos

onResourceAdded

Parâmetros

onResourceContentCommitted

Parâmetros

chrome.devtools.inspectedWindow