chrome.devtools.inspectedWindow

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.

Consulte o Resumo das APIs do DevTools para uma introdução geral ao uso das APIs das Ferramentas para desenvolvedores.

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.

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para o uso dessa API.

"devtools_page"

Executar o 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 recente

      Avalie 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 campo code definido como E_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

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (resources: Resource[])=>void

    • recursos

      Recurso[]

      Os recursos na página.

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 propriedade navigator.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

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