chrome.devtools.inspectedWindow

Descrição

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

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

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 devido a considerações de segurança. Você precisará transmitir o ID da guia para a página de segundo plano e invocar as funções de API chrome.tabs.* de lá.

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 de página ou uma opção para forçar a atualização dos 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, juntamente 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 oferece a capacidade de extensões executarem código JavaScript no contexto da página inspecionada. Esse método é útil 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.

Confira 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 é acessível ao código. Use esse método quando o acesso ao estado do JavaScript da página inspecionada for necessário.
  • 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 transmitido ao callback da extensão. O valor retornado precisa ser um objeto JSON válido (ele pode conter apenas tipos JavaScript primitivos 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 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 seu 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 frame 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 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 de API do DevTools do 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

    Recebe o conteúdo do recurso.

    A função getContent é assim: 

    (callback: function) => {...}

    • callback

      função

      O parâmetro callback é assim: 

      (content: string, encoding: string) => void

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

  • setContent

    void

    Define o conteúdo do recurso.

    A função setContent é assim: 

    (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 compatíveis.

    • commit

      booleano

      Verdadeiro se o usuário tiver terminado de editar o recurso e o novo conteúdo do recurso precisar ser mantido; falso se for uma mudança menor enviada em andamento da edição do recurso pelo usuário.

    • callback

      função opcional

      O parâmetro callback é assim: 

      (error?: object) => void

      • erro

        objeto opcional

        Definido como indefinido se o conteúdo do recurso foi definido com sucesso; descreve o erro de outra forma.

Propriedades

tabId

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

Tipo

número

Métodos

eval()

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

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 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 verdadeiro e code definido como um código de erro. No caso de um erro JavaScript, isException é definido como verdadeiro 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 de opções pode conter uma ou mais opções.

    • frameURL

      string opcional

      Se especificado, a expressão será 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 e versões mais recentes

      Avalie a expressão no contexto de um script de conteúdo de uma extensão que corresponda à origem especificada. Se fornecido, scriptExecutionContext substitui 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 tem o campo isError definido como verdadeiro e o campo code definido como E_NOTFOUND.

  • callback

    função opcional

    O parâmetro callback é assim: 

    (result: object, exceptionInfo: object) => void

    • resultado

      objeto

      O resultado da avaliaçã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 produz uma exceção não tratada.

      • valor

        string

        Definido se o código avaliado produz uma exceção não tratada.

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
): void

Recupera a lista de recursos da página inspecionada.

Parâmetros

  • callback

    função

    O parâmetro callback é assim: 

    (resources: Resource[]) => void

    • recursos

      Resource[]

      Os recursos na página.

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 ignora o cache de todos os recursos da página inspecionada carregados antes do evento load ser disparado. 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 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 especificado, 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 todos os scripts 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 é assim: 

    (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 é assim: 

    (resource: Resource, content: string) => void