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çã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 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
Tipo enumerado
"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 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()
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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recentePromessas 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()
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 recenteO 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 49Os 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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recentePromessas 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
-
função
O parâmetro
callback
tem esta aparência:(details: object) => void
-
objeto
-
Chrome 106 ou mais recente
O ciclo de vida em que o documento está.
-
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.
-
string opcional
Chrome 106 ou mais recenteUm UUID do documento pai que contém o frame. Isso não será definido se não houver um pai.
-
number
O ID do frame pai, ou
-1
, se este for o frame principal. -
number
Descontinuado desde o Chrome 50O 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.
-
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 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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recenteO 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
Uma lista de qualificadores de transição.
-
transitionType
Causa da navegação.
-
url
string
-
-
-
filtros
objeto opcional
-
url
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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recenteO 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
-
url
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
-
função
O parâmetro
callback
tem 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 para o 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 na nova janela.
-
-
-
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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recenteO 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
-
url
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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recenteO ID do frame pai, ou
-1
, se este for o frame principal. -
processId
number
Descontinuado desde o Chrome 50O 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
-
url
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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recenteO 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
Uma lista de qualificadores de transição.
-
transitionType
Causa da navegação.
-
url
string
-
-
-
filtros
objeto opcional
-
url
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 recenteUm UUID do documento carregado.
-
documentLifecycleChrome 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.
-
frameTypeChrome 106 ou mais recente
Tipo de frame em que a navegação ocorreu.
-
parentDocumentId
string opcional
Chrome 106 ou mais recenteUm 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 recenteO 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
Uma lista de qualificadores de transição.
-
transitionType
Causa da navegação.
-
url
string
-
-
-
filtros
objeto opcional
-
url
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.
-
-