Eventos de navegação para aplicações WebView2
Quando o utilizador da sua aplicação WebView2 acede a uma página Web, URL ou caminho de ficheiro diferente, trata-se de uma navegação. Cada navegação aciona uma sequência de eventos relacionados com a navegação. A parte nativa da sua aplicação WebView2 escuta estes eventos de navegação e processa-os.
Os eventos de navegação são executados quando ocorrem ações assíncronas específicas ao conteúdo apresentado numa instância do WebView2. Por exemplo, quando um utilizador do WebView2 navega para um novo site, o conteúdo nativo escuta a alteração ao escutar o NavigationStarting evento. Quando a ação de navegação for concluída, NavigationCompleted é executada.
Plataformas suportadas: Win32, Windows Forms, WinUI, WPF.
Sequência padrão de eventos
Segue-se a sequência normal de eventos que são acionados durante cada passo de uma navegação:
| Sequência | Evento | Descrição | Descrição geral da Referência da API |
|---|---|---|---|
| 1 | NavigationStarting |
O WebView2 começa a navegar e a navegação resulta num pedido de rede. O anfitrião pode não permitir o pedido durante o evento. | Bloquear navegação indesejada |
| 2 | SourceChanged |
A origem do WebView2 muda para um novo URL. O evento pode resultar de uma ação de navegação que não causa um pedido de rede, como uma navegação fragmentada . | 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 um pedido de Autenticação HTTP Básica. Veja Autenticação básica para aplicações WebView2. | Autenticação |
| 6 | DOMContentLoaded |
O WebView2 termina a análise do conteúdo do DOM, mas ainda não terminou de carregar todas as imagens, scripts 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 respetivo eventArgs objeto.
Controle os eventos de navegação para cada novo documento com 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 muda sempre que uma navegação bem-sucedida para um novo documento é concluída.
Os eventos de navegação com IDs de Navegação diferentes podem sobrepor-se. Por exemplo, quando inicia um evento de navegação, tem de aguardar pelo evento relacionado NavigationStarting . O NavigationStarting evento é identificado pela NavigationId propriedade no NavigationStartingEventArgs objeto . Se, em seguida, 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 restantes eventos de navegação adequados para a segunda navegação.
Em casos de erro, pode ou não haver um ContentLoading evento, dependendo se a navegação continua para uma página de erro.
Se ocorrer um redirecionamento HTTP, existem vários NavigationStarting eventos numa linha, em que os argumentos de eventos posteriores têm a IsRedirect propriedade definida; no entanto, o ID de Navegação permanece o mesmo.
Os 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 o ID de Navegação seja alterado.
Navegação em frames
Para monitorizar ou cancelar eventos de navegação dentro de frames numa instância do WebView2, utilize as APIs e eventos relacionados com frames equivalentes. Consulte Utilizar frames em aplicações WebView2.
Código de exemplo de navegação
Por exemplo, código que mostra como lidar com eventos de navegação, veja:
- Saiba mais sobre os eventos de navegação em Introdução ao WebView2 em aplicações WinUI 2 (UWP), sem código de exemplo no artigo; veja os artigos de outras arquiteturas.
- Passo 5 – Eventos de navegação em Introdução ao WebView2 em aplicações WinUI 3 (Windows App SDK).
- Passo 7 – Eventos de navegação em Introdução ao WebView2 em aplicações WPF.
- Passo 8 – Eventos de navegação em Introdução ao WebView2 em aplicações WinForms.
- Passo 13 – Eventos de navegação em Introdução ao WebView2 em aplicações Win32.
As aplicações de exemplo WebView2 também demonstram o processamento de eventos de navegação.
Confira também
- Navegue para páginas e faça a gestão de conteúdos carregados na Descrição geral das funcionalidades e APIs do WebView2
- Autenticação básica para aplicações WebView2
- Introdução ao WebView2
- Repositório WebView2Samples - um exemplo abrangente de capacidades do WebView2.
- Referência da API webView2