chrome.webNavigation

refresh date: 2026-09-25 robots: noindex

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

Essa permissão aciona um aviso.

Manifesto

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

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

Pedido do evento

Para uma navegação concluída, os eventos são acionados 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, nenhum outro evento é acionado após onErrorOccurred.

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

Se o fragmento de referência de um frame for alterado, um evento onReferenceFragmentUpdated será acionado. Esse evento pode ser acionado 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()), um evento onHistoryStateUpdated será disparado. Esse evento pode ser acionado a qualquer momento após onDOMContentLoaded.

Se uma 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á foi carregado quando a página foi visitada pela primeira vez.

Se uma navegação foi acionada pelo Instant do Chrome ou pelas Páginas Instantâneas, uma página totalmente carregada é trocada pela 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 eventos 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 exibido na IU, 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 às guias reais na interface do Chrome, por exemplo, uma guia que está sendo pré-renderizada. Essas guias não podem ser acessadas pela API tabs, e não é possível solicitar informações sobre elas usando webNavigation.getFrame ou webNavigation.getAllFrames. Depois que uma guia é trocada, um evento onTabReplaced é disparado e ela se torna acessível por essas APIs.

Carimbos de data/hora

É importante observar que algumas peculiaridades técnicas na forma como o SO lida com processos distintos do Chrome podem causar uma distorção do relógio entre o navegador e os processos de extensão. Isso significa que a propriedade timeStamp dos eventos do WebNavigation só tem garantia de ser consistente internamente. Comparar um evento com outro vai fornecer o deslocamento correto entre eles, mas compará-los com o horário atual dentro da extensão (por exemplo, usando (new Date()).getTime()) 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 é 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 é constante durante o ciclo de vida do frame (em várias navegações).

Devido à natureza de vários processos 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 as 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 que algo aconteceu em um documento específico apenas com frameIds. Estamos introduzindo 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/armazenada em cache) porque ele permanece o mesmo.

Tipos e qualificadores de transição

O evento onCommitted da API webNavigation tem uma propriedade transitionType e uma transitionQualifiers. O tipo de transição é o mesmo usado na API History, que descreve como o navegador acessou esse URL específico. Além disso, vários qualificadores de transição podem ser retornados para definir ainda mais 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 de metadados na página aconteceram durante a navegação.
"server_redirect"	Um ou mais redirecionamentos causados por cabeçalhos HTTP enviados do servidor aconteceram 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 do repositório chrome-extension-samples.

Tipos

TransitionQualifier

Chrome 44+

Enumeração

"client_redirect"

"server_redirect"

"forward_back"

"from_address_bar"

TransitionType

Chrome 44+

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

"reload"

"keyword"

"keyword_generated"

Métodos

getAllFrames()

Promessa

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

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

Parâmetros

• detalhes

  objeto

  Informações sobre a guia de onde todos os frames serão recuperados.

  • tabId

    número

    O ID da guia.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (details?: object[]) => void

  • detalhes

    object[] optional

    Uma lista de frames na guia fornecida, nula se o ID da guia especificado for inválido.

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • errorOccurred

      booleano

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

    • frameId

      número

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

    • frameType

      FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

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

    • processId

      número

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

    • url

      string

      O URL associado ao frame.

Retorna

• Promise<object[] | undefined>

  Chrome 93+

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getFrame()

Promessa

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

Recupera informações sobre o frame fornecido. Um frame se refere 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 que você quer recuperar.

  • documentId

    string opcional

    Chrome 106+

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

  • frameId

    número optional

    O ID do frame na guia especificada.

  • processId

    número optional

    Descontinuado desde o Chrome 49

    Agora os frames são identificados de forma exclusiva pelo ID da guia e do frame. O ID de processo não é mais necessário e, portanto, é ignorado.

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

  • tabId

    número optional

    O ID da guia em que o frame está.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (details?: object) => void

  • detalhes

    objeto optional

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

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • errorOccurred

      booleano

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

    • frameType

      FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

      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 algum momento na guia em questão. O fato de um URL estar associado a um determinado frameId não significa que o frame correspondente ainda exista.

Retorna

• Promise<object | undefined>

  Chrome 93+

  As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 é semelhante a:

  (details: object) => void

  • detalhes

    objeto

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • frameId

      número

      0 indica que a navegação ocorre 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.

    • frameType

      extensionTypes.FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

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

    • processId

      número

      Descontinuado desde o Chrome 50

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

      O valor de -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 o período.

    • url

      string

• filtros

  objeto optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

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 é semelhante a:

  (details: object) => void

  • detalhes

    objeto

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • frameId

      número

      0 indica que a navegação ocorre 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.

    • frameType

      extensionTypes.FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

      Chrome 74+

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

    • processId

      número

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

    • tabId

      número

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

    • timeStamp

      número

      O horário 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 optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

onCompleted

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

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

Parâmetros

• callback

  função

  O parâmetro callback é semelhante a:

  (details: object) => void

  • detalhes

    objeto

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • frameId

      número

      0 indica que a navegação ocorre 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.

    • frameType

      extensionTypes.FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

      Chrome 74+

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

    • processId

      número

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

    • tabId

      número

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

    • timeStamp

      número

      O horário em que o documento terminou de carregar, em milissegundos desde o período.

    • url

      string

• filtros

  objeto optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

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 é semelhante a:

  (details: object) => 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 do 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 que será aberto na nova janela.

• filtros

  objeto optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

onDOMContentLoaded

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

Acionado 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 é semelhante a:

  (details: object) => void

  • detalhes

    objeto

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • frameId

      número

      0 indica que a navegação ocorre 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.

    • frameType

      extensionTypes.FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

      Chrome 74+

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

    • processId

      número

      O ID do processo que executa o renderizador para esse 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 optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

onErrorOccurred

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

Acionado quando ocorre um erro e a navegação é cancelada. Isso pode acontecer se houver um erro de rede ou se o usuário cancelar a navegação.

Parâmetros

• callback

  função

  O parâmetro callback é semelhante a:

  (details: object) => void

  • detalhes

    objeto

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+

      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 ocorre 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.

    • frameType

      extensionTypes.FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

      Chrome 74+

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

    • processId

      número

      Descontinuado desde o Chrome 50

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

      O valor de -1.

    • tabId

      número

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

    • timeStamp

      número

      O horário em que o erro ocorreu, em milissegundos desde o período.

    • url

      string

• filtros

  objeto optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

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 é semelhante a:

  (details: object) => void

  • detalhes

    objeto

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • frameId

      número

      0 indica que a navegação ocorre 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.

    • frameType

      extensionTypes.FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

      Chrome 74+

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

    • processId

      número

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

    • tabId

      número

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

    • timeStamp

      número

      O horário 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 optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

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 é semelhante a:

  (details: object) => void

  • detalhes

    objeto

    • documentId

      string

      Chrome 106+

      Um UUID do documento carregado.

    • documentLifecycle

      extensionTypes.DocumentLifecycle

      Chrome 106+

      O ciclo de vida em que o documento está.

    • frameId

      número

      0 indica que a navegação ocorre 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.

    • frameType

      extensionTypes.FrameType

      Chrome 106+

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

    • parentDocumentId

      string opcional

      Chrome 106+

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

    • parentFrameId

      número

      Chrome 74+

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

    • processId

      número

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

    • tabId

      número

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

    • timeStamp

      número

      O horário 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 optional

  • url

    events.UrlFilter[]

    Condições que o URL acessado precisa atender.

onTabReplaced

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

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

Parâmetros

• callback

  função

  O parâmetro callback é semelhante a:

  (details: object) => 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.