Eventos de navegação para aplicativos WebView2
Quando o usuário do aplicativo WebView2 for para uma página da Web, URL ou caminho de arquivo diferente, essa é uma navegação. Cada navegação dispara uma sequência de eventos relacionados à navegação. A parte nativa do aplicativo WebView2 escuta esses eventos de navegação e os manipula.
Os eventos de navegação são executados quando ocorrem ações assíncronas específicas para o conteúdo exibido em uma instância do WebView2. Por exemplo, quando um usuário do WebView2 navega até um novo site, o conteúdo nativo escuta a alteração ouvindo o NavigationStarting evento. Quando a ação de navegação for concluída, NavigationCompleted será executada.
Plataformas com suporte: Win32, Windows Forms, WinUI, WPF.
Sequência padrão de eventos
A seguir está a sequência normal de eventos que são disparados durante cada etapa de uma navegação:
| Sequência | Evento | Descrição | Visão geral da Referência de API |
|---|---|---|---|
| 1 | NavigationStarting |
O WebView2 começa a navegar e a navegação resulta em uma solicitação de rede. O host pode não permitir a solicitação durante o evento. | Bloquear 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 inicia o carregamento de 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 conclui a análise do conteúdo do DOM, mas ainda não terminou de carregar todas as imagens, script e outros conteúdos na página. | Eventos de navegação |
| 7 | NavigationCompleted |
O WebView2 conclui o carregamento de conteúdo na nova página. | Eventos de navegação |
IDs de navegação
O diagrama acima mostra eventos de navegação que têm a mesma NavigationId propriedade no objeto respectivo eventArgs .
Acompanhe os eventos de navegação para cada novo documento usando a NavigationId propriedade do objeto de cada evento de eventArgs 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 com IDs de navegação diferentes podem se sobrepor. Por exemplo, ao iniciar um evento de navegação, você 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:
- O
NavigationStartingevento para a primeira navegação. - O
NavigationStartingevento para a segunda navegação. - O
NavigationCompletedevento para a primeira navegação. - Todos os outros 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 continuar para uma página de erro.
Se ocorrer um redirecionamento HTTP, haverá vários NavigationStarting eventos em uma linha, em que argumentos de evento posteriores têm o IsRedirect conjunto de propriedades; no entanto, a ID de Navegação permanece a mesma.
Eventos de navegação do mesmo documento, como navegar até um fragmento no mesmo documento, não fazem com que um NavigationStarting evento seja disparado e não faça com que a ID de Navegação seja alterada.
Navegação em quadros
Para monitorar ou cancelar eventos de navegação dentro de quadros em uma instância do WebView2, use as APIs e eventos relacionados a quadros equivalentes. Consulte Usar quadros em aplicativos WebView2.
Código de exemplo de navegação
Por exemplo, código mostrando como lidar com eventos de navegação, confira:
- Saiba mais sobre eventos de navegação em Introdução ao WebView2 em aplicativos WinUI 2 (UWP) – nenhum código de exemplo no artigo; consulte artigos de outras estruturas.
- Etapa 6 – Eventos de navegação em Introdução ao WebView2 em aplicativos WinUI 3 (SDK do Aplicativo Windows).
- Etapa 8 – Eventos de navegação em Introdução ao WebView2 em aplicativos WPF.
- Etapa 8 – Eventos de navegação em Introdução ao WebView2 em aplicativos WinForms.
- Etapa 14 – Eventos de navegação em Introdução ao WebView2 em aplicativos Win32.
Os aplicativos de exemplo do WebView2 também demonstram o tratamento de eventos de navegação.
Confira também
- Navegue até páginas e gerencie conteúdo carregado em Visão geral de recursos e APIs do WebView2
- Autenticação básica para aplicativos WebView2
- Introdução ao WebView2
- Repositório WebView2Samples – um exemplo abrangente de recursos do WebView2.
- Referência de API do WebView2