Migrering av fönsterfunktioner

Det här avsnittet innehåller vägledning om fönsterhantering, inklusive migrering från UWP:s ApplicationView/CoreWindow eller AppWindow till Windows App SDK Microsoft.UI.Windowing.AppWindow.

Viktiga API:er

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

Sammanfattning av skillnader i API och/eller funktioner

Windows App SDK tillhandahåller en Microsoft.UI.Windowing.AppWindow-klass som baseras på Win32 HWND-modellen. Den AppWindow-klassen är Windows App SDK:s version av UWP:s ApplicationView/CoreWindow och AppWindow.

Om du vill dra nytta av Windows App SDK-fönster-API:er innebär det att du migrerar UWP-koden för att använda Win32-modellen. Mer information om Windows App SDK AppWindowfinns i Hantera appfönster.

Fönstertyper i UWP jämfört med Windows App SDK

I en UWP-app kan du vara värd för fönsterinnehåll med hjälp av ApplicationView/CoreWindoweller AppWindow. Arbetet med att migrera koden till Windows App SDK beror på vilka av de två fönstermodellerna som UWP-appen använder. Om du är bekant med UWP:s Windows.UI.WindowManagement.AppWindowkan du se likheter mellan det och Microsoft.UI.Windowing.AppWindow.

UWP-fönstertyper

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow konsoliderar användargränssnittstråden och fönstret som appen använder för att visa innehåll. UWP-appar som använder AppWindow har mindre arbete att göra än ApplicationView/CoreWindow appar för att migrera till Windows App SDK AppWindow.

Windows App SDK-fönstertyp

• Microsoft.UI.Windowing.AppWindow är en abstraktion på hög nivå av en systemhanterad container med innehållet i en app.

Tänk på att skillnaderna i fönstermodeller mellan UWP och Win32 innebär att det inte finns någon direkt 1:1-mappning mellan UWP API-ytan och Windows App SDK API-ytan. Även för klass- och medlemsnamn som gör överföra från UWP (visas i det här avsnittets mappningstabeller) kan beteendet också variera.

Välkomstskärmar

Till skillnad från UWP-appar visar Win32-appar som standard inte en välkomstskärm vid start. UWP-appar som förlitar sig på den här funktionen för sin startupplevelse kan välja att implementera en anpassad övergång till sitt första appfönster.

Skapa, visa, stänga och förstöra ett fönster

Livslängden för en Microsoft.UI.Windowing.AppWindow är densamma som för en HWND. vilket innebär att AppWindow-objektet är tillgängligt omedelbart efter att fönstret har skapats och förstörs när fönstret stängs.

Skapa och visa

AppWindow.Create skapar ett appfönster med standardkonfigurationen. Att skapa och visa ett fönster är bara nödvändigt för scenarier där du inte arbetar med ett gränssnittsramverk. Om du migrerar UWP-appen till ett Win32-kompatibelt gränssnittsramverk kan du fortfarande nå ditt AppWindow--objekt från ett fönster som redan har skapats med hjälp av interop-metoderna för fönster.

Stänga

I UWP ApplicationView.TryConsolidateAsync är den programmatiska motsvarigheten till användaren som initierar en nära gest. Det här begreppet konsolidering (i UWP:s ApplicationView/CoreWindow fönstermodell) finns inte i Win32. Win32 kräver inte att fönster finns i separata trådar. Att replikera UWP:s ApplicationView/CoreWindow fönstermodell skulle kräva att utvecklaren skapar en ny tråd och skapar ett nytt fönster där. Under Win32-modellen är standardbeteendet för systemet Stäng>Dölj>Destroy.

Grundläggande fönsteranpassning

När du migrerar från UWP till Windows App SDK kan du förvänta dig samma upplevelse från din standard AppWindow. Men om det behövs kan du ändra standard Microsoft.UI.Windowing.AppWindow för anpassade fönsterupplevelser. Mer information om hur du anpassar dina fönster finns i Microsoft.UI.Windowing.AppWindow.

Ändra storlek på ett fönster

Placera ett fönster

Fönstertitel

Kompakt överlägg och helskärm

Appar som ingår i kompakt överlägg eller helskärmsläge bör dra nytta av Windows App SDK AppWindowPresenter. Om du är bekant med UWP-AppWindowkanske du redan är bekant med begreppet presentatörer.

Det finns ingen 1:1-mappning av funktioner och beteenden från UWP-appfönsterpresentatörer till Windows App SDK-programfönsterpresentatörer. Om du har en UWP-ApplicationView/CoreWindow app kan du fortfarande ha kompakt överlägg (bild-i-bild) eller helskärmsfönsterupplevelser i din app, men begreppet presentatörer kan vara nytt för dig. För mer information om appfönsterpresentatörer, se presentatörer. Som standard tillämpas en överlappande presentatör på en AppWindow- när den skapas. CompactOverlay och FullScreen är de enda tillgängliga visningslägena, förutom standardläget.

Kompakt överlägg

Om du använde UWP:s ApplicationViewMode eller AppWindowPresentionKind för att presentera ett kompakt överläggsfönster bör du använda det kompakta överlägget AppWindowPresenterKind. Microsoft.UI.Windowing.CompactOverlayPresenter stöder endast tre fasta fönsterstorlekar med proportionerna 16:9 och kan inte ändras av användaren. I stället för ApplicationViewMode.TryEnterViewModeAsync eller AppWindowPresenterKind.RequestPresentationbör du använda AppWindow.SetPresenter för att ändra presentationen av AppWindow.

Helskärm

Om du använde UWP:s ApplicationViewWindowingMode eller AppWindowPresentionKind klasser för att presentera ett helskärmsfönster bör du använda AppWindowPresenterKind-. Windows App SDK stöder endast den mest restriktiva helskärmsupplevelsen (det vill säga, när FullScreen är IsExclusive). För ApplicationView/CoreWindowkan du använda ApplicationView.ExitFullScreenMode- för att ta bort appen från helskärmsläge. När du använder presentatörer kan du ta bort en app från helskärmsläge genom att ställa in presentatören på överlappande/standard med hjälp av AppWindow.SetPresenter.

Mer information om hur du arbetar med appfönsterpresentatörer finns i exempelgalleriet för fönster . Den visar hur du växlar mellan olika appfönsters presentatörstillstånd.

Anpassad titelrad

Om din app använder ett standardnamnfält behövs inget ytterligare arbete med namnlisten när du migrerar till Win32. Om däremot din UWP-app har en anpassad titelrad, kan det vara möjligt att återskapa följande scenarier i din Windows App SDK-app.

1. Anpassa den systemgenererade titelraden
2. Appgenererade anpassade titelrader

Kod som använder UWP ApplicationViewTitleBar, CoreApplicationViewTitleBaroch AppWindowTitleBar klasser migreras till att använda Windows App SDK Microsoft.UI.Windowing.AppWindowTitleBar-klass.

Anpassa den systemgenererade titelraden

Här är en tabell med API:er för färganpassning.

Dessa Windows App SDK-API:er är till för ytterligare anpassning av den systemritade titelraden utöver API:et AppWindow.Title.

• AppWindow.SetIcon. Anger namnlisten och aktivitetsfältets ikonbild med hjälp av antingen ett hIcon-handtag eller en strängsökväg till en resurs eller till en fil.
• AppWindowTitleBar.IconShowOptions. Hämtar eller anger ett värde som anger hur fönsterikonen visas i namnlisten. Stöder för närvarande två värden:HideIconAndSystemMenu och ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Återställ namnlisten till standardinställningarna för fönstret.

App-genererade anpassade titelrader (fullständig anpassning)

Om du migrerar till att använda AppWindowTitleBarrekommenderar vi att du kontrollerar AppWindowTitleBar.IsCustomizationSupported i koden innan du anropar följande API:er för anpassade namnlister.

Dessa Windows App SDK-API:er är till för fullständig anpassning av namnlisten.

• AppWindowTitleBar.SetDragRectangles. Anger fönstrets dragområden.
• AppWindowTitleBar.ÅterställTillStandard. Återställ namnlisten till standardinställningarna för fönstret.

Dessa UWP-AppWindow API:er har ingen direkt 1:1-mappning till ett Windows App SDK-API.

• AppWindowTitleBarVisibility. Definierar konstanter som anger önskad synlighet för en AppWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Hämtar det önskade synlighetsläget för namnlisten.
• AppWindowTitleBar.SetPreferredVisibility. Anger önskat synlighetsläge för namnlisten.

Mer information om hur du arbetar med AppWindowTitleBarfinns i fönstergalleriprovet. Den visar hur du skapar en anpassad färgad titelrad och hur du ritar en anpassad titelrad.

Händelsehantering

Om UWP-appen använder händelsen AppWindow.Changed kan du migrera koden till Microsoft.UI.Windowing.AppWindow.Changed event.

Ändrad storlek för händelse

När du migrerar storleksändringskod för händelsehantering bör du växla till att använda Windows App SDK AppWindowChangedEventArgs.DidSizeChange egenskapen. Värdet är true om appfönstrets storlek ändras, annars är det false.

MainPage och MainWindow

När du skapar ett nytt UWP-projekt i Visual Studio ger projektmallen dig en MainPage--klass. För din app kanske du har bytt namn på den klassen (och/eller lagt till fler sidor och användarkontroller). Projektmallen innehåller även navigeringskod i metoderna för klassen App.

När du skapar ett nytt Windows App SDK-projekt i Visual Studio ger projektmallen dig en MainWindow-klass (av typen Microsoft.UI.Xaml.Window), men ingen sida. Och projektmallen tillhandahåller ingen navigeringskod.

Du kan dock lägga till sidor och användarkontroller i ditt Windows App SDK-projekt. Du kan till exempel lägga till ett nytt sidobjekt i projektet (WinUI>Tom sida (WinUI 3)) och ge det namnet MainPage.xamleller något annat namn. Det skulle lägga till en ny klass av typen Microsoft.UI.Xaml.Controls.Pagei projektet. Information om hur du lägger till navigeringskod i projektet finns sedan i Behöver jag implementera sidnavigering?.

För Windows App SDK-appar som är tillräckligt enkla behöver du inte skapa sidor eller användarkontroller, och du kan kopiera XAML-markering och kod bakom till MainWindow. Men information om undantag till arbetsflödet finns i Visual State Manager och Page.Resources.

Ändra CoreWindow.Dispatcher till Window.DispatcherQueue

Vissa användningsfall för UWP:s Windows.UI.Core.CoreWindow-klass migreras till Windows App SDK:s Microsoft.UI.Xaml.Window.

Om du till exempel använder egenskapen Windows.UI.Core.CoreWindow.Dispatcher i UWP-appen är lösningen inte att migrera till egenskapen Microsoft.UI.Xaml.Window.Dispatcher (som alltid returnerar null). Migrera i stället till egenskapen Microsoft.UI.Xaml.Window.DispatcherQueue, som returnerar en Microsoft.UI.Dispatching.DispatcherQueue.

Mer information och kodexempel finns i Ändra Windows.UI.Core.CoreDispatcher till Microsoft.UI.Dispatching.DispatcherQueue.

Relaterade ämnen

• Windows App SDK och Windows-versioner som stöds
• Migrera din trådfunktionalitet