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 que uma navegação seja concluída, os eventos são disparados na seguinte ordem:

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

Qualquer erro que ocorrer durante o processo resultará em um evento onErrorOccurred. Para um tipo específico de navegação, não há outros eventos acionados após onErrorOccurred.

Se um frame de navegação tiver subframes, o onCommitted será acionado antes do onBeforeNavigate enquanto o onCompleted é acionado depois de todos os onCompleted dos filhos.

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

Se a API History for usada para modificar o estado de um frame (por exemplo, usando history.pushState(), uma O evento onHistoryStateUpdated é disparado. Este evento pode ser disparado a qualquer momento após onDOMContentLoaded.

Caso uma navegação restaure uma página do cache de avanço e retorno, o evento onDOMContentLoaded não será disparada. O evento não é acionado porque o carregamento do conteúdo já foi concluído quando a página foi visitado pela primeira vez.

Se uma navegação era acionada usando o Instant do Chrome ou as Páginas instantâneas, uma navegação completamente carregada é alterado 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 os do API webNavigation. É possível que eventos webRequest ainda sejam recebidos para frames que já iniciou uma nova navegação ou que ela só prossiga depois que os recursos de rede já estiverem está totalmente carregado.

Em geral, os eventos webNavigation estão intimamente relacionados ao estado da navegação que é exibido na interface, enquanto os eventos webRequest correspondem ao estado da pilha de rede que está são geralmente opacas 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é-renderizados. Essas guias não são acessíveis usando a API de guias e também não é possível solicitar informações sobre elas chamando webNavigation.getFrame() ou webNavigation.getAllFrames(). Uma vez que uma guia for trocado, um evento onTabReplaced será acionado e eles se tornarão acessíveis por meio dessas APIs.

Carimbos de data/hora

É importante observar que há algumas peculiaridades técnicas no modo como o sistema operacional lida com versões distintas do Chrome processos 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 é garantida apenas para manter a consistência interna. A comparação de um evento com outro fornecerá o deslocamento correto entre eles, mas comparando-os com o horário atual dentro da extensão (usando (new Date()).getTime(), por exemplo) podem gerar resultados inesperados.

IDs de frames

Os frames de uma guia podem ser identificados por um ID de frame. O ID do frame principal é sempre 0, o O ID dos frames filhos é um número positivo. Depois que um documento é construído em um frame, o ID do frame permanece constante durante a vida útil do documento. A partir do Chrome 49, esse ID também será constante para 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 ocorre em um novo processo, você pode recebem eventos da página nova e da antiga até que a nova navegação seja confirmada (ou seja, o 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 diferenciados pela chave processId.

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

Outro conceito problemático com as extensões é o ciclo de vida 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, e por isso ele é difícil associar que algo aconteceu em um documento específico com apenas frameIds. Apresentamos o conceito de um documentId que é um identificador exclusivo por documento. Se um frame for navegado e abrir uma novo documento, o identificador será alterado. Esse campo é útil para determinar quando as páginas mudam o estado do ciclo de vida (entre pré-renderização/ativo/em cache) porque permanece a mesma.

Tipos de transição e qualificadores

O evento onCommitted webNavigation tem transitionType e transitionQualifiers . O tipo de transição é o mesmo usado na API de histórico, que descreve como a navegador acessou este URL específico. Além disso, vários qualificadores de transição podem ser retornados que definem 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 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 nas chrome-extension-samples repositório de dados.

Tipos

TransitionQualifier

Chrome 44 ou superior

Enumeração

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44 ou superior

Causa da navegação. São usados os mesmos tipos de transição definidos na API History. 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).

Enumeração

"link"

"typed"

"auto_bookmark"

"auto_subframe"

"manual_subframe"

"gerado"

"start_page"

"form_submit"

"atualizar"

"palavra-chave"

"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 opcional

    O parâmetro callback tem esta aparência: 

    (details?: object[]) => void

    • detalhes

      objeto[] opcional

      Uma lista de frames na guia especificada, nulo se o ID da guia especificada for inválido.

      • documentId

        string

        Chrome 106 ou versões mais recentes

        Um UUID do documento carregado.

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • errorOccurred

        booleano

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

      • frameId

        number

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

      • frameType

        FrameType

        Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

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

      • processId

        number

        O ID do processo que executa o renderizador desse frame.

      • url

        string

        O URL atualmente associado a este frame.

Retorna

  • Promise<object[] | indefinido>

    Chrome 93 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getFrame()

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

Recupera informações sobre o frame fornecido. Um frame se refere a um <iframe> ou um <frame> de uma página da Web e é identificada 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 versões mais recentes

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

    • frameId

      número opcional

      É o ID do frame na guia especificada.

    • processId

      número opcional

      Suspenso desde o Chrome 49

      Os frames agora são identificados exclusivamente 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 dessa guia.

    • tabId

      número opcional

      O ID da guia em que o frame está.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (details?: object) => void

    • detalhes

      objeto opcional

      Informações sobre o frame solicitado. Será nulo se o ID do frame especificado e/ou ID da guia forem inválidos.

      • documentId

        string

        Chrome 106 ou versões mais recentes

        Um UUID do documento carregado.

      • documentLifecycle

        DocumentLifecycle

        Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • errorOccurred

        booleano

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

      • frameType

        FrameType

        Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

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

      • url

        string

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

Retorna

  • Promise&lt;object | indefinido>

    Chrome 93 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

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 versões mais recentes

        O ciclo de vida do documento.

      • frameId

        number

        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 frames são exclusivos para uma determinada guia e processo.

      • Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

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

      • processId

        number

        Suspenso desde o Chrome 50

        O processId não está mais definido para esse evento, já que o processo que renderizará o documento resultante não é conhecido até 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 que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos de UrlFilter são ignorados para esse evento.

onCommitted

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

Disparado quando uma navegação é confirmada. É possível que o download do documento (e dos recursos a que ele se refere, como imagens e subframes) ainda esteja sendo baixado, 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 versões mais recentes

        Um UUID do documento carregado.

      • Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • frameId

        number

        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 frames são exclusivos em uma guia.

      • Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

        Chrome 74 ou superior

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

      • processId

        number

        O ID do processo que executa o renderizador desse 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 que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos de UrlFilter são ignorados para esse evento.

onCompleted

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

Disparado quando um documento, incluindo os recursos aos quais ele 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 versões mais recentes

        Um UUID do documento carregado.

      • Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • frameId

        number

        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 frames são exclusivos em uma guia.

      • Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

        Chrome 74 ou superior

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

      • processId

        number

        O ID do processo que executa o renderizador desse 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 que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos 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) => 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 do 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 em uma nova janela.

  • filtros

    objeto opcional

    • Condições que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos de 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 terminar de carregar.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) => void

    • detalhes

      objeto

      • documentId

        string

        Chrome 106 ou versões mais recentes

        Um UUID do documento carregado.

      • Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • frameId

        number

        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 frames são exclusivos em uma guia.

      • Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

        Chrome 74 ou superior

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

      • processId

        number

        O ID do processo que executa o renderizador desse frame.

      • tabId

        number

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

      • timeStamp

        number

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

      • url

        string

  • filtros

    objeto opcional

    • Condições que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos 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 é cancelada. Isso pode acontecer se um erro de rede tiver ocorrido 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 versões mais recentes

        Um UUID do documento carregado.

      • Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • erro

        string

        A descrição do erro.

      • frameId

        number

        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 frames são exclusivos em uma guia.

      • Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

        Chrome 74 ou superior

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

      • processId

        number

        Suspenso desde o Chrome 50

        O processId não está mais definido para esse 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 que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos de 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 desse 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 versões mais recentes

        Um UUID do documento carregado.

      • Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • frameId

        number

        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 frames são exclusivos em uma guia.

      • Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

        Chrome 74 ou superior

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

      • processId

        number

        O ID do processo que executa o renderizador desse 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 que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos 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 foi atualizado. Todos os eventos futuros desse 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 versões mais recentes

        Um UUID do documento carregado.

      • Chrome 106 ou versões mais recentes

        O ciclo de vida do documento.

      • frameId

        number

        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 frames são exclusivos em uma guia.

      • Chrome 106 ou versões mais recentes

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

      • parentDocumentId

        string opcional

        Chrome 106 ou versões mais recentes

        Um UUID do documento pai que possui este frame. Isso não será definido se não houver pai.

      • parentFrameId

        number

        Chrome 74 ou superior

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

      • processId

        number

        O ID do processo que executa o renderizador desse 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 que o URL que está sendo acessado precisa atender. Os "esquemas" e "ports" Os campos 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 uma guia diferente (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 guia antiga.

      • timeStamp

        number

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