doc/articles/features/native-frame-nav.md
This article discusses the particularities of the native Frame navigation in detail.
It is recommended to be familiar with the concept of navigation in WinUI, here are some good starting points:
On Android and iOS, there is the option to enable native frame navigation. Enabling this feature replaces the default styles and templates of the controls below:
Microsoft.UI.Xaml.Controls.Frame<superscript>*</superscript>Microsoft.UI.Xaml.Controls.CommandBarMicrosoft.UI.Xaml.Controls.AppBarButtonThis feature can be enabled by calling the method below, typically in the constructor of your App class in App.cs or App.xaml.cs:
#if __IOS__ || __ANDROID__
Uno.UI.FeatureConfiguration.Style.ConfigureNativeFrameNavigation();
#endif
[!NOTE] It is recommended to enable this feature in order to provide a more native user experience.
In essence, by enabling this, a custom renderer will be used as the control template. This renderer injects the native control into the app, and maps dependency properties (colors, content/icon, ...) and events (clicked), between the WinUI controls and the native ones:
| WinUI Control | Native Android Control | Native iOS Control |
|---|---|---|
CommandBar | android.widget.Toolbar | UIKit.UINavigationBar |
AppBarButton | android.view.MenuItem | UIKit.UIBarButtonItem |
As such, you can have the look and feel of the native control, including features like native swipe to go back on iOS, while programming against the WinUI API. However, you are no longer able to customize the control template.
The Frame also uses a custom presenter for its control template.
On iOS, this presenter creates a UINavigationController, and keeps its states in sync with its Frame. It also creates a UIViewController for each Page that gets navigated.
On iOS and Android, it also manages the state of the back button on the CommandBar, if it is present on a Page.
There is a FrameNavigationHelper that is in place to expose useful properties and methods related to Frame-based navigation logic. It contains the following helper methods:
| Method | Return Type | Description |
|---|---|---|
GetCurrentEntry(Frame) | PageStackEntry | Returns the PageStackEntry for the currently displayed Page within the given frame. |
GetInstance(PageStackEntry) | Page | Returns the actual Page instance of the given entry. |
EnsurePageInitialized(Frame, PageStackEntry) | Page | Retrieves the current Page instance of the given PageStackEntry. If no instance exists, the Page will be created and properly initialized to the provided Frame. |
CreateNavigationEventArgs(...) | NavigationEventArgs | Creates a new instance of NavigationEventArgs. |
SystemNavigationManager.BackRequested. It's the responsibility of the application's navigation controller to eventually call Frame.GoBack().UINavigationController (which is part of the native Frame implementation). The Frame will raise the Navigated event, and its state will automatically be updated to reflect the navigation. The navigation can't be intercepted or canceled.Uno.UI.FeatureConfiguration.Page.IsPoolingEnabled can be set to enable reuse of Page instances. Enabling this allows the pages in the forward stack to be recycled when stack is modified, which can improve performance of Frame navigation.Uno.UI.FeatureConfiguration.NativeFramePresenter.AndroidUnloadInactivePages = true.SystemNavigationManager.AppViewBackButtonVisibility needs to be set to Visible to intercept the browser back navigation. The intercepted event is forwarded to SystemNavigationManager.BackRequested. It's the responsibility of the application's navigation controller to eventually call Frame.GoBack().