Migración de la funcionalidad basada en ventanas
Este tema contiene instrucciones relacionadas con la administración de ventanas, incluida la migración desde ApplicationView/CoreWindow de UWP o AppWindow al SDK de aplicaciones de Windows Microsoft.UI.Windowing.AppWindow.
API importantes
- Microsoft.UI.Windowing.AppWindow
- Propiedad Windows.UI.Core.CoreWindow.Dispatcher
- Propiedad Microsoft.UI.Window.DispatcherQueue
Resumen de las diferencias de api o características
El SDK de Aplicaciones para Windows proporciona una clase Microsoft.UI.Windowing.AppWindow basada en el modelo HWND de Win32. Esa clase AppWindow es la versión del SDK de Aplicaciones para Windows de ApplicationView/CoreWindow y AppWindow de UWP.
Para aprovechar las api de ventanas de SDK de Aplicaciones para Windows significa que migrarás el código de UWP para usar el modelo Win32. Para obtener más información sobre la SDK de Aplicaciones para Windows AppWindow, consulta Administrar ventanas de aplicaciones.
Sugerencia
El tema Administrar ventanas de aplicaciones contiene un ejemplo de código que muestra cómo recuperar una instancia de AppWindow desde una ventana de WinUI 3. En la aplicación WinUI 3, use ese patrón de código para que pueda llamar a las API de AppWindow mencionadas en el resto de este tema.
Tipos de ventana en UWP frente a los SDK de Aplicaciones para Windows
En una aplicación para UWP, puedes hospedar contenido de ventana mediante ApplicationView/CoreWindow o AppWindow. El trabajo implicado en la migración de ese código a la SDK de Aplicaciones para Windows depende de cuál de esos dos modelos de ventana usa la aplicación para UWP. Si está familiarizado con Windows.UI.WindowManagement.AppWindow de UWP, es posible que vea similitudes entre eso y Microsoft.UI.Windowing.AppWindow.
Tipos de ventana para UWP
- Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
- Windows.UI.WindowManagement.AppWindow. AppWindow consolida el subproceso de interfaz de usuario y la ventana que usa la aplicación para mostrar el contenido. Las aplicaciones para UWP que usan AppWindow tendrán menos trabajo que las aplicaciones ApplicationView/CoreWindow para migrar a la SDK de Aplicaciones para Windows AppWindow.
SDK de Aplicaciones para Windows tipo de ventana
- Microsoft.UI.Windowing.AppWindow es la abstracción de alto nivel de un contenedor administrado por el sistema del contenido de una aplicación.
Tenga en cuenta que las diferencias en los modelos de ventanas entre UWP y Win32 significan que no hay una asignación directa de 1:1 entre la superficie de la API de UWP y la superficie de api de SDK de Aplicaciones para Windows. Incluso para los nombres de clase y miembros que se transfieren desde UWP (reflejados en las tablas de asignación de este tema), el comportamiento también puede diferir.
Pantallas de presentación
A diferencia de las aplicaciones para UWP, las aplicaciones Win32 no muestran de forma predeterminada una pantalla de presentación en el inicio. Las aplicaciones para UWP que dependen de esta característica para su experiencia de inicio pueden optar por implementar una transición personalizada a su primera ventana de la aplicación.
Crear, mostrar, cerrar y destruir una ventana
La duración de microsoft.UI.Windowing.AppWindow es la misma que para un HWND; lo que significa que el objeto AppWindow está disponible inmediatamente después de crear la ventana y se destruye cuando se cierra la ventana.
Crear y mostrar
AppWindow.Create crea una ventana de aplicación con la configuración predeterminada. Crear y mostrar una ventana solo es necesario para escenarios en los que no esté trabajando con un marco de interfaz de usuario. Si va a migrar la aplicación para UWP a un marco de interfaz de usuario compatible con Win32, puede seguir migrando el objeto AppWindow desde una ventana ya creada mediante los métodos de interoperabilidad de ventanas.
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| CoreApplication.CreateNewView o CoreWindow.GetForCurrentThread |
AppWindow.TryCreateAsync | AppWindow.Create |
| CoreWindow.Activate | AppWindow.TryShowAsync | AppWindow.Show |
Cerrar
En UWP, ApplicationView.TryConsolidateAsync es el equivalente mediante programación del usuario que inicia un gesto de cierre. Este concepto de consolidación (en el modelo de ventanas ApplicationView/CoreWindow de UWP) no existe en Win32. Win32 no requiere que las ventanas existan en subprocesos independientes. La replicación del modelo de ventanas ApplicationView/CoreWindow de UWP requeriría que el desarrollador cree un subproceso y cree una nueva ventana allí. En el modelo Win32, el comportamiento predeterminado del sistema es Cerrar>ocultar>destruir.
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| ApplicationView.TryConsolidateAsync | AppWindow.CloseAsync | AppWindow.Destroy |
Personalización básica de la ventana
A medida que migre de UWP a la SDK de Aplicaciones para Windows, puede esperar la misma experiencia desde la versión predeterminada de AppWindow. Pero si es necesario, puede cambiar el valor predeterminado Microsoft.UI.Windowing.AppWindow para experiencias de ventana personalizadas. Consulta Microsoft.UI.Windowing.AppWindow para obtener más información sobre cómo personalizar las ventanas.
Cambio de tamaño de una ventana
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| ApplicationView.TryResizeView | AppWindow.RequestSize | AppWindow.Resize |
CoreWindow.Bounds (normalmente aparece en C# como CoreWindow.GetForCurrentThread.Bounds) |
AppWindowPlacement.Size | AppWindow.Size |
Posicionamiento de una ventana
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| No es posible | AppWindow.GetPlacement | AppWindow.Position |
| No es posible | Appwindow.RequestMoveXxx | AppWindow.Move |
Título de la ventana
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| ApplicationView.Title | AppWindow.Title | AppWindow.Title |
Superposición compacta y pantalla completa
Las aplicaciones que entran en superposición compacta o en pantalla completa deben aprovechar las ventajas de la SDK de Aplicaciones para Windows AppWindowPresenter. Si estás familiarizado con la Aplicación para UWPWindow, es posible que ya estés familiarizado con el concepto de moderadores.
No hay una asignación 1:1 de funcionalidad y comportamiento de moderadores de ventanas de aplicaciones para UWP a SDK de Aplicaciones para Windows moderadores de ventanas de la aplicación. Si tienes una aplicación ApplicationView/CoreWindow para UWP, puedes tener una superposición compacta (imagen en imagen) o experiencias de ventanas de pantalla completa en tu aplicación, pero es posible que el concepto de moderadores sea nuevo para ti. Para obtener más información sobre los presentadores de ventanas de la aplicación, consulte Presentadores. De forma predeterminada, un moderador superpuesto se aplica a una instancia de AppWindow en el momento de la creación. CompactOverlay y FullScreen son los únicos presentadores disponibles, aparte de los predeterminados.
Superposición compacta
Si usaste ApplicationViewMode o AppWindowPresentionKind de UWP para presentar una ventana de superposición compacta, debes usar la superposición compacta AppWindowPresenterKind. Microsoft.UI.Windowing.CompactOverlayPresenter solo admite tres tamaños fijos de ventana con una relación de aspecto de 16:9 y el usuario no puede cambiar el tamaño. En lugar de ApplicationViewMode.TryEnterViewModeAsync o AppWindowPresenterKind.RequestPresentation, debe usar AppWindow.SetPresenter para cambiar la presentación de AppWindow.
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| ApplicationViewMode.CompactOverlay | AppWindowPresentationKind.CompactOverlay | AppWindowPresenterKind.CompactOverlay |
| ApplicationView.TryEnterViewModeAsync con ApplicationViewMode.CompactOverlay | AppWindowPresenter.RequestPresentation con AppWindowPresenterKind.CompactOverlay | AppWindow.SetPresenter con AppWindowPresenterKind.CompactOverlay |
Pantalla completa
Si usaste las clases ApplicationViewWindowingMode o AppWindowPresentionKind de UWP para presentar una ventana de pantalla completa, debes usar appWindowPresenterKind de pantalla completa. El SDK de Aplicaciones para Windows solo admite la experiencia de pantalla completa más restrictiva (es decir, cuando FullScreen es IsExclusive). Para ApplicationView/CoreWindow, puedes usar ApplicationView.ExitFullScreenMode para sacar la aplicación de pantalla completa. Al usar moderadores, puede quitar una aplicación de pantalla completa estableciendo el moderador de nuevo en superpuesto o predeterminado mediante AppWindow.SetPresenter.
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| ApplicationViewWindowingMode.FullScreen | AppWindowPresentationKind.FullScreen | AppWindowPresenterKind.FullScreen |
| ApplicationView.TryEnterFullScreenMode | AppWindowPresenter.RequestPresentation con AppWindowPresenterKind.FullScreen | AppWindow.SetPresenter con AppWindowPresenterKind.FullScreen |
Para obtener más información sobre cómo trabajar con presentadores de ventanas de la aplicación, consulte el ejemplo de la galería de ventanas. Muestra cómo alternar diferentes estados del moderador de la ventana de la aplicación.
Barra de título personalizada
Nota
Actualmente, las API de personalización de la barra de título solo funcionan en Windows 11. Se recomienda comprobar AppWindowTitleBar.IsCustomizationSupported en el código antes de llamar a estas API.
Si la aplicación usa una barra de título predeterminada, no es necesario realizar ningún trabajo de barra de título adicional al migrar a Win32. Si, por otro lado, la aplicación para UWP tiene una barra de título personalizada, es posible volver a crear los siguientes escenarios en la aplicación SDK de Aplicaciones para Windows.
- Personalizar la barra de título dibujada por el sistema
- Barra de título personalizada dibujada por la aplicación
El código que usa las clases ApplicationViewTitleBar, CoreApplicationViewTitleBar y AppWindowTitleBar se migra al uso de la clase SDK de Aplicaciones para Windows Microsoft.UI.Windowing.AppWindowTitleBar.
Personalizar la barra de título dibujada por el sistema
Esta es una tabla de las API de personalización de color.
Nota
Cuando AppWindowTitleBar.ExtendsContentIntoTitleBar es true, la transparencia solo se admite para las siguientes propiedades: AppWindowTitleBar.ButtonBackgroundColor, AppWindowTitleBar.ButtonInactiveBackgroundColor, AppWindowTitleBar.ButtonPressedBackgroundColor, AppWindowTitleBar.ButtonHoverBackgroundColor y AppWindowTitleBar.BackgroundColor (establecido implícitamente).
Estas API de SDK de Aplicaciones para Windows son para personalizar aún más la barra de título dibujada por el sistema, además de la API AppWindow.Title.
- AppWindow.SetIcon. Establece la barra de título y la imagen del icono de la barra de tareas mediante un identificador hIcon o una ruta de acceso de cadena a un recurso o a un archivo.
- AppWindowTitleBar.IconShowOptions. Obtiene o establece un valor que especifica cómo se muestra el icono de ventana en la barra de título. Admite actualmente dos valores: HideIconAndSystemMenu y ShowIconAndSystemMenu.
- AppWindowTitleBar.ResetToDefault. Restablece la barra de título actual a la configuración predeterminada de la ventana.
Barra de título personalizada dibujada por la aplicación (personalización completa)
Si va a migrar a mediante AppWindowTitleBar, se recomienda comprobar AppWindowTitleBar.IsCustomizationSupported en el código antes de llamar a las siguientes API de barra de título personalizadas.
| UWP ApplicationView/CoreWindow | SDK de Aplicaciones para Windows AppWindow |
|---|---|
| CoreApplicationViewTitleBar.ExtendViewIntoTitleBar | AppWindowTitleBar.ExtendsContentIntoTitleBar La plataforma sigue dibujando los botones Minimizar/maximizar/cerrar para usted e informa de la información de oclusión. |
| CoreApplicationViewTitleBar.SystemOverlayLeftInset | AppWindowTitleBar.LeftInset |
| CoreApplicationViewTitleBar.SystemOverlayRightInset | AppWindowTitleBar.RightInset |
| CoreApplicationViewTitleBar.Height | AppWindowTitleBar.Height |
| AppWindowTitleBarOcclusion AppWindowTitleBar.GetTitleBarOcclusions |
Representa las regiones reservadas del sistema de la ventana de la aplicación que oscluirán el contenido de la aplicación si ExtendsContentIntoTitleBar es true. La SDK de Aplicaciones para Windows información de conjunto de la izquierda y derecha de AppWindow, junto con el alto de la barra de título, proporcionan la misma información. AppWindowTitleBar.LeftInset, AppWindowTitleBar.RightInset, AppWindowTitleBar.Height |
Estas API de SDK de Aplicaciones para Windows son para la personalización completa de la barra de título.
- AppWindowTitleBar.SetDragRectangles. Establece las regiones de arrastre de la ventana.
- AppWindowTitleBar.ResetToDefault. Restablece la barra de título actual a la configuración predeterminada de la ventana.
Estas API de UWP AppWindow no tienen ninguna asignación directa de 1:1 a una API de SDK de Aplicaciones para Windows.
- AppWindowTitleBarVisibility. Define constantes que especifican la visibilidad preferida de una clase AppWindowTitleBar.
- AppWindowTitleBar.GetPreferredVisibility. Recupera el modo de visibilidad preferido para la barra de título.
- AppWindowTitleBar.SetPreferredVisibility. Establece el modo de visibilidad preferido para la barra de título.
Para obtener más información sobre cómo trabajar con AppWindowTitleBar, consulte el ejemplo de la galería de ventanas. Muestra cómo crear una barra de título de color personalizada y cómo dibujar una barra de título personalizada.
Control de eventos
Si la aplicación para UWP usa el evento AppWindow.Changed , puedes migrar ese código al evento Microsoft.UI.Windowing.AppWindow.Changed .
Evento de cambio de tamaño
Al migrar el código de control de eventos cambiado de tamaño, debe cambiar al uso de la propiedad SDK de Aplicaciones para Windows AppWindowChangedEventArgs.DidSizeChange. El valor es true si el tamaño de la ventana de la aplicación ha cambiado; de lo contrario, es false.
| UWP ApplicationView/CoreWindow | Aplicación para UWPWindow | SDK para aplicaciones de Windows |
|---|---|---|
| CoreWindow.SizeChanged | AppWindowChangedEventArgs.DidSizeChange | AppWindowChangedEventArgs.DidSizeChange |
MainPage y MainWindow
Al crear un nuevo proyecto de UWP en Visual Studio, la plantilla de proyecto proporciona una clase MainPage . En el caso de la aplicación, es posible que haya cambiado el nombre de esa clase (o haya agregado más páginas y controles de usuario). La plantilla de proyecto también proporciona código de navegación en los métodos de la clase App .
Al crear un nuevo proyecto de SDK de Aplicaciones para Windows en Visual Studio, la plantilla de proyecto proporciona una clase MainWindow (de tipo Microsoft.UI.Xaml.Window), pero no page. Y la plantilla de proyecto no proporciona ningún código de navegación.
Sin embargo, tiene la opción de agregar páginas y controles de usuario al proyecto de SDK de Aplicaciones para Windows. Por ejemplo, podría agregar un nuevo elemento de página al proyecto (Página en blanco de WinUI>(WinUI 3)) y asignarle MainPage.xamlel nombre , o algún otro nombre. Esto agregaría al proyecto una nueva clase de tipo Microsoft.UI.Xaml.Controls.Page. A continuación, para obtener información sobre cómo agregar código de navegación al proyecto, consulte ¿Necesito implementar la navegación de páginas?.
Para SDK de Aplicaciones para Windows aplicaciones que son lo suficientemente sencillas, no necesitas crear páginas ni controles de usuario, y puedes copiar el marcado XAML y el código subyacente en MainWindow. Pero para obtener información sobre las excepciones a ese flujo de trabajo, vea Visual State Manager y Page.Resources.
Cambie CoreWindow.Dispatcher a Window.DispatcherQueue
Algunos casos de uso de la clase Windows.UI.Core.CoreWindow de UWP migran a microsoft.UI.Xaml.Window de la SDK de Aplicaciones para Windows.
Por ejemplo, si usas la propiedad Windows.UI.Core.CoreWindow.Dispatcher en tu aplicación para UWP, la solución no es migrar a la propiedad Microsoft.UI.Xaml.Window.Dispatcher (que siempre devuelve null). En su lugar, migre a la propiedad Microsoft.UI.Xaml.Window.DispatcherQueue , que devuelve microsoft.UI.Dispatching.DispatcherQueue.
Para obtener más información y ejemplos de código, consulta Cambiar Windows.UI.Core.CoreDispatcher a Microsoft.UI.Dispatching.DispatcherQueue.
Temas relacionados
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de