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ê precisa 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 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, 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 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 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 de 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 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 de API das Ferramentas para desenvolvedores 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

    Recebe o conteúdo do recurso.

    A função getContent é assim: 

    () => {...}

    • retorna

      Promise<object>

      Pendente

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

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

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

    • retorna

      Promise<object>

      Pendente

      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.

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 de avaliação pode informar um erro do lado das Ferramentas para desenvolvedores ou uma exceção de 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 das Ferramentas para desenvolvedores, 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 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.

Retorna

  • Promise<object>

    Pendente

    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[]>

    Pendente

    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 ignora 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 todos os scripts em execução na página inspecionada.

Eventos

onResourceAdded

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

Acionado 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,
)

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

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