Descrição
Use a API chrome.webNavigation para receber notificações sobre o status das solicitações de navegação em andamento.
Permissões
webNavigationTodos 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 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ção | Descriçã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
Enumeração
"client_redirect"
"server_redirect"
"forward_back"
"from_address_bar"
TransitionType
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()
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
callbacktem 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 recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm 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
-1se 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 recenteO 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()
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 recentesO 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 49Os 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
callbacktem 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 recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm 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
-1se 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<object | indefinido>
Chrome 93 ou versão mais recenteO 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
-
função
O parâmetro
callbacktem esta aparência:(details: object) => void
-
objeto
-
Chrome 106 ou versões mais recentes
O ciclo de vida do documento.
-
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.
-
string opcional
Chrome 106 ou versões mais recentesUm UUID do documento pai que possui este frame. Isso não será definido se não houver pai.
-
number
O ID do frame pai ou
-1se esse for o frame principal. -
number
Suspenso desde o Chrome 50O 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.
-
number
O ID da guia em que a navegação está prestes a ocorrer.
-
number
A hora em que o navegador estava prestes a iniciar a navegação, em milissegundos, desde o período.
-
string
-
-
-
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
callbacktem esta aparência:(details: object) => void
-
detalhes
objeto
-
documentId
string
Chrome 106 ou versões mais recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm UUID do documento pai que possui este frame. Isso não será definido se não houver pai.
-
parentFrameId
number
Chrome 74 ou superiorO ID do frame pai ou
-1se 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
Uma lista de qualificadores de transição.
-
transitionType
Causa da navegação.
-
url
string
-
-
-
filtros
objeto opcional
-
url
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
callbacktem esta aparência:(details: object) => void
-
detalhes
objeto
-
documentId
string
Chrome 106 ou versões mais recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm UUID do documento pai que possui este frame. Isso não será definido se não houver pai.
-
parentFrameId
number
Chrome 74 ou superiorO ID do frame pai ou
-1se 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
-
url
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
-
função
O parâmetro
callbacktem esta aparência:(details: object) => void
-
objeto
-
number
O ID do frame com sourceTabId em que a navegação é acionada. O valor 0 indica o frame principal.
-
number
O ID do processo que executa o renderizador do frame de origem.
-
number
O ID da guia em que a navegação é acionada.
-
number
O ID da guia em que o URL é aberto
-
number
A hora em que o navegador estava prestes a criar uma nova visualização, em milissegundos, desde o período.
-
string
O URL que será aberto em uma nova janela.
-
-
-
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
callbacktem esta aparência:(details: object) => void
-
detalhes
objeto
-
documentId
string
Chrome 106 ou versões mais recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm UUID do documento pai que possui este frame. Isso não será definido se não houver pai.
-
parentFrameId
number
Chrome 74 ou superiorO ID do frame pai ou
-1se 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
-
url
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
callbacktem esta aparência:(details: object) => void
-
detalhes
objeto
-
documentId
string
Chrome 106 ou versões mais recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm UUID do documento pai que possui este frame. Isso não será definido se não houver pai.
-
parentFrameId
number
Chrome 74 ou superiorO ID do frame pai ou
-1se esse for o frame principal. -
processId
number
Suspenso desde o Chrome 50O 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
-
url
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
callbacktem esta aparência:(details: object) => void
-
detalhes
objeto
-
documentId
string
Chrome 106 ou versões mais recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm UUID do documento pai que possui este frame. Isso não será definido se não houver pai.
-
parentFrameId
number
Chrome 74 ou superiorO ID do frame pai ou
-1se 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
Uma lista de qualificadores de transição.
-
transitionType
Causa da navegação.
-
url
string
-
-
-
filtros
objeto opcional
-
url
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
callbacktem esta aparência:(details: object) => void
-
detalhes
objeto
-
documentId
string
Chrome 106 ou versões mais recentesUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 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 recentesUm UUID do documento pai que possui este frame. Isso não será definido se não houver pai.
-
parentFrameId
number
Chrome 74 ou superiorO ID do frame pai ou
-1se 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
Uma lista de qualificadores de transição.
-
transitionType
Causa da navegação.
-
url
string
-
-
-
filtros
objeto opcional
-
url
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
callbacktem 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.
-
-