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.

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

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.

Manifesto

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

"devtools_page"

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 da extensão. (Equivalente a especificar a própria origem da Web da extensão 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

    Recebe o conteúdo do recurso.

    A função getContent tem esta aparência: 

    () => {...}

    • retorna

      Promise<object>

      Chrome 151 ou mais recente

      Uma função que recebe o conteúdo do recurso quando a solicitação é concluída.

  • setContent

    void

    Define o conteúdo do recurso.

    A função setContent tem esta aparência: 

    (content: string, commit: boolean) => {...}

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

    • retorna

      Promise<object>

      Chrome 151 ou mais recente

      Uma função chamada após a conclusão da solicitação.

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

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
): 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.

Retorna

  • Promise<object>

    Chrome 151 ou mais recente

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

getResources()

chrome.devtools.inspectedWindow.getResources(): Promise<Resource[]>

Recupera a lista de recursos da página inspecionada.

Retorna

  • Promise<Resource[]>

    Chrome 151 ou mais recente

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

reload()

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

Atualiza a página inspecionada.

Parâmetros

  • reloadOptions

    objeto opcional

    • ignoreCache

      booleano opcional

      Quando verdadeiro, 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

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