Migracja funkcji obsługi okien

Ten temat zawiera wskazówki dotyczące zarządzania oknami, w tym migrację z UWP (Universal Windows Platform) ApplicationView/CoreWindow lub AppWindow do Window App SDK Microsoft.UI.Windowing.AppWindow.

Ważne interfejsy API

• Microsoft.UI.Windowing.AppWindow
• Windows.UI.Core.CoreWindow.Dispatcher właściwość
• właściwość Microsoft.UI.Window.DispatcherQueue

Podsumowanie różnic między interfejsami API i/lub funkcjami

Zestaw SDK aplikacji systemu Windows udostępnia klasę Microsoft.UI.Windowing.AppWindow opartą na modelu HWND Win32. Ta klasa AppWindow jest wersją pakietu Windows App SDK odpowiednią dla ApplicationView/CoreWindow i AppWindowUWP.

Aby skorzystać z interfejsów API okien zestawu SDK aplikacji systemu Windows, należy przeprowadzić migrację kodu platformy UWP do korzystania z modelu Win32. Aby uzyskać więcej informacji na temat Windows App SDK AppWindow, zobacz Zarządzanie oknami aplikacji.

Typy okien w systemie UWP a zestaw SDK aplikacji systemu Windows

W aplikacji UWP możesz hostować zawartość okna przy użyciu ApplicationView/CoreWindow lub AppWindow. Praca związana z migracją tego kodu do zestawu SDK aplikacji systemu Windows zależy od tego, które z tych dwóch modeli okien używa aplikacja platformy UWP. Jeśli znasz Windows.UI.WindowManagement.AppWindowplatformy UWP, to możesz zauważyć podobieństwa między nim a Microsoft.UI.Windowing.AppWindow.

Typy okien UWP systemu Windows

• Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
• Windows.UI.WindowManagement.AppWindow. AppWindow konsoliduje wątek interfejsu użytkownika i okno używane przez aplikację do wyświetlania zawartości. Aplikacje UWP korzystające z AppWindow będą miały mniej pracy do wykonania niż aplikacje ApplicationView/CoreWindow przy migracji do zestawu SDK aplikacji Windows AppWindow.

Typ okna zestawu SDK aplikacji systemu Windows

• Microsoft.UI.Windowing.AppWindow to abstrakcja wysokiego poziomu kontenera zarządzanego przez system zawartości aplikacji.

Należy pamiętać, że różnice w modelach okien między platformami UWP i Win32 oznaczają, że nie istnieje bezpośrednie mapowanie 1:1 między powierzchnią interfejsu API platformy UWP a powierzchnią interfejsu API zestawu SDK aplikacji systemu Windows. Nawet w przypadku nazw klas i składowych, które przenoszone z platformy UWP (odzwierciedlone w tabelach mapowania tego tematu), zachowanie może się również różnić.

Ekrany początkowe

W przeciwieństwie do aplikacji platformy UWP aplikacje Win32 domyślnie nie wyświetlają ekranu powitalnego podczas uruchamiania. Aplikacje UWP polegające na tej funkcji dla swojego środowiska uruchamiania mogą wybrać wdrożenie niestandardowego przejścia do pierwszego okna aplikacji.

Tworzenie, pokazywanie, zamykanie i niszczenie okna

Okres istnienia elementu Microsoft.UI.Windowing.AppWindow jest taki sam jak w przypadku HWND; oznacza to, że obiekt AppWindow jest dostępny natychmiast po utworzeniu okna i jest niszczony po zamknięciu okna.

Tworzenie i wyświetlanie

AppWindow.Create tworzy okno aplikacji z konfiguracją domyślną. Tworzenie i wyświetlanie okna jest konieczne tylko w scenariuszach, w których nie pracujesz z platformą interfejsu użytkownika. Jeśli migrujesz aplikację platformy UWP do platformy interfejsu użytkownika zgodnej z systemem Win32, nadal możesz uzyskać dostęp do obiektu AppWindow z już utworzonego okna przy użyciu metod międzyoperacyjnych okien.

Zamknij

W systemie UWP ApplicationView.TryConsolidateAsync jest programowym odpowiednikiem użytkownika inicjującego gest zamknięcia. Ta koncepcja konsolidacji (w modelu ApplicationView platformy UWP/CoreWindow) nie istnieje w systemie Win32. Win32 nie wymaga, aby okna istniały w oddzielnych wątkach. Replikowanie modelu okien ApplicationView platformy UWP/CoreWindow wymagałoby od dewelopera utworzenia nowego wątku i utworzenia w nim nowego okna. W modelu Win32 domyślne zachowanie systemu to Close>Hide>Destroy.

Dostosowywanie okna podstawowego

Podczas migracji z platformy UWP do Windows App SDK można oczekiwać tej samej funkcjonalności z domyślnego okna aplikacji AppWindow. W razie potrzeby można jednak zmienić domyślne Microsoft.UI.Windowing.AppWindow, aby dostosować środowiska okien. Aby uzyskać więcej informacji na temat dostosowywania okien, zobacz Microsoft.UI.Windowing.AppWindow .

Zmiana rozmiaru okna

Pozycjonowanie okna

Tytuł okna

Kompaktowa nakładka i pełny ekran

Aplikacje wchodzące w kompaktową nakładkę lub pełny ekran powinny korzystać z zestawu SDK aplikacji systemu Windows AppWindowPresenter. Jeśli znasz platformę UWP AppWindow, być może znasz już koncepcję prezenterów.

Nie istnieje mapowanie funkcji i zachowania 1:1 z prezenterów okien aplikacji platformy UWP do prezenterów okien aplikacji zestawu Sdk aplikacji systemu Windows. Jeśli masz aplikację Uniwersalnej Platformy Windows ApplicationView/CoreWindow, nadal możesz mieć kompaktową nakładkę (obraz w obrazie) lub tryby pełnoekranowe w aplikacji, ale pojęcie prezenterów może być Ci nieznane. Aby uzyskać więcej informacji na temat prezenterów okien aplikacji, sprawdź Presenters. Domyślnie nakładający się prezenter jest stosowany do AppWindow w czasie tworzenia. CompactOverlay i FullScreen są jedynymi dostępnymi prezenterami, oprócz domyślnego.

Kompaktowa nakładka

Jeśli użyto ApplicationViewMode platformy UWP lub AppWindowPresentionKind do przedstawienia kompaktowego okna nakładki, należy użyć kompaktowej nakładki AppWindowPresenterKind. Obiekt Microsoft.UI.Windowing.CompactOverlayPresenter obsługuje tylko trzy stałe rozmiary okien o współczynniku proporcji 16:9 i nie można zmienić ich rozmiaru przez użytkownika. Zamiast applicationViewMode.TryEnterViewModeAsync lub AppWindowPresenterKind.RequestPresentation należy użyć elementu AppWindow.SetPresenter , aby zmienić prezentację aplikacji AppWindow.

Pełny ekran

Jeśli użyto klas ApplicationViewWindowingMode platformy UWP lub AppWindowPresentationKind, aby zaprezentować okno w trybie pełnoekranowym, należy użyć trybu pełnoekranowego AppWindowPresenterKind. Zestaw SDK aplikacji systemu Windows obsługuje tylko najbardziej restrykcyjne środowisko pełnoekranowe (czyli gdy FullScreen jest IsExclusive). W przypadku ApplicationView/CoreWindow możesz użyć ApplicationView.ExitFullScreenMode, aby wyjść z trybu pełnoekranowego aplikacji. Korzystając z prezenterów, możesz wyłączyć tryb pełnoekranowy dla aplikacji, ustawiając prezenter z powrotem na standardowy przy użyciu AppWindow.SetPresenter.

Aby uzyskać więcej informacji na temat pracy z prezenterami okien aplikacji, zobacz przykład galerii okien. Pokazuje on, jak przełączać różne stany prezentera okien aplikacji.

Niestandardowy pasek tytułu

Jeśli aplikacja używa domyślnego paska tytułu, podczas migracji do win32 nie jest wymagana żadna dodatkowa praca paska tytułu. Natomiast jeśli aplikacja UWP ma niestandardowy pasek tytułu, możliwe jest odtworzenie następujących scenariuszy w aplikacji Windows App SDK.

1. Dostosowywanie paska tytułu rysowanego przez system
2. Niestandardowy pasek tytułu rysowany przez aplikację

Kod korzystający z platformy UWP ApplicationViewTitleBar, CoreApplicationViewTitleBari klasy AppWindowTitleBar migruje do użycia klasy Zestawu SDK Aplikacji Windows Microsoft.UI.Windowing.AppWindowTitleBar.

Dostosowywanie paska tytułu rysowanego przez system

Oto tabela interfejsów API dostosowywania kolorów.

Te interfejsy API zestawu SDK aplikacji Microsoft Windows pozwalają na dalsze dostosowywanie paska tytułu rysowanego przez system, oprócz interfejsu API AppWindow.Title.

• AppWindow.SetIcon. Ustawia obraz ikony na pasku tytułu i pasku zadań, korzystając z uchwytu hIcon lub ścieżki do ciągu prowadzącej do zasobu lub pliku.
• AppWindowTitleBar.IconShowOptions. Pobiera lub ustawia wartość określającą sposób wyświetlania ikony okna na pasku tytułu. Obsługuje obecnie dwie wartości — HideIconAndSystemMenu i ShowIconAndSystemMenu.
• AppWindowTitleBar.ResetToDefault. Resetuje bieżący pasek tytułu z powrotem do ustawień domyślnych okna.

Niestandardowy pasek tytułu rysowany przez aplikację (pełne dostosowywanie)

Jeśli przeprowadzasz migrację do korzystania z AppWindowTitleBar, zalecamy sprawdzenie AppWindowTitleBar.IsCustomizationSupported w swoim kodzie przed wywołaniem następujących niestandardowych interfejsów API paska tytułu.

Te interfejsy API zestawu SDK aplikacji systemu Windows umożliwiają dostosowywanie pełnego paska tytułu.

• AppWindowTitleBar.SetDragRectangles. Ustawia obszary przeciągania dla okna.
• AppWindowTitleBar.ResetToDefault. Resetuje bieżący pasek tytułu z powrotem do ustawień domyślnych okna.

Te interfejsy API UWP AppWindow nie mają bezpośredniego mapowania 1:1 na interfejsy API SDK aplikacji Windows.

• AppWindowTitleBarVisibility. Definiuje stałe określające preferowaną widoczność AppWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Pobiera preferowany tryb widoczności paska tytułu.
• AppWindowTitleBar.SetPreferredVisibility. Ustawia preferowany tryb widoczności paska tytułu.

Aby uzyskać więcej informacji na temat pracy z AppWindowTitleBar, zobacz przykładową galerię okien . Pokazuje on, jak utworzyć niestandardowy pasek tytułu koloru i jak narysować niestandardowy pasek tytułu.

Obsługa zdarzeń

Jeśli aplikacja platformy UWP używa zdarzenia AppWindow.Changed , możesz przeprowadzić migrację tego kodu do zdarzenia Microsoft.UI.Windowing.AppWindow.Changed .

Zmiana rozmiaru zdarzenia

Podczas migrowania kodu obsługującego zdarzenia zmiany rozmiaru, należy przełączyć się na korzystanie z właściwości AppWindowChangedEventArgs.DidSizeChange w Windows App SDK . Wartość to true , jeśli rozmiar okna aplikacji uległ zmianie, w przeciwnym razie jest to false.

MainPage i MainWindow

Podczas tworzenia nowego projektu platformy UWP w programie Visual Studio szablon projektu udostępnia klasę MainPage . W przypadku aplikacji możesz zmienić nazwę tej klasy (lub dodać więcej stron i kontrolek użytkownika). Szablon projektu zawiera również kod nawigacji w metodach klasy App.

Podczas tworzenia nowego projektu zestawu SDK aplikacji systemu Windows w programie Visual Studio szablon projektu udostępnia klasę MainWindow (typu Microsoft.UI.Xaml.Window), ale nie page. Szablon projektu nie udostępnia żadnego kodu nawigacyjnego.

Istnieje jednak możliwość dodawania stron i kontrolek użytkownika do projektu zestawu SDK aplikacji systemu Windows. Można na przykład dodać nowy element strony do projektu (WinUI>Pusta strona (WinUI 3)), i nadać mu nazwę MainPage.xaml, lub jakąś inną nazwę. Spowoduje to dodanie do projektu nowej klasy typu Microsoft.UI.Xaml.Controls.Page. Następnie, aby uzyskać informacje na temat dodawania kodu nawigacji do projektu, zobacz Czy muszę zaimplementować nawigację po stronie?.

W przypadku aplikacji Windows App SDK, które są na tyle proste, nie musisz tworzyć stron ani kontrolek użytkownika. Możesz skopiować swoje znaczniki XAML i kod zaplecza do MainWindow. Aby uzyskać informacje o wyjątkach od tego przepływu pracy, zobacz Visual State Manager i Page.Resources.

Zmień element CoreWindow.Dispatcher na Window.DispatcherQueue

Niektóre przypadki użycia windows.UI.Core.CoreWindow klasy platformy UWP są migrowane do microsoft.UI.Xaml.Window zestawu SDK aplikacji systemu Windows.

Jeśli na przykład używasz właściwości Windows.UI.Core.CoreWindow.Dispatcher w aplikacji platformy UWP, rozwiązanie nie jest przeprowadzić migrację do właściwości Microsoft.UI.Xaml.Window.Dispatcher (która zawsze zwraca wartość null). Zamiast tego należy przeprowadzić migrację do właściwości Microsoft.UI.Xaml.Window.DispatcherQueue, która zwraca Microsoft.UI.Dispatching.DispatcherQueue.

Aby uzyskać więcej informacji oraz przykłady kodu, zobacz Change Windows.UI.Core.CoreDispatcher to Microsoft.UI.Dispatching.DispatcherQueue.

Tematy pokrewne

• Zestaw SDK aplikacji systemu Windows i obsługiwane wersje systemu Windows
• Migruj swoją funkcjonalność wątkową