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 da página.

Manifesto

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

"devtools_page"

Use chrome.devtools.inspectedWindow para interagir com a janela inspecionada: extraia o ID da guia de página inspecionada, avaliar o código no contexto da janela inspecionada, atualizar a página ou obter a lista de recursos da página.

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

Visão geral

A propriedade tabId fornece o identificador de guia que você pode usar com o chrome.tabs.*. chamadas de API. No entanto, a API chrome.tabs.* não está exposta às Ferramentas para Desenvolvedores páginas de extensão devido a considerações de segurança. Você terá que passar o ID da guia para o segundo plano e invoque as funções da API chrome.tabs.* nela.

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 da string do user agent, um script que será injetado logo após o carregamento da página ou uma para forçar o recarregamento dos recursos armazenados em cache.

Use a chamada getResources e o evento onResourceContent para acessar a lista de recursos (documentos, folhas de estilo, scripts, imagens etc.) na página inspecionada. Os métodos getContent e Os métodos setContent da classe Resource com o evento onResourceContentCommitted podem ser usado para oferecer suporte à modificação do conteúdo do recurso, por exemplo, por um editor externo.

Como executar código na janela inspecionada

Com o método eval, as extensões podem executar o código JavaScript no contexto da a página inspecionada. Esse método é poderoso quando usado no contexto certo e perigoso quando usado inadequadamente. Use o método tabs.executeScript, a menos que você precise da funcionalidade específica que o método eval fornece.

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 JavaScript da janela inspecionada fica acessível ao código. Use esse método quando acessar o O estado do JavaScript da página inspecionada é obrigatório.
  • O contexto de execução do código que está sendo avaliado inclui a API Developer Tools do console. 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 (pode conter apenas tipos JavaScript primitivos e referências a outros objetos JSON). Tenha cuidado extra ao processar os dados recebidos na página inspecionada: o contexto de execução é essencialmente controlado pela página inspecionada; por página maliciosa pode afetar os dados retornados à extensão.
.

Uma página pode incluir vários contextos diferentes de execução de JavaScript. Cada frame tem um próprio contexto, além de um contexto adicional para cada extensão que tem scripts de conteúdo em execução na 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 você pode usar 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 dele.
useContentScriptContext
Se verdadeiro, execute o script no mesmo contexto que os scripts de conteúdo das extensões. (equivalente a especificando a própria origem da Web das extensões como a origem da segurança de contexto. Isso pode ser usado para 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 (link em inglês) em chrome-extension-samples repositório de dados.

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: 

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

      • encoding

        string

        Vai ser vazio se o conteúdo não estiver codificado. Caso contrário, codificará 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, só há suporte para recursos com o tipo de texto.

    • commit

      booleano

      True se o usuário terminou de editar o recurso e o novo conteúdo do recurso deve ser mantido; "false" se for uma pequena alteração enviada em andamento pelo usuário que edita o recurso.

    • callback

      função opcional

      O parâmetro callback tem esta aparência: 

      (error?: object) => void

      • erro

        objeto opcional

        Defina como indefinido se o conteúdo do recurso foi definido com sucesso. descreve o erro.

Propriedades

tabId

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

Tipo

number

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á lançada. A função eval pode informar um erro no 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 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 versão 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 substitui 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 é 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.

  • callback

    função opcional

    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 ocorreu uma exceção durante a avaliação da expressão.

      • código

        string

        Define se o erro ocorreu no DevTools antes da avaliação da expressão.

      • descrição

        string

        Define se o erro ocorreu no DevTools antes da avaliação da expressão.

      • detalhes

        qualquer[]

        Define se o erro ocorreu no lado do DevTools antes que a expressão seja avaliada, 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

        Define se o erro ocorreu no DevTools antes da avaliação da expressão.

      • isException

        booleano

        Definido se o código avaliado produzir uma exceção não processada.

      • valor

        string

        Definido se o código avaliado produzir uma exceção não processada.

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 tem esta aparência: 

    (resources: Resource[]) => void

    • recursos

      Recurso[]

      Os recursos da página.

reload()

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

Recarrega a página inspecionada.

Parâmetros

  • reloadOptions

    objeto opcional

    • ignoreCache

      booleano opcional

      Quando verdadeiro, o carregador ignora o cache para todos os recursos da página inspecionados 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 atualizações subsequentes, por exemplo, se o usuário pressionar Ctrl+R.

    • userAgent

      string opcional

      Se especificada, a string substitui o valor do cabeçalho HTTP User-Agent que é enviado ao carregar os recursos da página inspecionada. A string também substitui o valor da propriedade navigator.userAgent que é retornada para 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 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