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.
Dica
O tópico Gerenciar janelas do aplicativo contém um exemplo de código que demonstra como recuperar um AppWindow de uma janela do WinUI 3. Em seu aplicativo WinUI 3, use esse padrão de código para que você possa chamar as APIs AppWindow mencionadas no restante deste tópico.
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.
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| CoreApplication.CreateNewView or CoreWindow.GetForCurrentThread |
AppWindow.TryCreateAsync | AppWindow.Create |
| CoreWindow.Activate | AppWindow.TryShowAsync | AppWindow.Show |
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.
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| ApplicationView.TryConsolidateAsync | AppWindow.CloseAsync | AppWindow.Destroy |
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
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| ApplicationView.TryResizeView | AppWindow.RequestSize | AppWindow.Resize |
CoreWindow.Bounds (geralmente aparece em C# como CoreWindow.GetForCurrentThread.Bounds) |
AppWindowPlacement.Size | AppWindow.Size |
Posicionando uma janela
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| Não é possível | AppWindow.GetPlacement | AppWindow.Position |
| Não é possível | Appwindow.RequestMoveXxx | AppWindow.Move |
Window title
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| ApplicationView.Title | AppWindow.Title | AppWindow.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.
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| ApplicationViewMode.CompactOverlay | AppWindowPresentationKind.CompactOverlay | AppWindowPresenterKind.CompactOverlay |
| ApplicationView.TryEnterViewModeAsync com ApplicationViewMode.CompactOverlay | AppWindowPresenter.RequestPresentation com AppWindowPresenterKind.CompactOverlay | AppWindow.SetPresenter com AppWindowPresenterKind.CompactOverlay |
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.
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| ApplicationViewWindowingMode.FullScreen | AppWindowPresentationKind.FullScreen | AppWindowPresenterKind.FullScreen |
| ApplicationView.TryEnterFullScreenMode | AppWindowPresenter.RequestPresentation com AppWindowPresenterKind.FullScreen | AppWindow.SetPresenter com AppWindowPresenterKind.FullScreen |
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
Observação
Atualmente, as APIs de personalização da barra de título funcionam apenas no Windows 11. Recomendamos que você verifique AppWindowTitleBar.IsCustomizationSupported em seu código antes de chamar essas APIs.
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.
- Personalizar a barra de título desenhada pelo sistema
- 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.
Observação
Quando AppWindowTitleBar.ExtendsContentIntoTitleBar é true, a transparência tem suporte apenas para as seguintes propriedades: AppWindowTitleBar.ButtonBackgroundColor, AppWindowTitleBar.ButtonInactiveBackgroundColor, AppWindowTitleBar.ButtonPressedBackgroundColor, AppWindowTitleBar.ButtonHoverBackgroundColor e AppWindowTitleBar.BackgroundColor (definido implicitamente).
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.
| UWP ApplicationView/CoreWindow | SDK do Aplicativo Windows AppWindow |
|---|---|
| CoreApplicationViewTitleBar.ExtendViewIntoTitleBar | AppWindowTitleBar.ExtendsContentIntoTitleBar A plataforma continua a desenhar os botões Minimizar/Maximizar/Fechamento para você e relata as informações de oclusão. |
| CoreApplicationViewTitleBar.SystemOverlayLeftInset | AppWindowTitleBar.LeftInset |
| CoreApplicationViewTitleBar.SystemOverlayRightInset | AppWindowTitleBar.RightInset |
| CoreApplicationViewTitleBar.Height | AppWindowTitleBar.Height |
| AppWindowTitleBarOcclusion AppWindowTitleBar.GetTitleBarOcclusions |
Representa as regiões reservadas pelo sistema da janela do aplicativo que ocluirão o conteúdo do aplicativo se ExtendsContentIntoTitleBar for true. As informações de inserção esquerda e direita do SDK do Aplicativo Windows, juntamente com a altura da barra de título, fornecem as mesmas informações. AppWindowTitleBar.LeftInset, AppWindowTitleBar.RightInset, AppWindowTitleBar.Height |
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.
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| CoreWindow.SizeChanged | AppWindowChangedEventArgs.DidSizeChange | AppWindowChangedEventArgs.DidSizeChange |
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
Windows developer
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de