Migração da funcionalidade de janelas

Este tópico contém orientações relacionadas ao gerenciamento de janelas, incluindo a migração do ApplicationView/CoreWindow ou AppWindow do UWP ao SDK de 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 SDK do Aplicativo Windows fornece uma classe Microsoft.UI.Windowing.AppWindow baseada no modelo HWND do Win32. Essa classe AppWindow é a versão do SDK do Aplicativo Windows do ApplicationView/CoreWindow e AppWindow da UWP.

Aproveitar as APIs de janela SDK do Aplicativo Windows significa que você migrará seu código UWP para usar o modelo Win32. Para obter mais informações sobre o SDK do Aplicativo Windows AppWindow, consulte Gerenciar janelas de aplicativos.

Tipos de janela na UWP versus 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 você estiver familiarizado com o Windows.UI.WindowManagement.AppWindow da UWP, poderá ver semelhanças entre ele e Microsoft.UI.Windowing.AppWindow.

Tipos de janela UWP

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow consolida o thread da interface do usuário e a janela que o aplicativo 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.

SDK do Aplicativo Windows tipo de janela

• 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 janela entre UWP e Win32 significam que não há um mapeamento direto de 1:1 entre a superfície da API UWP e a superfície da API SDK do Aplicativo Windows. Mesmo para nomes de classe e membro que são transferidos da UWP (refletidos nas tabelas de mapeamento deste tópico), o comportamento também pode ser diferente.

Telas 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 a primeira janela do 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 criação da janela 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 janela.

Fechar

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

Personalização básica de janela

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

Redimensionando uma janela

Posicionando uma janela

Window title

Sobreposição compacta e tela cheia

Os aplicativos que entram em sobreposição compacta ou tela inteira devem aproveitar o SDK do Aplicativo Windows AppWindowPresenter. Se você estiver familiarizado com o UWP AppWindow, talvez já esteja familiarizado com o conceito de apresentadores.

Não há um mapeamento 1:1 da funcionalidade e do comportamento dos apresentadores da janela do aplicativo UWP para os apresentadores da janela do aplicativo SDK do Aplicativo Windows. Se você tiver um aplicativo UWP ApplicationView/CoreWindow , ainda poderá ter experiências de sobreposição compacta (picture-in-picture) ou janelas de tela inteira em seu aplicativo, mas o conceito de apresentadores pode ser novo para você. Para obter mais informações sobre apresentadores de janela de aplicativo, 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 você usou o ApplicationViewMode ou AppWindowPresentionKind da UWP para apresentar uma janela de sobreposição compacta, deverá usar a sobreposição compacta AppWindowPresenterKind. O Microsoft.UI.Windowing.CompactOverlayPresenter dá suporte a apenas três tamanhos de janela fixos em uma taxa de 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.

Tela cheia

Se você usou as classes ApplicationViewWindowingMode ou AppWindowPresentionKind da UWP para apresentar uma janela de tela inteira, deverá usar o AppWindowPresenterKind de tela inteira. SDK do Aplicativo Windows dá suporte apenas à experiência de tela inteira mais restritiva (ou seja, quando FullScreen é IsExclusive). Para ApplicationView/CoreWindow, você pode usar o ApplicationView.ExitFullScreenMode para tirar o aplicativo da tela inteira. Ao usar apresentadores, você pode tirar um aplicativo da tela inteira definindo o apresentador de volta para sobreposto/padrão usando AppWindow.SetPresenter.

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

Barra de título personalizada

Se o aplicativo usar uma barra de título padrão, não haverá nenhum trabalho adicional na barra de título necessário ao migrar para o Win32. Se, por outro lado, seu aplicativo UWP tiver uma barra de título personalizada, será possível recriar os cenários a seguir em seu aplicativo SDK do 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 as classes UWP ApplicationViewTitleBar, CoreApplicationViewTitleBar e AppWindowTitleBar migra para usar a classe SDK do Aplicativo Windows 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 SDK do 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 barra de título e a imagem do ícone da barra de tarefas usando um identificador hIcon ou um caminho de cadeia de caracteres para um recurso ou para um arquivo.
• AppWindowTitleBar.IconShowOptions. Obtém ou define um valor que especifica como o ícone da janela é exibido na barra de título. Atualmente, dá suporte a dois valores: 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 o uso de AppWindowTitleBar, recomendamos que você verifique AppWindowTitleBar.IsCustomizationSupported em seu código antes de chamar as seguintes APIs de barra de título personalizadas.

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

• AppWindowTitleBar.SetDragRectangles. Define as regiões de arrastar 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 SDK do Aplicativo Windows.

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

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

Manipulação de eventos

Se o aplicativo UWP usar o evento AppWindow.Changed, você poderá 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 alterado por tamanho, você deve alternar para o uso da propriedade SDK do Aplicativo Windows AppWindowChangedEventArgs.DidSizeChange. O valor é true se o tamanho da janela do aplicativo mudou, caso contrário, é false.

Página principal e janela principal

Quando você 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 você cria um novo projeto do SDK de Aplicativos Windows no Visual Studio, o modelo de projeto fornece uma classe MainWindow (do tipo Microsoft.UI.Xaml.Window), mas nenhuma Página. 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 SDK do Aplicativo 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 do 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 de página?.

Para SDK do Aplicativo Windows aplicativos que são simples o suficiente, você não precisa criar páginas ou controles de usuário e pode copiar sua marcação XAML e code-behind para MainWindow. Mas para obter informações sobre exceções a esse fluxo de trabalho, consulte Visual State Manager e Page.Resources.

Alterar CoreWindow.Dispatcher para Window.DispatcherQueue

Alguns casos de uso da classe Windows.UI.Core.CoreWindow da UWP migram para Microsoft.UI.Xaml.Window do SDK do Aplicativo Windows.

Por exemplo, se você estiver usando a propriedade Windows.UI.Core.CoreWindow.Dispatcher em seu aplicativo UWP, a solução não será migrar para a propriedade Microsoft.UI.Xaml.Window.Dispatcher (que sempre retorna nulo). 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 do Aplicativo do Windows e versões do Windows com suporte
• Migrar sua funcionalidade de threading