chrome.webNavigation

Descrição

Use a API chrome.webNavigation para receber notificações sobre o status das solicitações de navegação em andamento.

Permissões

webNavigation

Todos os métodos e eventos chrome.webNavigation exigem que você declare a permissão "webNavigation" no manifesto de extensões. Exemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "webNavigation"
  ],
  ...
}

Conceitos e uso

Ordem do evento

Para uma navegação concluída, os eventos são disparados na seguinte ordem:

onBeforeNavigate -> onCommitted -> [onDOMContentLoaded] -> onCompleted

Qualquer erro que ocorre durante o processo resulta em um evento onErrorOccurred. Para uma navegação específica, não há mais eventos disparados após onErrorOccurred.

Se um frame de navegação tiver subframes, a onCommitted será disparada antes de qualquer um dos onBeforeNavigate filhos. Já onCompleted será acionada depois de todas as onCompleted filhas.

Se o fragmento de referência de um frame for alterado, um evento onReferenceFragmentUpdated será disparado. Esse evento pode ser disparado a qualquer momento após onDOMContentLoaded, mesmo após onCompleted.

Se a API do histórico for usada para modificar o estado de um frame (por exemplo, com history.pushState(), um evento onHistoryStateUpdated será disparado. Este evento pode ser disparado a qualquer momento após onDOMContentLoaded.

Se a navegação restaurar uma página do cache de avanço e retorno, o evento onDOMContentLoaded não será disparado. O evento não é disparado porque o conteúdo já tinha concluído o carregamento quando a página foi visitada pela primeira vez.

Se uma navegação for acionada usando o Instant do Chrome ou as Páginas instantâneas, uma página completamente carregada será trocada para a guia atual. Nesse caso, um evento onTabReplaced é acionado.

Relação com eventos webRequest

Não há uma ordem definida entre os eventos da API webRequest e da API webNavigation. É possível que os eventos webRequest ainda sejam recebidos para frames que já iniciaram uma nova navegação ou que uma navegação só prossiga depois que os recursos de rede já estiverem totalmente carregados.

Em geral, os eventos webNavigation estão intimamente relacionados ao estado de navegação mostrado na IU, enquanto os eventos webRequest correspondem ao estado da pilha de rede, que geralmente é opaco para o usuário.

IDs de guia

Nem todas as guias de navegação correspondem a guias reais na interface do Chrome, por exemplo, uma guia que está sendo pré-renderizada. Essas guias não podem ser acessadas usando a API Tabs, nem é possível solicitar informações sobre elas chamando webNavigation.getFrame() ou webNavigation.getAllFrames(). Depois que essa guia é trocada, um evento onTabReplaced é disparado, e elas se tornam acessíveis por essas APIs.

Marcações de tempo

É importante observar que algumas dificuldades técnicas no processamento de processos distintos do Chrome pelo SO podem fazer com que o relógio fique distorcido entre o próprio navegador e os processos de extensão. Isso significa que a propriedade timeStamp da propriedade timeStamp do evento WebNavigation só terá consistência interna. A comparação de um evento com outro informa o deslocamento correto entre eles, mas ao compará-los ao horário atual dentro da extensão (usando (new Date()).getTime(), por exemplo) pode gerar resultados inesperados.

IDs de frame

Os frames em uma guia podem ser identificados por um ID de frame. O ID do frame principal é sempre 0, e o ID dos frames filhos é um número positivo. Depois que um documento é criado em um frame, o ID dele permanece constante durante o ciclo de vida do documento. A partir do Chrome 49, esse ID também é constante durante o ciclo de vida do frame (em várias navegações).

Devido à natureza multiprocessos do Chrome, uma guia pode usar processos diferentes para renderizar a origem e o destino de uma página da Web. Portanto, se uma navegação ocorrer em um novo processo, você poderá receber eventos da página nova e da antiga até que a nova navegação seja confirmada (ou seja, o evento onCommitted é enviado para o novo frame principal). Em outras palavras, é possível ter mais de uma sequência pendente de eventos webNavigation com o mesmo frameId. As sequências podem ser diferenciadas pela chave processId.

Observe também que, durante um carregamento provisório, o processo pode ser alterado várias vezes. Isso acontece quando a carga é redirecionada para outro site. Nesse caso, você vai receber eventos onBeforeNavigate e onErrorOccurred repetidos até receber o evento onCommitted final.

Outro conceito problemático com as extensões é o ciclo de vida do frame. Um frame hospeda um documento, que está associado a um URL confirmado. O documento pode mudar (por exemplo, navegando), mas o frameId não. Por isso, é difícil associar que algo aconteceu em um documento específico apenas com frameIds. Estamos introduzindo um conceito de documentId, que é um identificador exclusivo por documento. Se um frame for navegado e abrir um novo documento, o identificador mudará. Esse campo é útil para determinar quando as páginas mudam o estado do ciclo de vida (entre pré-renderização/ativa/armazenada em cache) porque permanece o mesmo.

Tipos e qualificadores de transição

O evento webNavigation onCommitted tem uma propriedade transitionType e uma transitionQualifiers. O tipo de transição é o mesmo usado na API de histórico que descreve como o navegador navegou até esse URL específico. Além disso, vários qualificadores de transição podem ser retornados para definir melhor a navegação.

Existem os seguintes qualificadores de transição:

Qualificador de transiçãoDescrição
"client_redirect"Um ou mais redirecionamentos causados por JavaScript ou tags de atualização meta na página ocorreram durante a navegação.
"server_redirect"Um ou mais redirecionamentos causados por cabeçalhos HTTP enviados do servidor ocorreram durante a navegação.
"forward_back"O usuário utilizou o botão Avançar ou Voltar para iniciar a navegação.
"from_address_bar"O usuário iniciou a navegação na barra de endereço (também conhecida como omnibox).

Exemplos

Para testar essa API, instale o exemplo da API webNavigation no repositório chrome-extension-samples.

Tipos

TransitionQualifier

Chrome 44 ou mais recente

Tipo enumerado

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 ou mais recente

Causa da navegação. São usados os mesmos tipos de transição definidos na API de histórico. Esses são os mesmos tipos de transição definidos na API de histórico, exceto com "start_page" no lugar de "auto_toplevel" (para compatibilidade com versões anteriores).

Tipo enumerado

"link"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"start_page"

"form_submit"

"keyword_generated"

Métodos

getAllFrames()

Promessa 
chrome.webNavigation.getAllFrames(
  details: object,
  callback?: function,
)

Recupera informações sobre todos os frames de uma determinada guia.

Parâmetros

  • detalhes

    objeto

    Informações sobre a guia da qual recuperar todos os frames.

    • tabId

      number

      O ID da guia.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (details?: object[])=>void

    • detalhes

      objeto[] opcional

      Uma lista de frames na guia especificada. O valor será nulo se o ID da guia especificado for inválido.

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • errorOccurred

        boolean

        Verdadeiro se a última navegação no frame foi interrompida por um erro, ou seja, o evento onErrorOccurred disparado.

      • frameId

        number

        É o ID do frame. 0 indica que este é o frame principal; um valor positivo indica o ID de um subframe.

      • frameType

        FrameType

        Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        O ID do processo que executa o renderizador para esse frame.

      • url

        string

        O URL atualmente associado a este frame.

Retorna

  • Promise<object[]|undefined>

    Chrome 93 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getFrame()

Promessa 
chrome.webNavigation.getFrame(
  details: object,
  callback?: function,
)

Recupera informações sobre o frame especificado. Um frame refere-se a um <iframe> ou <frame> de uma página da Web e é identificado por um ID de guia e um ID de frame.

Parâmetros

  • detalhes

    objeto

    Informações sobre o frame sobre o qual recuperar informações.

    • documentId

      string opcional

      Chrome 106 ou mais recente

      O UUID do documento. Se o frameId e/ou tabId forem fornecidos, eles serão validados para corresponder ao documento encontrado pelo ID fornecido.

    • frameId

      número opcional

      O ID do frame na guia especificada.

    • processId

      número opcional

      Descontinuado desde o Chrome 49

      Os frames agora são identificados de forma exclusiva pelos IDs da guia e do frame. O ID do processo não é mais necessário e, portanto, é ignorado.

      O ID do processo que executa o renderizador para essa guia.

    • tabId

      número opcional

      O ID da guia em que o frame está.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (details?: object)=>void

    • detalhes

      objeto opcional

      Informações sobre o frame solicitado, "null" se o ID do frame especificado e/ou o ID da guia for inválido.

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • errorOccurred

        boolean

        Verdadeiro se a última navegação no frame foi interrompida por um erro, ou seja, o evento onErrorOccurred disparado.

      • frameType

        FrameType

        Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        O ID do frame pai, ou -1, se este for o frame principal.

      • url

        string

        O URL atualmente associado a esse frame, se o frame identificado pelo frameId existia em um ponto na guia especificada. O fato de um URL estar associado a um determinado frameId não significa que o frame correspondente ainda existe.

Retorna

  • Promise<object|undefined>

    Chrome 93 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onBeforeNavigate

chrome.webNavigation.onBeforeNavigate.addListener(
  callback: function,
  filters?: object,
)

Disparado quando uma navegação está prestes a ocorrer.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • frameId

        number

        Zero indica que a navegação acontece na janela de conteúdo da guia; um valor positivo indica a navegação em um subframe. Os IDs de frame são exclusivos para uma determinada guia e processo.

      • Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        Descontinuado desde o Chrome 50

        O processId não está mais definido para este evento, já que o processo que vai renderizar o documento resultante não é conhecido até o onCommit.

        O valor de -1.

      • tabId

        number

        O ID da guia em que a navegação está prestes a ocorrer.

      • timeStamp

        number

        A hora em que o navegador estava prestes a iniciar a navegação, em milissegundos, desde o período.

      • url

        string

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onCommitted

chrome.webNavigation.onCommitted.addListener(
  callback: function,
  filters?: object,
)

Disparado quando uma navegação é confirmada. O download do documento (e dos recursos a que ele se refere, como imagens e subquadros) ainda pode estar sendo feito, mas pelo menos parte do documento foi recebido do servidor e o navegador decidiu mudar para o novo documento.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • frameId

        number

        Zero indica que a navegação acontece na janela de conteúdo da guia; um valor positivo indica a navegação em um subframe. Os IDs de frame são exclusivos dentro de uma guia.

      • Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        Chrome 74 ou mais recente

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        O ID do processo que executa o renderizador para esse frame.

      • tabId

        number

        O ID da guia em que a navegação ocorre.

      • timeStamp

        number

        A hora em que a navegação foi confirmada, em milissegundos, desde o período.

      • transitionQualifiers

        TransitionQualifier[]

        Uma lista de qualificadores de transição.

      • transitionType

        TransitionType

        Causa da navegação.

      • url

        string

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onCompleted

chrome.webNavigation.onCompleted.addListener(
  callback: function,
  filters?: object,
)

Disparado quando um documento, incluindo os recursos a que se refere, é completamente carregado e inicializado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • frameId

        number

        Zero indica que a navegação acontece na janela de conteúdo da guia; um valor positivo indica a navegação em um subframe. Os IDs de frame são exclusivos dentro de uma guia.

      • Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        Chrome 74 ou mais recente

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        O ID do processo que executa o renderizador para esse frame.

      • tabId

        number

        O ID da guia em que a navegação ocorre.

      • timeStamp

        number

        A hora em que o documento terminou de carregar, em milissegundos, desde o período.

      • url

        string

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onCreatedNavigationTarget

chrome.webNavigation.onCreatedNavigationTarget.addListener(
  callback: function,
  filters?: object,
)

Disparado quando uma nova janela ou guia em uma janela existente é criada para hospedar uma navegação.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • sourceFrameId

        number

        O ID do frame com sourceTabId em que a navegação é acionada. O valor 0 indica o frame principal.

      • sourceProcessId

        number

        O ID do processo que executa o renderizador para o frame de origem.

      • sourceTabId

        number

        O ID da guia em que a navegação é acionada.

      • tabId

        number

        O ID da guia em que o URL é aberto

      • timeStamp

        number

        A hora em que o navegador estava prestes a criar uma nova visualização, em milissegundos, desde o período.

      • url

        string

        O URL que será aberto na nova janela.

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onDOMContentLoaded

chrome.webNavigation.onDOMContentLoaded.addListener(
  callback: function,
  filters?: object,
)

Disparado quando o DOM da página é totalmente construído, mas os recursos referenciados podem não concluir o carregamento.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • frameId

        number

        Zero indica que a navegação acontece na janela de conteúdo da guia; um valor positivo indica a navegação em um subframe. Os IDs de frame são exclusivos dentro de uma guia.

      • Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        Chrome 74 ou mais recente

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        O ID do processo que executa o renderizador para esse frame.

      • tabId

        number

        O ID da guia em que a navegação ocorre.

      • timeStamp

        number

        A hora em que o DOM da página foi totalmente construído, em milissegundos, desde o período.

      • url

        string

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onErrorOccurred

chrome.webNavigation.onErrorOccurred.addListener(
  callback: function,
  filters?: object,
)

Disparado quando ocorre um erro e a navegação é cancelada. Isso pode acontecer se tiver ocorrido um erro de rede ou se o usuário tiver cancelado a navegação.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • error

        string

        A descrição do erro.

      • frameId

        number

        Zero indica que a navegação acontece na janela de conteúdo da guia; um valor positivo indica a navegação em um subframe. Os IDs de frame são exclusivos dentro de uma guia.

      • Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        Chrome 74 ou mais recente

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        Descontinuado desde o Chrome 50

        O processId não está mais definido para este evento.

        O valor de -1.

      • tabId

        number

        O ID da guia em que a navegação ocorre.

      • timeStamp

        number

        A hora em que o erro ocorreu, em milissegundos, desde o período.

      • url

        string

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onHistoryStateUpdated

chrome.webNavigation.onHistoryStateUpdated.addListener(
  callback: function,
  filters?: object,
)

Disparado quando o histórico do frame foi atualizado para um novo URL. Todos os eventos futuros para esse frame usarão o URL atualizado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • frameId

        number

        Zero indica que a navegação acontece na janela de conteúdo da guia; um valor positivo indica a navegação em um subframe. Os IDs de frame são exclusivos dentro de uma guia.

      • Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        Chrome 74 ou mais recente

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        O ID do processo que executa o renderizador para esse frame.

      • tabId

        number

        O ID da guia em que a navegação ocorre.

      • timeStamp

        number

        A hora em que a navegação foi confirmada, em milissegundos, desde o período.

      • transitionQualifiers

        TransitionQualifier[]

        Uma lista de qualificadores de transição.

      • transitionType

        TransitionType

        Causa da navegação.

      • url

        string

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onReferenceFragmentUpdated

chrome.webNavigation.onReferenceFragmentUpdated.addListener(
  callback: function,
  filters?: object,
)

Disparado quando o fragmento de referência de um frame é atualizado. Todos os eventos futuros para esse frame usarão o URL atualizado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • documentId

        string

        Chrome 106 ou mais recente

        Um UUID do documento carregado.

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • frameId

        number

        Zero indica que a navegação acontece na janela de conteúdo da guia; um valor positivo indica a navegação em um subframe. Os IDs de frame são exclusivos dentro de uma guia.

      • Chrome 106 ou mais recente

        Tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.

      • parentFrameId

        number

        Chrome 74 ou mais recente

        O ID do frame pai, ou -1, se este for o frame principal.

      • processId

        number

        O ID do processo que executa o renderizador para esse frame.

      • tabId

        number

        O ID da guia em que a navegação ocorre.

      • timeStamp

        number

        A hora em que a navegação foi confirmada, em milissegundos, desde o período.

      • transitionQualifiers

        TransitionQualifier[]

        Uma lista de qualificadores de transição.

      • transitionType

        TransitionType

        Causa da navegação.

      • url

        string

  • filtros

    objeto opcional

    • Condições a que o URL que está sendo navegado precisa atender. Os campos "schemes" e "ports" do UrlFilter são ignorados para esse evento.

onTabReplaced

chrome.webNavigation.onTabReplaced.addListener(
  callback: function,
)

Disparado quando o conteúdo da guia é substituído por outra (geralmente pré-renderizada).

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object)=>void

    • detalhes

      objeto

      • replacedTabId

        number

        O ID da guia que foi substituída.

      • tabId

        number

        O ID da guia que substituiu a antiga.

      • timeStamp

        number

        A hora em que a substituição aconteceu, em milissegundos, desde o período.