Skip to content

navigation-events.md

Latest commit

 

History

History
80 lines (61 loc) · 4.86 KB

navigation-events.md

File metadata and controls

80 lines (61 loc) · 4.86 KB
title Navigation events for WebView2 apps
description Navigation events for WebView2: NavigationStarting, SourceChanged, ContentLoading, HistoryChanged, DOMContentLoaded, and NavigationCompleted.
author MSEdgeTeam
ms.author msedgedevrel
ms.topic conceptual
ms.prod microsoft-edge
ms.technology webview
ms.date 10/28/2021

Navigation events for WebView2 apps

Supported platforms: Win32, Windows Forms, WinUi, WPF.

This article covers navigation events for WebView2 apps. Navigation events run when specific asynchronous actions occur to the content that's displayed in a WebView2 instance. For example, when a WebView2 user navigates to a new website, the native content listens for the change by listening for the NavigationStarting event. When the navigation action completes, NavigationCompleted runs.

For an example of navigation events, see Get started with WebView2.

The normal sequence of navigation events is:

  1. NavigationStarting
  2. SourceChanged
  3. ContentLoading
  4. HistoryChanged
  5. BasicAuthenticationRequested
  6. DOMContentLoaded
  7. NavigationCompleted

The following events describe the state of WebView2 during each navigation action:

WebView2 Navigation Events

Sequence Event name Details
1 NavigationStarting WebView2 starts to navigate and the navigation results in a network request. The host may disallow the request during the event.
2 SourceChanged The source of WebView2 changes to a new URL. The event may result from a navigation action that doesn't cause a network request such as a fragment navigation.
3 ContentLoading WebView2 starts loading content for the new page.
4 HistoryChanged The navigation causes the history of WebView2 to update.
5 DOMContentLoaded WebView2 finishes parsing the DOM content but hasn't finished loading all images, script, and other content on the page.
6 NavigationCompleted WebView2 completes loading content on the new page.

The above figure shows navigation events that have the same NavigationId property on the respective event argument.

Track navigation events to each new document by using the navigation ID (which is provided in the NavigationId event). The NavigationId event of WebView2 changes every time a successful navigation to a new document completes.

Navigation events with different instances of NavigationId event may overlap. For instance, when you start a navigation event, you must wait for the related NavigationStarting event. If you then start another navigation, you'll see the following sequence:

  1. The NavigationStarting event for the first navigation.
  2. The NavigationStarting event for the second navigation.
  3. The NavigationCompleted event for the first navigation.
  4. All the rest of the appropriate navigation events for the second navigation.

In error cases, there may or may not be a ContentLoading event, depending on whether the navigation is continued to an error page.

If an HTTP redirect occurs, there are multiple NavigationStarting events in a row, where later event arguments have the IsRedirect property set; however, the NavigationId event remains the same.

Same-document navigation events, such as navigating to a fragment in the same document, don't cause a NavigationStarting event, and don't increment the NavigationId event.

To monitor or cancel navigation events inside subframes in a WebView2 instance, use the FrameNavigationStarting and FrameNavigationCompleted events. Those events act like the equivalent non-frame, counterpart events.

See also