Migração da funcionalidade de janelas

Este tópico contém orientações relacionadas ao gerenciamento de janelas, incluindo a migração do ApplicationView da UWP/CoreWindow ou AppWindow para o SDK do Aplicativo do Windows Microsoft.UI.Windowing.AppWindow .

APIs importantes

• Microsoft.UI.Windowing.AppWindow
• propriedade Windows.UI.Core.CoreWindow.Dispatcher
• propriedade Microsoft.UI.Window.DispatcherQueue

Resumo das diferenças de API e/ou recursos

O Windows App SDK fornece uma classe Microsoft.UI.Windowing.AppWindow que é baseada no modelo HWND do Win32. Essa classe AppWindow é a versão do SDK de Aplicativo do Windows do ApplicationView da UWP/CoreWindow e AppWindow.

Para aproveitar as APIs de janela do SDK de Aplicativos Windows, você migrará seu código UWP para usar o modelo Win32. Para obter mais informações sobre o SDK da App Windows AppWindow, consulte Gerir janelas de apps.

Tipos de janela na UWP versus o SDK do Aplicativo Windows

Em um aplicativo UWP, você pode hospedar o conteúdo da janela usando ApplicationView/CoreWindow ou AppWindow. O trabalho envolvido na migração desse código para o SDK do Aplicativo Windows depende de qual desses dois modelos de janela seu aplicativo UWP usa. Se estiveres familiarizado com o da UWPWindows.UI.WindowManagement.AppWindow, poderás ver semelhanças entre isso e Microsoft.UI.Windowing.AppWindow.

Tipos de janela UWP

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow consolida a sequência da interface do utilizador e a janela que a aplicação usa para exibir conteúdo. Os aplicativos UWP que usam AppWindow terão menos trabalho a fazer do que os aplicativos ApplicationView/CoreWindow para migrar para o SDK do Aplicativo Windows AppWindow.

Tipo de janela do SDK do Aplicativo Windows

• Microsoft.UI.Windowing.AppWindow é a abstração de alto nível de um contêiner gerenciado pelo sistema do conteúdo de um aplicativo.

Lembre-se de que as diferenças nos modelos de janelas entre UWP e Win32 significam que não há um mapeamento 1:1 direto entre a superfície da API UWP e a superfície da API do SDK do Windows App. Mesmo para nomes de classe e membros que transferir da UWP (refletido nas tabelas de mapeamento deste tópico), o comportamento também pode ser diferente.

Ecrãs iniciais

Ao contrário dos aplicativos UWP, os aplicativos Win32 não mostram, por padrão, uma tela inicial na inicialização. Os aplicativos UWP que dependem desse recurso para sua experiência de inicialização podem optar por implementar uma transição personalizada para sua primeira janela de aplicativo.

Criar, mostrar, fechar e destruir uma janela

O tempo de vida de um Microsoft.UI.Windowing.AppWindow é o mesmo de um HWND; o que significa que o objeto AppWindow está disponível imediatamente após a janela ter sido criada e é destruído quando a janela é fechada.

Criar e mostrar

AppWindow.Create cria uma janela de aplicativo com a configuração padrão. Criar e mostrar uma janela só é necessário para cenários em que você não está trabalhando com uma estrutura de interface do usuário. Se você estiver migrando seu aplicativo UWP para uma estrutura de interface do usuário compatível com Win32, ainda poderá acessar seu objeto AppWindow de uma janela já criada usando os métodos de interoperabilidade de janelas.

Fechar

Na UWP, ApplicationView.TryConsolidateAsync é o equivalente programático do usuário que inicia um gesto de fechar. Esse conceito de de consolidação de (no modelo de janelas ApplicationViewCoreWindow da UWP) não existe no Win32. O Win32 não requer que as janelas existam em threads separados. Replicar o ApplicationView da UWP/o modelo de janela CoreWindow exigiria que o desenvolvedor criasse um novo thread e criasse uma nova janela lá. No modelo Win32, o comportamento padrão do sistema é Close>Hide>Destroy.

Personalização básica de janelas

Ao migrar do UWP para o Windows App SDK, pode esperar a mesma experiência da AppWindow padrão . Mas, se necessário, você pode alterar o padrão Microsoft.UI.Windowing.AppWindow para experiências de janela personalizadas. Consulte Microsoft.UI.Windowing.AppWindow para obter mais informações sobre como personalizar suas janelas.

Redimensionar uma janela

Posicionar uma janela

Título da janela

Sobreposição compacta e ecrã inteiro

As aplicações que entram em sobreposição compacta, ou em tela inteira, devem tirar partido do SDK de Aplicativo do Windows AppWindowPresenter. Se você estiver familiarizado com a UWP AppWindow, talvez já esteja familiarizado com o conceito de apresentadores.

Não há um mapeamento 1:1 de funcionalidade e comportamento dos gestores de janelas do aplicativo UWP para os gestores de janelas do SDK de Aplicativos do Windows. Se tiver uma aplicação UWP ApplicationView/CoreWindow, ainda pode ter experiências de sobreposição compacta (picture-in-picture) ou de janelas em ecrã completo na sua aplicação, mas o conceito de apresentadores pode ser novo para si. Para obter mais informações sobre apresentadores de janelas de aplicação, consulte Apresentadores. Por padrão, um apresentador sobreposto é aplicado a um AppWindow no momento da criação. CompactOverlay e FullScreen são os únicos apresentadores disponíveis, além do padrão.

Sobreposição compacta

Se tiver utilizado o ApplicationViewMode da UWP ou o AppWindowPresentationKind para apresentar uma janela de sobreposição compacta, então deve usar a sobreposição compacta AppWindowPresenterKind. O Microsoft.UI.Windowing.CompactOverlayPresenter suporta apenas três tamanhos de janela fixos em uma proporção de 16:9 e não pode ser redimensionado pelo usuário. Em vez de ApplicationViewMode.TryEnterViewModeAsync ou AppWindowPresenterKind.RequestPresentation , você deve usar AppWindow.SetPresenter para alterar a apresentação do AppWindow.

Ecrã inteiro

Se você usou o ApplicationViewWindowingMode da UWP ou classes de AppWindowPresentionKind para apresentar uma janela de tela inteira, use o de tela inteira AppWindowPresenterKind. O SDK da Aplicação Windows suporta apenas a experiência mais restritiva de ecrã completo (ou seja, quando FullScreen é IsExclusive). Para ApplicationView/CoreWindow, pode utilizar o ApplicationView.ExitFullScreenMode para retirar a aplicação do modo de ecrã completo. Ao usar apresentadores, pode-se tirar um aplicativo da tela inteira definindo o apresentador de volta para sobreposição/padrão usando AppWindow.SetPresenter.

Para obter mais detalhes sobre como trabalhar com apresentadores de janelas de aplicativos, consulte o Exemplo de galeria de janelas. Ele demonstra como alternar diferentes estados do apresentador da janela do aplicativo.

Barra de título personalizada

Se seu aplicativo usa uma barra de título padrão, não há trabalho adicional na barra de título necessário quando você migra para o Win32. Se, por outro lado, seu aplicativo UWP tiver uma barra de título personalizada, será possível recriar os seguintes cenários em seu aplicativo SDK de Aplicativo Windows.

1. Personalizar a barra de título desenhada pelo sistema
2. Barra de título personalizada desenhada por aplicativo

O código que usa oUWP ApplicationViewTitleBar, CoreApplicationViewTitleBar e classes AppWindowTitleBar migra para usar o SDK do Windows classe de Microsoft.UI.Windowing.AppWindowTitleBar.

Personalizar a barra de título desenhada pelo sistema

Aqui está uma tabela das APIs de personalização de cores.

Essas APIs do SDK de Aplicativo Windows são para personalização adicional da barra de título desenhada pelo sistema, além da API AppWindow.Title .

• AppWindow.SetIcon. Define a imagem da barra de título e do ícone da barra de tarefas usando um identificador hIcon ou um caminho de cadeia de caracteres para um recurso ou um arquivo.
• AppWindowTitleBar.IconShowOptions. Obtém ou define um valor que especifica como o ícone da janela é exibido na barra de título. Suporta dois valores atualmente: HideIconAndSystemMenu e ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Redefine a barra de título atual de volta para as configurações padrão da janela.

Barra de título personalizada desenhada por aplicativo (personalização completa)

Se você estiver migrando para usar AppWindowTitleBar, recomendamos que marque AppWindowTitleBar.IsCustomizationSupported em seu código antes de chamar as seguintes APIs de barra de título personalizadas.

Essas APIs do SDK de Aplicativo Windows são para personalização completa da barra de título.

• AppWindowTitleBar.SetDragRectangles. Define as regiões de arrasto para a janela.
• AppWindowTitleBar.ResetToDefault. Redefine a barra de título atual de volta para as configurações padrão da janela.

Essas APIs UWP AppWindow não têm mapeamento 1:1 direto para uma API do SDK de Aplicativos do Windows.

• AppWindowTitleBarVisibility. Define constantes que especificam a visibilidade preferida de um AppWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Recupera o modo de visibilidade preferido para a barra de título.
• AppWindowTitleBar.SetPreferredVisibility. Define o modo de visibilidade preferido para a barra de título.

Para obter mais detalhes sobre como trabalhar com AppWindowTitleBar, consulte o Exemplo de galeria de janelas. Ele demonstra como criar uma barra de título de cor personalizada e como desenhar uma barra de título personalizada.

Tratamento de eventos

Se o seu aplicativo UWP usa o evento AppWindow.Changed, pode migrar esse código para o evento Microsoft.UI.Windowing.AppWindow.Changed.

Evento de alteração de tamanho

Ao migrar o código de manipulação de eventos de alteração de tamanho, deve passar a usar a propriedade AppWindowChangedEventArgs.DidSizeChange do Windows App SDK . O valor é true se o tamanho da janela do aplicativo mudou, caso contrário, é false.

MainPage e MainWindow

Quando se cria um novo projeto UWP no Visual Studio, o modelo de projeto fornece uma classe MainPage. Para seu aplicativo, você pode ter renomeado essa classe (e/ou adicionado mais páginas e controles de usuário). O modelo de projeto também fornece código de navegação nos métodos da classe App .

Quando se cria um novo projeto do SDK de Aplicação Windows no Visual Studio, o modelo de projeto fornece uma classe MainWindow (do tipo Microsoft.UI.Xaml.Window), mas não Page. E o modelo de projeto não fornece nenhum código de navegação.

No entanto, você tem a opção de adicionar páginas e controles de usuário ao seu projeto do SDK de aplicativos Windows. Por exemplo, você pode adicionar um novo item de página ao projeto (WinUI>Blank Page (WinUI 3)) e nomeá-lo MainPage.xamlou algum outro nome. Isso adicionaria ao seu projeto uma nova classe de tipo Microsoft.UI.Xaml.Controls.Page. Em seguida, para obter informações sobre como adicionar código de navegação ao projeto, consulte Preciso implementar a navegação na página?.

Para aplicações do SDK de Aplicações Windows que sejam suficientemente simples, não é necessário criar páginas ou controles de utilizador e pode copiar a sua marcação XAML e o código subjacente para MainWindow. Mas para obter informações sobre exceções a esse fluxo de trabalho, consulte Visual State Manager e Page.Resources.

Altere CoreWindow.Dispatcher para Window.DispatcherQueue

Alguns casos de uso para a classe Windows.UI.Core.CoreWindow do UWP migram para o Microsoft.UI.Xaml.Window do SDK de Aplicações do Windows.

Por exemplo, se estiveres a usar a propriedade Windows.UI.Core.CoreWindow.Dispatcher na tua aplicação UWP, a solução não é já migrar para a propriedade Microsoft.UI.Xaml.Window.Dispatcher (que sempre retorna null). Em vez disso, migre para a propriedade Microsoft.UI.Xaml.Window.DispatcherQueue, que retorna um Microsoft.UI.Dispatching.DispatcherQueue.

Para obter mais informações e exemplos de código, consulte alterar Windows.UI.Core.CoreDispatcher para Microsoft.UI.Dispatching.DispatcherQueue.

Tópicos relacionados

• SDK de Aplicativos Windows e versões suportadas do Windows
• Migrar sua funcionalidade de threading