| -api-id | -api-type |
|---|---|
T:Windows.UI.Xaml.Controls.Page |
winrt class |
Represents content that a Frame control can navigate to.
<Page .../>
-or-
<Page ...>
singleRootElement
</Page>The Page class encapsulates content that the Frame control can navigate to. You will generally create your own page types that derive from the Page class, and use Page (or a custom type) as the root element for the XAML-declared content.
Page is a UserControl, therefore you can declare a single XAML object element as Content for the Page. Most pages contain more than one UI element in total. You typically use a panel or items control as the immediate child of a Page, so that you can have the page contain and compose multiple elements of a UI.
You can also specify app bars, with the TopAppBar and BottomAppBar properties. You must use property element syntax for these properties to contain the AppBar values in XAML.
You can create new pages using the Add | New Item menu option for your project in Microsoft Visual Studio. These all create XAML files where the root is a Page class, and the code-behind class derives from Page. Some page item templates add navigation support and additional features. For more info on the Microsoft Visual Studio item templates, see C#, VB, and C++ item templates for .
Create as many pages as you need to present the content in your app, and then navigate to those pages by calling the Frame.Navigate method and passing in a type reference for the page to navigate to. By type reference, we mean an instance of a class that identifies a type in the type system, for the language you are using. For Microsoft .NET that type is System.Type, and you can get a System.Type reference from a page class' name by using the operators typeof (C#) or GetType (Visual Basic). For Visual C++ component extensions (C++/CX), use TypeName. Initialize a TypeName by using the typeid of a class. typeid is a component extension that can be called for any runtime class.
Through Frame.Navigate, you can also pass in a parameter object to initialize the page to a particular state. The parameter object is loosely typed but serialization of navigation history only works for basic types (see Remarks in Frame.Navigate(Type, Object)). Pages that are navigated to as part of an activation generally pass data from the activation. Other navigation scenarios such as search result pages also have expectations of what info will be contained in the parameter.
By default, each navigation creates a new instance of the specific Page (or subclass) requested, and disposes the previous page instance. This happens even when navigating back to a previously visited page or when the new page type is the same as the previous page type. Apps that involve frequent navigation to the same pages can cache and reuse the page instances to make navigation more efficient. To do this, set the Frame.CacheSize property to specify how many pages to cache. For each page type that you want to cache, you must also set the NavigationCacheMode property to either Enabled or Required. Pages with a Required cache mode are cached regardless of the CacheSize value, and do not count against the CacheSize total.
You can override the page OnNavigatedTo, OnNavigatingFrom, and OnNavigatedFrom methods to perform tasks such as initializing and saving the page state. OnNavigatingFrom can be used to cancel a navigation by setting a Cancel property in the event data from your handler.
The following code example shows an abridged version (except for the C++/WinRT version, which lists the full function) of the OnLaunched method override generated for the Blank App template in Visual Studio. This code shows how the content of the app window is set to a new Frame, which is then navigated to the default initial Page.
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
Frame rootFrame = Window.Current.Content as Frame;
if (rootFrame == null)
{
// Create a Frame to act as the navigation context and navigate to the first page
rootFrame = new Frame();
// Place the frame in the current Window
Window.Current.Content = rootFrame;
}
if (rootFrame.Content == null)
{
// When the navigation stack isn't restored navigate to the first page,
// configuring the new page by passing required information as a navigation
// parameter
rootFrame.Navigate(typeof(MainPage), e.Arguments);
}
// Ensure the current window is active
Window.Current.Activate();
} Protected Overrides Sub OnLaunched(e As Windows.ApplicationModel.Activation.LaunchActivatedEventArgs)
Dim rootFrame As Frame = TryCast(Window.Current.Content, Frame)
If rootFrame Is Nothing Then
' Create a Frame to act as the navigation context and navigate to the first page
rootFrame = New Frame()
' Place the frame in the current Window
Window.Current.Content = rootFrame
End If
If rootFrame.Content Is Nothing Then
' When the navigation stack isn't restored navigate to the first page,
' configuring the new page by passing required information as a navigation
' parameter
rootFrame.Navigate(GetType(MainPage), e.Arguments)
End If
' Ensure the current window is active
Window.Current.Activate()
End Subvoid App::OnLaunched(LaunchActivatedEventArgs const& e)
{
Frame rootFrame{ nullptr };
auto content = Window::Current().Content();
if (content)
{
rootFrame = content.try_as<Frame>();
}
// Do not repeat app initialization when the Window already has content,
// just ensure that the window is active
if (rootFrame == nullptr)
{
// Create a Frame to act as the navigation context and associate it with
// a SuspensionManager key
rootFrame = Frame();
rootFrame.NavigationFailed({ this, &App::OnNavigationFailed });
if (e.PreviousExecutionState() == ApplicationExecutionState::Terminated)
{
// Restore the saved session state only when appropriate, scheduling the
// final launch steps after the restore is complete
}
if (e.PrelaunchActivated() == false)
{
if (rootFrame.Content() == nullptr)
{
// When the navigation stack isn't restored navigate to the first page,
// configuring the new page by passing required information as a navigation
// parameter
rootFrame.Navigate(xaml_typename<BlankApp1::MainPage>(), box_value(e.Arguments()));
}
// Place the frame in the current Window
Window::Current().Content(rootFrame);
// Ensure the current window is active
Window::Current().Activate();
}
}
else
{
if (e.PrelaunchActivated() == false)
{
if (rootFrame.Content() == nullptr)
{
// When the navigation stack isn't restored navigate to the first page,
// configuring the new page by passing required information as a navigation
// parameter
rootFrame.Navigate(xaml_typename<BlankApp1::MainPage>(), box_value(e.Arguments()));
}
// Ensure the current window is active
Window::Current().Activate();
}
}
}
void App::OnLaunched(Windows::ApplicationModel::Activation::LaunchActivatedEventArgs^ e)
{
auto rootFrame = dynamic_cast<Frame^>(Window::Current->Content);
if (rootFrame == nullptr)
{
rootFrame = ref new Frame();
if (rootFrame->Content == nullptr)
{
// When the navigation stack isn't restored navigate to the first page,
// configuring the new page by passing required information as a navigation
// parameter
rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments);
}
// Place the frame in the current Window
Window::Current->Content = rootFrame;
// Ensure the current window is active
Window::Current->Activate();
}
//else case omitted
}
For example code that adds an AppBar to a page, see Quickstart: adding app bars or How to share an app bar across pages. For example code that uses NavigationCacheMode, see Navigation.
Frame, UserControl, Quickstart: adding app bars, Navigation design basics overview