browser.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 para desenvolvedores.

A propriedade tabId fornece o identificador da guia que pode ser usado com as chamadas de API browser.tabs.*. No entanto, a API browser.tabs.* não é exposta às páginas de extensão das Ferramentas para Desenvolvedores devido a considerações de segurança. É necessário transmitir o ID da guia para a página de plano de fundo e invocar as funções da API browser.tabs.* de lá.

O método reload pode ser usado para recarregar 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 o recarregamento de recursos em cache.

Use a chamada getResources e o evento onResourceContent para ver 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 permitir a 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 é poderoso 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 pode ser acessado pelo 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 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 cuidado ao processar os dados recebidos da página inspecionada. O contexto de execução é essencialmente controlado pela página inspecionada. Uma página mal-intencionada pode afetar os dados retornados à extensão.

Uma página pode incluir vários contextos de execução de 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 que os scripts de conteúdo da extensão. (Equivalente a especificar a 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:

browser.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 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 é semelhante a: 

    () => {...}

    • retorna

      Promise<object>

      Chrome 151+ browser.* desde o Chrome 152

      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 é semelhante a: 

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

    • conteúdo

      string

      Novo conteúdo do recurso. No momento, apenas recursos do tipo 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 pequena mudança enviada durante a edição do recurso pelo usuário.

    • retorna

      Promise<object>

      Chrome 151+ browser.* desde o Chrome 152

      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.* API REST.

Tipo

número

Métodos

eval()

browser.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 relatar um erro 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 DevTools, o parâmetro isException não é nulo, tem isError definido como verdadeiro e code definido como um código do erro. No caso de um erro de 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 optional

    O parâmetro de opções pode conter uma ou mais opções.

    • frameURL

      string opcional

      Se especificada, a expressão é avaliada no iframe com o URL correspondente ao informado. Por padrão, a expressão é avaliada no frame superior da página inspecionada.

    • scriptExecutionContext

      string opcional

      Chrome 107+ browser.* desde o Chrome 152

      Avalia a expressão no contexto de um script de conteúdo de uma extensão que corresponde à origem especificada. Se fornecido, scriptExecutionContext substitui 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 é avaliada, e o callback é 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.

Retorna

  • Promise<object>

    Chrome 151+ browser.* desde o Chrome 152

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

getResources()

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

Recupera a lista de recursos da página inspecionada.

Retorna

  • Promise<Resource[]>

    Chrome 151+ browser.* desde o Chrome 152

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

reload()

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

Recarrega a página inspecionada.

Parâmetros

  • reloadOptions

    objeto optional

    • ignoreCache

      booleano opcional

      Quando verdadeiro, o carregador ignora o cache de todos os recursos da página inspecionada carregados antes que o evento load seja acionado. O efeito é semelhante a pressionar Ctrl+Shift+R na janela inspecionada ou na janela de 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 script do frame. O script não será injetado após as recargas 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 que é retornada para todos os scripts em execução na página inspecionada.

Eventos

onResourceAdded

browser.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

Disparado quando um novo recurso é adicionado à página inspecionada.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (resource: Resource) => void

onResourceContentCommitted

browser.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

Acionado 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 é semelhante a: 

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