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 da extensão. Exemplo:

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

Conceitos e uso

Ordem do evento

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

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

Qualquer erro que ocorra durante o processo resulta em um evento onErrorOccurred. Para uma navegação específica, não há mais eventos disparados depois de onErrorOccurred.

Se um frame de navegação tiver subframes, o onCommitted dele será disparado antes do onBeforeNavigate de qualquer um dos filhos. Já o onCompleted será disparado depois do onCompleted de todos os filhos.

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

Se a API History for usada para modificar o estado de um frame (por exemplo, usando history.pushState()), um evento onHistoryStateUpdated será acionado. Esse evento pode ser disparado a qualquer momento depois de onDOMContentLoaded.

Se uma navegação restaurar uma página do cache de avanço e retorno, o evento onDOMContentLoaded não será acionado. O evento não é acionado porque o conteúdo já foi carregado quando a página foi acessada pela primeira vez.

Se uma navegação foi acionada usando o Chrome Instant ou as Páginas instantâneas, uma página totalmente carregada será trocada na 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 os da API webNavigation. É possível que 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 exibido na interface, enquanto os eventos webRequest correspondem ao estado da pilha de rede, que geralmente é opaco para o usuário.

IDs de guias

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(). Quando uma guia é trocada, um evento onTabReplaced é disparado, e elas ficam acessíveis por essas APIs.

Carimbos de data/hora

É importante observar que algumas peculiaridades técnicas no tratamento de processos distintos do Chrome pelo SO podem fazer com que o relógio fique distorcido entre o navegador e os processos de extensão. Isso significa que a propriedade timeStamp do evento WebNavigation só tem garantia de ser internamente consistente.timeStamp Comparar um evento com outro vai dar o ajuste correto entre eles, mas comparar com a hora atual na extensão (usando (new Date()).getTime(), por exemplo) pode gerar resultados inesperados.

IDs de frames

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 é construído 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 a vida útil do frame (em várias navegações).

Devido à natureza multiprocesso 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 seja 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 distinguidas pela chave processId.

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

Outro conceito problemático com extensões é o ciclo de vida do frame. Um frame hospeda um documento (associado a um URL confirmado). O documento pode mudar (por exemplo, ao navegar), mas o frameId não. Por isso, é difícil associar algo que aconteceu em um documento específico apenas com frameIds. Estamos apresentando o conceito de documentId, que é um identificador exclusivo por documento. Se um frame for navegado e abrir um novo documento, o identificador vai mudar. Esse campo é útil para determinar quando as páginas mudam o estado do ciclo de vida (entre pré-renderização/ativa/em cache), porque ele 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 History, descrevendo como o navegador navegou até esse URL específico. Além disso, vários qualificadores de transição podem ser retornados para definir ainda mais a navegação.

Estes são os qualificadores de transição:

Qualificadora de transiçãoDescrição
"client_redirect"Um ou mais redirecionamentos causados por tags JavaScript ou de meta-atualização 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 usou 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

Enumeração

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 ou mais recente

Causa da navegação. Os mesmos tipos de transição definidos na API History são usados. Esses são os mesmos tipos de transição definidos na API History, exceto que "start_page" substitui "auto_toplevel" (para compatibilidade com versões anteriores).

Enumeração

"link"

"digitado"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"gerado"

"start_page"

"form_submit"

"reload"

"keyword"

"keyword_generated"

Métodos

getAllFrames()

chrome.webNavigation.getAllFrames(
  details: object,
): Promise<object[] | undefined>

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

Parâmetros

  • detalhes

    objeto

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

    • tabId

      número

      O ID da guia.

Retorna

  • Promise<object[] | undefined>

    Chrome 93+

getFrame()

chrome.webNavigation.getFrame(
  details: object,
): Promise<object | undefined>

Recupera informações sobre o frame especificado. Um frame se refere a um <iframe> ou um <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 a ser recuperado.

    • documentId

      string opcional

      Chrome 106 ou mais recente

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

    • frameId

      number optional

      O ID do frame na guia especificada.

    • processId

      number optional

      Suspensas desde o Chrome 49

      Os frames agora são identificados de forma exclusiva pelo ID 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

      number optional

      O ID da guia em que o frame está.

Retorna

  • Promise<object | undefined>

    Chrome 93+

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) =& gt;void

    • detalhes

      objeto

      • Chrome 106 ou mais recente

        O ciclo de vida em que o documento está.

      • frameId

        número

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

      • Chrome 106 ou mais recente

        O tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento principal proprietário deste frame. Não é definido se não houver um elemento pai.

      • parentFrameId

        número

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

      • processId

        número

        Suspensas desde o Chrome 50

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

        O valor -1.

      • tabId

        número

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

      • timeStamp

        número

        O momento em que o navegador estava prestes a iniciar a navegação, em milissegundos desde a época.

      • url

        string

  • filtros

    objeto opcional

    • Condições que o URL de navegação precisa atender. Os campos "schemes" e "ports" de UrlFilter são ignorados para esse evento.

onCommitted

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

Disparado quando uma navegação é confirmada. O documento (e os recursos a que ele se refere, como imagens e subframes) ainda pode estar sendo baixado, mas pelo menos parte dele foi recebida 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) =& gt;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

        número

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

      • Chrome 106 ou mais recente

        O tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento principal proprietário deste frame. Não é definido se não houver um elemento pai.

      • parentFrameId

        número

        Chrome 74 ou mais recente

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

      • processId

        número

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

      • tabId

        número

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

      • timeStamp

        número

        O momento 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 que o URL de navegação precisa atender. Os campos "schemes" e "ports" de UrlFilter são ignorados para esse evento.

onCompleted

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

Acionado quando um documento, incluindo os recursos a que ele se refere, é totalmente carregado e inicializado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) =& gt;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

        número

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

      • Chrome 106 ou mais recente

        O tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento principal proprietário deste frame. Não é definido se não houver um elemento pai.

      • parentFrameId

        número

        Chrome 74 ou mais recente

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

      • processId

        número

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

      • tabId

        número

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

      • timeStamp

        número

        O momento em que o documento terminou de ser carregado, em milissegundos desde a época.

      • url

        string

  • filtros

    objeto opcional

    • Condições que o URL de navegação precisa atender. Os campos "schemes" e "ports" de UrlFilter são ignorados para esse evento.

onCreatedNavigationTarget

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

Disparado quando uma nova janela ou uma nova 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) =& gt;void

    • detalhes

      objeto

      • sourceFrameId

        número

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

      • sourceProcessId

        número

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

      • sourceTabId

        número

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

      • tabId

        número

        O ID da guia em que o URL é aberto.

      • timeStamp

        número

        O momento em que o navegador estava prestes a criar uma nova visualização, em milissegundos desde a época.

      • url

        string

        O URL a ser aberto na nova janela.

  • filtros

    objeto opcional

    • Condições que o URL de navegação precisa atender. Os campos "schemes" e "ports" de UrlFilter são ignorados para esse evento.

onDOMContentLoaded

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

Disparado quando o DOM da página está totalmente construído, mas os recursos referenciados podem não terminar de carregar.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) =& gt;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

        número

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

      • Chrome 106 ou mais recente

        O tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento principal proprietário deste frame. Não é definido se não houver um elemento pai.

      • parentFrameId

        número

        Chrome 74 ou mais recente

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

      • processId

        número

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

      • tabId

        número

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

      • timeStamp

        número

        O momento em que o DOM da página foi totalmente construído, em milissegundos desde a época.

      • url

        string

  • filtros

    objeto opcional

    • Condições que o URL de navegação precisa atender. Os campos "schemes" e "ports" de 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 é interrompida. Isso pode acontecer se ocorrer um erro de rede ou se o usuário interromper a navegação.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) =& gt;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á.

      • erro

        string

        A descrição do erro.

      • frameId

        número

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

      • Chrome 106 ou mais recente

        O tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento principal proprietário deste frame. Não é definido se não houver um elemento pai.

      • parentFrameId

        número

        Chrome 74 ou mais recente

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

      • processId

        número

        Suspensas desde o Chrome 50

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

        O valor -1.

      • tabId

        número

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

      • timeStamp

        número

        O momento em que o erro ocorreu, em milissegundos desde o período.

      • url

        string

  • filtros

    objeto opcional

    • Condições que o URL de navegação precisa atender. Os campos "schemes" e "ports" de UrlFilter são ignorados para esse evento.

onHistoryStateUpdated

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) =& gt;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

        número

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

      • Chrome 106 ou mais recente

        O tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento principal proprietário deste frame. Não é definido se não houver um elemento pai.

      • parentFrameId

        número

        Chrome 74 ou mais recente

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

      • processId

        número

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

      • tabId

        número

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

      • timeStamp

        número

        O momento 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 que o URL de navegação precisa atender. Os campos "schemes" e "ports" de 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 desse frame vão usar o URL atualizado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) =& gt;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

        número

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

      • Chrome 106 ou mais recente

        O tipo de frame em que a navegação ocorreu.

      • parentDocumentId

        string opcional

        Chrome 106 ou mais recente

        Um UUID do documento principal proprietário deste frame. Não é definido se não houver um elemento pai.

      • parentFrameId

        número

        Chrome 74 ou mais recente

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

      • processId

        número

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

      • tabId

        número

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

      • timeStamp

        número

        O momento 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 que o URL de navegação precisa atender. Os campos "schemes" e "ports" de 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) =& gt;void

    • detalhes

      objeto

      • replacedTabId

        número

        O ID da guia que foi substituída.

      • tabId

        número

        O ID da guia que substituiu a antiga.

      • timeStamp

        número

        O momento em que a substituição ocorreu, em milissegundos desde o período.