Eventos de navegação para aplicativos WebView2

Quando o usuário do seu aplicativo WebView2 vai para uma página da Web, URL ou caminho de arquivo diferente, isso é uma navegação. Cada navegação dispara uma sequência de eventos relacionados à navegação. A parte nativa do seu aplicativo WebView2 escuta esses eventos de navegação e os manipula.

Os eventos de navegação são executados quando ações assíncronas específicas ocorrem no conteúdo exibido em uma instância do WebView2. Por exemplo, quando um usuário do WebView2 navega para um novo site, o conteúdo nativo ouve a alteração ouvindo o NavigationStarting evento. Quando a ação de navegação for concluída, NavigationCompleted executada.

Plataformas suportadas: Win32, Windows Forms, WinUI, WPF.

Standard sequence of events

A seguir está a sequência normal de eventos que são acionados durante cada etapa de uma navegação:

Eventos de navegação do WebView2

Sequência Evento Descrição Visão geral de referência de API
1 NavigationStarting O WebView2 começa a navegar e a navegação resulta em uma solicitação de rede. O anfitrião pode não permitir a solicitação durante o evento. Bloquear a navegação indesejada
2 SourceChanged A origem do WebView2 muda para uma nova URL. O evento pode resultar de uma ação de navegação que não causa uma solicitação de rede, como uma navegação de fragmento . Histórico de navegação
3 ContentLoading O WebView2 começa a carregar conteúdo para a nova página. Eventos de navegação
4 HistoryChanged A navegação faz com que o histórico do WebView2 seja atualizado. Histórico de navegação
5 BasicAuthenticationRequested Gerado quando o WebView encontra uma solicitação de autenticação HTTP básica. Consulte Autenticação básica para aplicativos WebView2. Autenticação
6 DOMContentLoaded O WebView2 termina de analisar o conteúdo do DOM, mas não terminou de carregar todas as imagens, scripts e outros conteúdos da página. Eventos de navegação
7 NavigationCompleted O WebView2 conclui o carregamento do conteúdo na nova página. Eventos de navegação

O diagrama acima mostra eventos de navegação que têm a mesma NavigationId propriedade no respectivo eventArgs objeto.

Rastreie eventos de navegação para cada novo documento usando a NavigationId propriedade do objeto de eventArgs cada evento de navegação. Cada navegação envolve uma sequência de eventos de navegação. O NavigationId valor é alterado sempre que uma navegação bem-sucedida para um novo documento é concluída.

Eventos de navegação que têm IDs de navegação diferentes podem se sobrepor. Por exemplo, quando você inicia um evento de navegação, deve aguardar o evento relacionado NavigationStarting . O NavigationStarting evento é identificado pela NavigationId propriedade no NavigationStartingEventArgs objeto. Se você iniciar outra navegação, verá a seguinte sequência:

  1. O NavigationStarting evento para a primeira navegação.
  2. O NavigationStarting evento para a segunda navegação.
  3. O NavigationCompleted evento para a primeira navegação.
  4. Todo o resto dos eventos de navegação apropriados para a segunda navegação.

Em casos de erro, pode ou não haver um ContentLoading evento, dependendo se a navegação é continuada para uma página de erro.

Se ocorrer um redirecionamento HTTP, haverá vários NavigationStarting eventos seguidos, em que os argumentos de evento posteriores têm a IsRedirect propriedade definida; no entanto, a ID de navegação permanecerá a mesma.

Eventos de navegação no mesmo documento, como navegar para um fragmento no mesmo documento, não fazem com que um NavigationStarting evento seja acionado e não fazem com que a ID de navegação seja alterada.

Para monitorar ou cancelar eventos de navegação dentro de quadros em uma instância WebView2, use as APIs e eventos relacionados a quadros equivalentes. Consulte Usando quadros em aplicativos WebView2.

Para obter um código de exemplo mostrando como lidar com eventos de navegação, consulte:

Os aplicativos de exemplo WebView2 também demonstram como lidar com eventos de navegação.

Confira também