Migração da funcionalidade de janelas
Este tópico contém diretrizes relacionadas ao gerenciamento de janelas, incluindo a migração do ApplicationView/CoreWindow da UWP ou do AppWindow para o SDK do Aplicativo de Janela 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 Win32 HWND. 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 windows do aplicativo contém um exemplo de código que demonstra como recuperar um AppWindow de uma janela 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 o SDK do Aplicativo Windows
Em um aplicativo UWP, você pode hospedar o conteúdo da janela usando o ApplicationView/CoreWindow ou o AppWindow. O trabalho envolvido na migração desse código para o SDK do Aplicativo Windows depende de quais desses dois modelos de janela seu aplicativo UWP usa. Se você estiver familiarizado com Windows.UI.WindowManagement.AppWindow da UWP, poderá 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 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 Do 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.
Tenha em mente que as diferenças nos modelos de janela entre UWP e Win32 significam que não há um mapeamento direto 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 (refletido 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 ou 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 de janela básica
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 janela 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 (normalmente aparece em C# como CoreWindow.GetForCurrentThread.Bounds) |
AppWindowPlacement.Size | AppWindow.Size |
Posicionando uma janela
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| Impossível | AppWindow.GetPlacement | AppWindow.Position |
| Impossível | Appwindow.RequestMoveXxx | AppWindow.Move |
Título da janela
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| ApplicationView.Title | AppWindow.Title | AppWindow.Title |
Sobreposição compacta e tela inteira
Os aplicativos que entram em sobreposição compacta, ou em tela inteira, devem aproveitar o SDK do Aplicativo Windows AppWindowPresenter. Se você estiver familiarizado com o AppWindow da UWP, 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 SDK do Aplicativo Windows apresentadores da janela do aplicativo. Se você tiver um aplicativo UWP ApplicationView/CoreWindow , ainda poderá ter uma sobreposição compacta (imagem em imagem) ou experiências de janela de tela inteira em seu aplicativo, mas o conceito de apresentadores pode ser novo para você. Para obter mais informações sobre os apresentadores da janela do 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 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 inteira
Se você usou as classes ApplicationViewWindowingMode ou AppWindowPresentionKind da UWP para apresentar uma janela de tela inteira, deverá usar o AppWindowPresenterKind em tela inteira. O SDK do Aplicativo Windows dá suporte apenas à experiência de tela inteira mais restritiva (ou seja, quando FullScreen é IsExclusive). Para o 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 como 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 os apresentadores da janela do aplicativo, consulte o exemplo da galeria de janelas. Ele demonstra como alternar diferentes estados do apresentador da janela do aplicativo.
Barra de título personalizada
Observação
No momento, as APIs de personalização da barra de título funcionam apenas em Windows 11. Recomendamos que você marcar 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 de barra de título necessário ao migrar para o Win32. Se, por outro lado, o 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 pelo aplicativo
O código que usa as classes ApplicationViewTitleBar, CoreApplicationViewTitleBar e AppWindowTitleBar da UWP migra para usando o SDK do Aplicativo Windows classe 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 (implicitamente definido).
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 de janela é exibido na barra de título. Dá suporte a 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 pelo aplicativo (personalização completa)
Se você estiver migrando para usando AppWindowTitleBar, recomendamos que você marcar AppWindowTitleBar.IsCustomizationSupported em seu código antes de chamar as APIs da barra de título personalizada a seguir.
| 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. O SDK do Aplicativo Windows informações de inicialização esquerda e direita do AppWindow, 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 direto 1:1 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 cores 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 tamanho alterado
Ao migrar o código de manipulação de eventos alterado, você deve mudar para usando a propriedade SDK do Aplicativo Windows AppWindowChangedEventArgs.DidSizeChange. O valor será true se o tamanho da janela do aplicativo for alterado, caso contrário, será false.
| UWP ApplicationView/CoreWindow | UWP AppWindow | SDK do Aplicativo do Windows |
|---|---|---|
| CoreWindow.SizeChanged | AppWindowChangedEventArgs.DidSizeChange | AppWindowChangedEventArgs.DidSizeChange |
MainPage e MainWindow
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 SDK do Aplicativo 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.xamlcomo ou 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 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 para a classe Windows.UI.Core.CoreWindow da UWP migram para o 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