Migratie van vensterfunctionaliteit

Dit onderwerp bevat richtlijnen voor vensterbeheer, waaronder het migreren van UWP's ApplicationView/CoreWindow of AppWindow naar de Window App SDK Microsoft.UI.Windowing.AppWindow.

Belangrijke API's

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

Overzicht van verschillen tussen API's en/of functies

De Windows App SDK biedt een Microsoft.UI.Windowing.AppWindow klasse die is gebaseerd op het Win32 HWND-model. Deze klasse AppWindow is de Windows App SDK-versie van de ApplicationView/CoreWindow en AppWindow.

Als u wilt profiteren van de Windows App SDK venster-API's, betekent dit dat u uw UWP-code migreert om het Win32-model te gebruiken. Zie voor meer informatie over de Windows App SDK AppWindowBeheer-appvensters.

Venstertypen in UWP versus de Windows App SDK

In een UWP-app kunt u vensterinhoud hosten met ApplicationView/CoreWindow of AppWindow. Het werk dat betrokken is bij het migreren van die code naar de Windows App SDK is afhankelijk van welke van deze twee venstermodellen uw UWP-app gebruikt. Als u bekend bent met de Windows.UI.WindowManagement.AppWindow van UWP, ziet u mogelijk overeenkomsten tussen dat en Microsoft.UI.Windowing.AppWindow.

Types UWP-vensters

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow- voegt de UI-thread en het venster dat de app gebruikt om inhoud weer te geven. UWP-apps die gebruikmaken van AppWindow hebben minder werk te doen dan ApplicationView/CoreWindow-apps om te migreren naar de Windows App SDK AppWindow.

Windows App SDK venstertype

• Microsoft.UI.Windowing.AppWindow is de abstractie op hoog niveau van een door het systeem beheerde container van de inhoud van een app.

Houd er rekening mee dat de verschillen in venstermodellen tussen UWP en Win32 betekenen dat er geen directe 1:1-toewijzing is tussen de UWP-API-surface en de Windows App SDK-API-surface. Zelfs voor klassen- en ledennamen die overdragen van UWP (weerspiegeld in de toewijzingstabellen van dit onderwerp), kan het gedrag ook verschillen.

Welkomstschermen

In tegenstelling tot UWP-apps geven Win32-apps niet standaard een welkomstscherm weer bij het starten. UWP-apps die afhankelijk zijn van deze functie voor hun startervaring, kunnen ervoor kiezen om een aangepaste overgang naar hun eerste app-venster te implementeren.

Een venster maken, weergeven, sluiten en vernietigen

De levensduur van een Microsoft.UI.Windowing.AppWindow is hetzelfde als voor een HWND; betekent dat het AppWindow-object direct na het maken van het venster beschikbaar is en wordt vernietigd wanneer het venster wordt gesloten.

Maken en weergeven

AppWindow.Create maakt een app-venster met de standaardconfiguratie. Het maken en weergeven van een venster is alleen nodig voor scenario's waarin u niet met een UI-framework werkt. Als u uw UWP-app migreert naar een win32-compatibel UI-framework, kunt u uw AppWindow-object nog steeds bereiken vanuit een al gemaakt venster met behulp van de interoperabiliteitsmethoden voor vensters.

Sluiten

In UWP is ApplicationView.TryConsolidateAsync het programmatische equivalent van de gebruiker die een sluitgebaar initieert. Dit concept van samenvoeging (in UWP's ApplicationView/CoreWindow windowing model) bestaat niet in Win32. Win32 vereist niet dat vensters bestaan in afzonderlijke threads. Als de ontwikkelaar het ApplicationView-venstermodel/van de UWP CoreWindow wilt repliceren, moet hij een nieuwe thread aanmaken en daar een nieuw venster maken. Onder het Win32-model is het standaardsysteemgedrag Close>Hide>Destroy.

Basisvensterpersonalisatie

Wanneer u migreert van UWP naar de Windows App SDK, kunt u dezelfde ervaring verwachten van uw standaard-AppWindow. Maar indien nodig kunt u de standaard microsoft.UI.Windowing.AppWindow wijzigen voor aangepaste vensterervaringen. Zie Microsoft.UI.Windowing.AppWindow voor meer informatie over het aanpassen van uw vensters.

Het formaat van een venster wijzigen

Een venster positioneren

Venstertitel

Compacte overlay en volledig scherm

Apps die in compacte overlay of volledig scherm worden ingevoerd, moeten profiteren van de Windows App SDK AppWindowPresenter. Als u bekend bent met de UWP AppWindow, bent u mogelijk al bekend met het concept van presentatoren.

Er is geen 1:1-toewijzing van functionaliteit en gedrag van UWP-apppresentatoren en Windows SDK-appvensterpresentatoren. Als u een UWP ApplicationView/CoreWindow-app hebt, kunt u nog steeds een compacte overlay (afbeelding-in-afbeelding) of vensterervaringen op volledig scherm in uw app hebben, maar het concept van presentatoren is mogelijk nieuw voor u. Voor meer informatie over presentatoren van app-vensters, zie Presentatoren. Standaard wordt een overlappende presentator toegepast op een AppWindow- bij het aanmaken. CompactOverlay en FullScreen zijn de enige beschikbare presentatoren, afgezien van de standaardinstelling.

Compacte overlay

Als u de ApplicationViewMode of AppWindowPresentionKind van UWP hebt gebruikt om een compact overlayvenster te presenteren, moet u de compacte overlay AppWindowPresenterKind gebruiken. Microsoft.UI.Windowing.CompactOverlayPresenter ondersteunt slechts drie vaste venstergrootten met een hoogte-breedteverhouding van 16:9 en kan niet worden gewijzigd door de gebruiker. In plaats van ApplicationViewMode.TryEnterViewModeAsync of AppWindowPresenterKind.RequestPresentation moet u AppWindow.SetPresenter gebruiken om de presentatie van de AppWindow te wijzigen.

Volledig scherm

Als u de ApplicationViewWindowingMode of AppWindowPresentionKind klassen hebt gebruikt om een volledig schermvenster te presenteren, moet u het volledige scherm gebruiken AppWindowPresenterKind. De Windows App SDK ondersteunt alleen de meest beperkende volledige schermervaring (dat wil gezegd, wanneer FullScreen is IsExclusive). Voor ApplicationView/CoreWindow-kunt u de ApplicationView.ExitFullScreenMode gebruiken om de app uit de volledige schermmodus te halen. Wanneer u presentatoren gebruikt, kunt u een app uit de volledige schermmodus halen door de presentator terug te zetten naar overlappend/standaard met behulp van AppWindow.SetPresenter.

Zie het voorbeeld van de Windowing-galerie voor meer informatie over het werken met presentatoren voor app-vensters. Het laat zien hoe u verschillende statussen van de presentator van het app-venster kunt in- of uitschakelen.

Aangepaste titelbalk

Als uw app een standaardtitelbalk gebruikt, is er geen extra werk voor de titelbalk nodig wanneer u migreert naar Win32. Als uw UWP-app daarentegen een aangepaste titelbalk heeft, kunt u de volgende scenario's in uw Windows App SDK-app opnieuw maken.

1. De door het systeem getekende titelbalk aanpassen
2. Aangepaste titelbalk getekend door app

Code die gebruikmaakt van de UWP-ApplicationViewTitleBar, CoreApplicationViewTitleBar, en AppWindowTitleBar-klassen worden gemigreerd naar het gebruik van de klasse Windows App SDK Microsoft.UI.Windowing.AppWindowTitleBar.

De door het systeem getekende titelbalk aanpassen

Hier volgt een tabel met de API's voor kleuraanpassing.

Deze Windows App SDK API's zijn bedoeld voor verdere aanpassing van de door het systeem getekende titelbalk naast de AppWindow.Title-API.

• AppWindow.SetIcon. Hiermee stelt u de titelbalk- en taakbalkpictogramafbeelding in met behulp van een hIcon-ingang of een tekenreekspad naar een resource of een bestand.
• AppWindowTitleBar.IconShowOptions. Hiermee wordt een waarde opgehaald of ingesteld waarmee wordt aangegeven hoe het vensterpictogram wordt weergegeven op de titelbalk. Ondersteunt momenteel twee waarden: HideIconAndSystemMenu en ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Hiermee stelt u de huidige titelbalk weer in op de standaardinstellingen voor het venster.

App-getekende aangepaste titelbalk (volledig aanpasbaar)

Als u migreert naar het gebruik van AppWindowTitleBar, raden we u aan AppWindowTitleBar.IsCustomizationSupported in uw code te controleren voordat u de volgende aangepaste titelbalk-API's aanroept.

Deze Windows App SDK API's zijn bedoeld voor het aanpassen van de volledige titelbalk.

• AppWindowTitleBar.SetDragRectangles. Hiermee stelt u de sleepregio's voor het venster in.
• AppWindowTitleBar.ResetToDefault. Hiermee stelt u de huidige titelbalk weer in op de standaardinstellingen voor het venster.

Deze UWP-AppWindow-API's hebben geen directe 1:1-toewijzing aan een Windows App SDK-API.

• AppWindowTitleBarVisibility. Definieert constanten die de voorkeurszichtbaarheid van een AppWindowTitleBar opgeven.
• AppWindowTitleBar.GetPreferredVisibility. Hiermee haalt u de voorkeurszichtbaarheidsmodus voor de titelbalk op.
• AppWindowTitleBar.SetPreferredVisibility. Hiermee stelt u de voorkeurszichtbaarheidsmodus voor de titelbalk in.

Raadpleeg voor meer details over het werken met AppWindowTitleBar de Windowing-galerij voorbeeld. Het laat zien hoe u een aangepaste titelbalk met kleuren maakt en hoe u een aangepaste titelbalk tekent.

Gebeurtenisafhandeling

Als uw UWP-app gebruikmaakt van de gebeurtenis AppWindow.Changed , kunt u die code migreren naar de gebeurtenis Microsoft.UI.Windowing.AppWindow.Changed .

Grootte gewijzigd gebeurtenis

Wanneer u code voor het afhandelen van grootteveranderingsevents migreert, moet u overschakelen naar de eigenschap Windows App SDK AppWindowChangedEventArgs.DidSizeChange. De waarde is true als de grootte van het app-venster is gewijzigd, anders is het false.

MainPage en MainWindow

Wanneer u een nieuwe UWP-project maakt in Visual Studio, biedt de project-sjabloon u een MainPage-klasse. Voor uw app hebt u mogelijk de naam van die klasse gewijzigd (en/of meer pagina's en gebruikersbesturingselementen toegevoegd). De project-sjabloon bevat ook navigatiecode in de methoden van de klasse App.

Wanneer u een nieuwe Windows App SDK project maakt in Visual Studio, de project-sjabloon bevat een klasse MainWindow (van het type Microsoft.UI.Xaml.Window), maar geen Page. De project sjabloon bevat geen navigatiecode.

U kunt echter pagina's en gebruikersbesturingselementen toevoegen aan uw Windows App SDK project. U kunt bijvoorbeeld een nieuw pagina-item toevoegen aan de project (WinUI>Blank Page (WinUI)) en deze MainPage.xaml of een andere naam geven. Er zal aan uw project een nieuwe klasse van het type Microsoft.UI.Xaml.Controls.Page worden toegevoegd. Raadpleeg vervolgens Moet ik paginanavigatie implementeren? voor informatie over het toevoegen van navigatiecode aan het project.

Voor Windows App SDK apps die eenvoudig genoeg zijn, hoeft u geen pagina's of gebruikersbesturingselementen te maken en kunt u uw XAML-markeringen en code-achter kopiëren naar MainWindow. Zie Visual State Manager en Page.Resources voor informatie over uitzonderingen op die werkstroom.

CoreWindow.Dispatcher wijzigen in Window.DispatcherQueue

Sommige gebruiksvoorbeelden voor de Windows.UI.Core.CoreWindow-klasse migreren naar de Windows App SDK Microsoft.UI.Xaml.Window.

Als u bijvoorbeeld de eigenschap Windows.UI.Core.CoreWindow.Dispatcher in uw UWP-app gebruikt, wordt de oplossing niet gemigreerd naar de eigenschap Microsoft.UI.Xaml.Window.Dispatcher (die altijd null retourneert). Migreer in plaats daarvan naar de eigenschap Microsoft.UI.Xaml.Window.DispatcherQueue , die een Microsoft.UI.Dispatching.DispatcherQueue retourneert.

Zie Windows.UI.Core.CoreDispatcher wijzigen in Microsoft.UI.Dispatching.DispatcherQueue voor meer informatie en codevoorbeelden.

Verwante onderwerpen

• Windows App SDK en ondersteunde Windows-releases
• De threading-functionaliteit migreren