Zarządzanie oknami aplikacji

Zestaw SDK aplikacji systemu Windows udostępnia klasę Microsoft.UI.WindowingAppWindow , która reprezentuje abstrakcję wysokiego poziomu HWND. W aplikacji istnieje mapowanie wartości 1:1 między elementem AppWindow a HWND najwyższego poziomu. AppWindow i powiązane z nim klasy udostępniają interfejsy API, które umożliwiają zarządzanie wieloma aspektami okien najwyższego poziomu aplikacji bez konieczności bezpośredniego uzyskiwania dostępu do HWND.

Uwaga / Notatka

W tym artykule pokazano, jak używać AppWindow interfejsów API w aplikacji. Zalecamy, aby jako wymóg wstępny przeczytać i zrozumieć AppWindow informacje zawarte w Omówieniu systemu okienkowego dla WinUI i Windows App SDK, które mają zastosowanie niezależnie od tego, czy korzystasz z WinUI, czy innego systemu interfejsu użytkownika.

• Ważne interfejsy API: AppWindow klasa, Klasa OverlappedPresenter

Otwórz aplikację Galeria WinUI 3 i zobacz AppWindow w akcji

Aplikacja Galeria WinUI 3 zawiera interaktywne przykłady większości kontrolek, funkcji i funkcji interfejsu WinUI 3. Pobierz aplikację ze Sklepu Microsoft lub pobierz kod źródłowy w witrynie GitHub

Interfejsów API można używać z dowolną AppWindow strukturą interfejsu użytkownika obsługiwaną przez Windows App SDK — WinUI 3, WPF, WinForms lub Win32. AppWindow Interfejsy API działają obok interfejsów API okien specyficznych dla platformy:

• XAML Window
• WPF Window
• Formularz formularzy systemu Windows
• Interfejsy API okien Win32, MFC Windows

Zazwyczaj używasz interfejsów API AppWindow do:

• Zarządzaj rozmiarem i położeniem okna aplikacji.

• Zarządzanie tytułem okna, ikoną i kolorem paska tytułu; lub utwórz w pełni niestandardowy pasek tytułu za pomocą interfejsów API AppWindowTitleBar .

  Aby uzyskać więcej informacji i przykładów, zobacz Dostosowywanie paska tytułu .

• Zarządzaj wyglądem i zachowaniem okna za pomocą interfejsów API wywodzących się z AppWindowPresenter.

Reagowanie na AppWindow zmiany

Reagujesz na zmiany AppWindow przez obsługę pojedynczego zdarzenia Zmienione , a następnie sprawdzasz args zdarzeń (AppWindowChangedEventArgs), aby określić, jakiego rodzaju zmiany wystąpiły. Jeśli zmiana, która cię interesuje, miała miejsce, możesz na nią odpowiedzieć. Potencjalne zmiany obejmują pozycje, rozmiar, prezenter, widoczność i kolejność z.

Oto przykład procedury obsługi zdarzenia AppWindow.Changed.

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    // ConfigText and SizeText are TextBox controls defined in XAML for the page.
    if (args.DidPresenterChange == true)
    {
        ConfigText.Text = sender.Presenter.Kind.ToString();
    }

    if (args.DidSizeChange == true)
    {
        SizeText.Text = sender.Size.Width.ToString() + ", " + sender.Size.Height.ToString();
    }
}

Window rozmiar i położenie

Klasa AppWindow ma kilka właściwości i metod, których można użyć do zarządzania rozmiarem i rozmieszczeniem okna.

Kategoria	Właściwości
Właściwości tylko do odczytu	Pozycja, rozmiar, rozmiar klienta
Events	Zmieniono (DidPositionChange, DidSizeChange)
Metody rozmiaru i położenia	Move, Resize, ResizeClient, MoveAndResize
Metody kolejności Z	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Wywołaj metodę Zmień rozmiar, aby określić nowy rozmiar okna.

W tym przykładzie kod znajduje się w MainWindow.xaml.cs, więc możesz użyć właściwości Window.AppWindow, aby uzyskać instancję AppWindow.

public MainWindow()
{
    InitializeComponent();
    AppWindow.Resize(new Windows.Graphics.SizeInt32(1200, 800));
}

Wywołaj metodę Move , aby zmienić położenie okna.

W tym przykładzie okno zostanie wyśrodkowane na ekranie, gdy użytkownik kliknie przycisk.

Dzieje się tak w pliku kodu dla klasy Page , więc nie masz automatycznie dostępu do Window obiektów lub AppWindow . Istnieje kilka opcji pobierania pliku AppWindow.

• Jeśli zachowasz odwołanie do obiektu Window zgodnie z opisem w sekcji Śledzenie bieżącego okna lub Śledź wystąpienia elementu Window, możesz pobrać element Window, a następnie pobrać AppWindow z właściwości Window.AppWindow
• Możesz też wywołać statyczną metodę AppWindow.GetFromWindowId, aby uzyskać wystąpienie AppWindow, jak pokazano tutaj. (Zobacz Określanie okna obsługującego element wizualizacji).

private void MoveWindowButton_Click(object sender, RoutedEventArgs e)
{
    AppWindow appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    RectInt32? area = DisplayArea.GetFromWindowId(appWindow.Id, DisplayAreaFallback.Nearest)?.WorkArea;
    if (area == null) return;
    appWindow.Move(new PointInt32((area.Value.Width - appWindow.Size.Width) / 2, (area.Value.Height - appWindow.Size.Height) / 2));
}

Klasa AppWindowPresenter i podklasy

Każdy AppWindow z nich ma zastosowany element AppWindowPresenter (prezenter). Prezenter jest tworzony przez system i stosowany do elementu AppWindow w momencie tworzenia. Każda podklasa appWindowPresenter zapewnia wstępnie zdefiniowaną konfigurację odpowiednią dla celu okna. Te prezentery pochodne appWindowPresenter są udostępniane i są dostępne we wszystkich obsługiwanych wersjach systemu operacyjnego.

• CompactOverlayPresenter

  Konfiguruje zawsze na wierzchu okno o stałym rozmiarze z współczynnikiem proporcji 16:9, aby umożliwić doświadczenia w stylu obraz-w-obrazie. Domyślnie parametr InitialSize to CompactOverlaySize.Small, ale można go zmienić na Medium lub Large. Możesz również wywołać metodę AppWindow. Zmień rozmiar , aby zastąpić współczynnik proporcji 16:9 i zmienić rozmiar okna.

• FullScreenPresenter

  Konfiguruje okno, aby zapewnić środowisko pełnoekranowe odpowiednie do oglądania wideo. Okno nie ma obramowania ani paska tytułu i ukrywa pasek zadań systemowych.

• Nakładające siępresenter

  Konfiguracja okna standardowego, która domyślnie zapewnia obramowanie z uchwytami zmiany rozmiaru i paskiem tytułu z przyciskami minimalizowania/maksymalizowania/przywracania.

Uwaga / Notatka

Jako nowy koncept w modelu aplikacji Win32, prezenter jest podobny do (ale nie taki sam jak) kombinacji stanu okna i stylów. Niektórzy prezenterzy mają również zdefiniowane w nich zachowania, których nie można sprawdzić z poziomu klasycznego stanu okna i właściwości stylu (takich jak automatyczne ukrywanie paska tytułu).

Domyślny prezenter

Domyślny prezenter stosowany, gdy tworzony jest AppWindow, jest instancją OverlappedPresenter z domyślnymi ustawieniami właściwości. Nie ma potrzeby zachowywania odwołania do niego w celu powrotu do domyślnego prezentera dla okna po zastosowaniu innego prezentera. Dzieje się tak dlatego, że system przechowuje to samo wystąpienie tego prezentera przez cały okres istnienia AppWindow, dla którego został utworzony; i można go ponownie zastosować, wywołując metodę AppWindow.SetPresenter z parametrem AppWindowPresenterKind.Default.

Ważne

Wywołanie SetPresenter(AppWindowPresenterKind.Default) zawsze stosuje ponownie domyślne wystąpienie prezentera, które jest tworzone za pomocą elementu AppWindow. Jeśli utworzysz i zastosujesz innego prezentera i chcesz go ponownie zastosować później, musisz zachować odwołanie do prezentera.

Możesz również uzyskać referencję do domyślnego wystąpienia prezentera i zmodyfikować je. Jeśli zastosowano nowy prezenter, najpierw upewnij się, że domyślny prezenter jest stosowany, jak pokazano poniżej:

appWindow.SetPresenter(AppWindowPresenterKind.Default);
OverlappedPresenter defaultPresenter = (OverlappedPresenter)appWindow.Presenter;
defaultPresenter.IsMaximizable = false;
defaultPresenter.IsMinimizable = false;

Modyfikowanie nakładającego się elementuPresenter

Nakładający siępresenter to elastyczny prezenter, który można skonfigurować na różne sposoby.

CreateMetody * umożliwiają utworzenie nakładającego się prezentera z domyślnymi ustawieniami właściwości lub z ustawieniami właściwości wstępnie skonfigurowanymi do określonego użycia.

W tej tabeli przedstawiono sposób ustawiania właściwości konfiguracji podczas tworzenia obiektu OverlappedPresenter z każdej metody.

Majątek	Create	CreateForContextMenu	CreateForDialog	CreateForToolWindow
HasBorder	true	true	true	true
HasTitleBar	true	false	true	true
IsAlwaysOnTop	false	false	false	false
IsMaximizable	true	false	false	true
IsMinimizable	true	false	false	true
IsModal	false	false	false	false
IsResizable	true	false	false	true

Zastosowany prezenter jest aktywnym obiektem. Zmiana dowolnej właściwości obiektu AppWindow.Presenter wchodzi w życie natychmiast. Nie ma zdarzeń powiadamiających o tych zmianach, ale można sprawdzić bieżące wartości właściwości w dowolnym momencie.

Właściwości HasBorder i HasTitleBar są tylko do odczytu. Te wartości można ustawić, wywołując metodę SetBorderAndTitleBar (SetBorderAndTitleBar(bool hasBorder, bool hasTitleBar)). OverlappedPresenter nie może mieć paska tytułu bez obramowania. Oznacza to, że jeśli hasTitleBar parametr ma truewartość , hasBorder parametr musi również mieć wartość true. W przeciwnym razie zostanie zgłoszony wyjątek z tym komunikatem:

The parameter is incorrect.
Invalid combination: Border=false, TitleBar=true.

Ustaw IsMaximizable na false, aby ukryć przycisk maksymalizacji na pasku narzędzi. Zalecamy wykonanie tej czynności, jeśli ustawisz właściwości PreferredMaximumHeight lub PreferredMaximumWidth, ponieważ te właściwości ograniczają rozmiar okna nawet w stanie zmaksymalizowania. Nie ma to wpływu na wywołania metody Maximize .

Aby ukryć przycisk minimalizowania na pasku narzędzi, ustaw IsMinimizable na false. Nie ma to wpływu na wywołania metody Minimal .

Ustaw wartość IsResizable , aby false ukryć kontrolki zmiany rozmiaru i uniemożliwić użytkownikowi zmianę rozmiaru okna. Nie ma to wpływu na wywołania metody AppWindow.Resize.

Ustaw IsAlwaysOnTop na true, aby to okno było zawsze na wierzchu innych okien. Jeśli wywołasz dowolną z AppWindow.MoveInZOrder* metod, nadal zostaną zastosowane do zmiany kolejności okna, nawet jeśli ta właściwość jest true.

Ustaw wartości PreferredMaximumHeight i PreferredMaximumWidth, aby ograniczyć maksymalny rozmiar, do którego użytkownik może rozciągnąć okno. Zalecamy ustawienie na w przypadku ustawienia właściwości maksymalnego rozmiaru, ponieważ te właściwości ograniczają maksymalny rozmiar okna nawet w stanie zmaksymalizowanym. Te właściwości mają również wpływ na wywołania funkcji AppWindow. Zmień rozmiar; rozmiar okna nie będzie większy niż określona maksymalna wysokość i szerokość.

Ustaw PreferredMinimumHeight i PreferredMinimumWidth, aby określić minimalny rozmiar, do którego użytkownik może zmniejszyć okno. Te właściwości mają również wpływ na wywołania funkcji AppWindow. Zmień rozmiar; rozmiar okna nie będzie mniejszy niż określona minimalna wysokość i szerokość.

Modalne okna

Możesz ustawić IsModal jako true , aby utworzyć modalne okno. Modalne okno to oddzielne okno, które blokuje interakcję z oknem właściciela , dopóki nie zostanie zamknięte. Jednak aby utworzyć modalne okno, należy również ustawić okno właściciela; w przeciwnym razie zostanie zgłoszony wyjątek z następującym komunikatem:

The parameter is incorrect.

The window should have an owner when IsModal=true.

Aby ustawić okno właściciela w aplikacji WinUI, konieczne jest użycie współdziałania z Win32. Aby uzyskać więcej informacji i przykładowy kod, zobacz stronę AppWindow w przykładowej aplikacji Galeria WinUI.

• Uruchamianie aplikacji z galerii WinUI
• Otwieranie ModalWindow.xaml.cs w usłudze GitHub

Zastosuj prezentera

Prezenter może być stosowany tylko do jednego okna w danym momencie. Próba zastosowania tego samego prezentera do drugiego okna powoduje wystąpienie wyjątku. Oznacza to, że jeśli masz wiele okien i chcesz przełączyć każdy z nich do określonego trybu prezentacji, musisz utworzyć wiele prezenterów tego samego rodzaju, a następnie zastosować każdy z nich do własnego okna.

Po zastosowaniu nowego prezentera (zmiana właściwości AppWindow.Presenter), aplikacja jest powiadamiana przez zdarzenie AppWindow.Changed na odpowiednim AppWindow, z właściwością AppWindowChangedEventArgs.DidPresenterChange ustawioną na true.

Wskazówka

Jeśli zastosujesz zmodyfikowany prezenter i zezwolisz na zmianę między prezenterami, pamiętaj, aby zachować odwołanie do zmodyfikowanego prezentera, aby można było go ponownie zastosować do elementu AppWindow.

W tym przykładzie pokazano, jak wykonać następujące czynności:

• Użyj właściwości AppWindow.Presenter, aby pobrać bieżącego prezentera.
• Użyj właściwości AppWindowPresenter.Kind , aby sprawdzić, jakiego rodzaju konfiguracja jest obecnie stosowana.
• Wywołaj AppWindow.SetPresenter, aby zmienić bieżącą konfigurację.

Tutaj prezenter jest tworzony, modyfikowany i używany w konstruktorze okna.

OverlappedPresenter presenter = OverlappedPresenter.Create();
presenter.PreferredMinimumWidth = 420;
presenter.PreferredMinimumHeight = 550;
AppWindow.SetPresenter(presenter);

Na stronie , która jest zawartością okna, możesz uzyskać odwołanie do AppWindow i zastosowanego prezentera.

AppWindow appWindow;
OverlappedPresenter modifiedPresenter;

private void AppWindowPage_Loaded(object sender, RoutedEventArgs e)
{
    appWindow = AppWindow.GetFromWindowId(XamlRoot.ContentIslandEnvironment.AppWindowId);
    modifiedPresenter = (OverlappedPresenter)appWindow.Presenter;

    appWindow.Changed += AppWindow_Changed;
}

private void AppWindow_Changed(AppWindow sender, AppWindowChangedEventArgs args)
{
    if (args.DidPresenterChange)
    {
        // ConfigText is a TextBox control defined in XAML for the page.
        ConfigText.Text = appWindow.Presenter.Kind.ToString();
    }
}

private void CompactOverlayButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.CompactOverlay)
    {
        appWindow.SetPresenter(CompactOverlayPresenter.Create());
        fullScreenButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

private void FullScreenButton_Click(object sender, RoutedEventArgs e)
{
    if (appWindow.Presenter.Kind != AppWindowPresenterKind.FullScreen)
    {
        appWindow.SetPresenter(FullScreenPresenter.Create());
        compactOverlayButton.IsChecked = false;
    }
    else
    {
        appWindow.SetPresenter(modifiedPresenter);
    }
}

Platforma interfejsu użytkownika i interoperacyjność HWND

Klasa AppWindow jest dostępna dla dowolnego najwyższego poziomu HWND w aplikacji. Oznacza to, że podczas pracy z platformą interfejsu użytkownika pulpitu (w tym WinUI 3) możesz nadal używać punktu wejścia tej platformy do tworzenia okna i dołączania jego zawartości. Po utworzeniu okna za pomocą tego frameworka interfejsu użytkownika możesz użyć funkcji międzyoperacyjnych okien (patrz poniżej) dostępnych w ramach Windows App SDK, aby uzyskać dostęp do odpowiednich AppWindow oraz jego metod, właściwości i zdarzeń.

Niektóre korzyści wynikające z używania AppWindow (nawet w przypadku pracy z platformą interfejsu użytkownika) to:

• Łatwe dostosowywanie paska tytułu; które domyślnie zachowuje interfejs użytkownika systemu Windows 11 (zaokrąglone rogi, wysuwane menu grupy przyciągania).
• Zapewniana przez system pełnoekranowa i kompaktowa nakładka (obraz na obrazie).
• Powierzchnia interfejsu API środowiska Uruchomieniowego systemu Windows (WinRT) dla niektórych podstawowych pojęć związanych z oknem Win32.

Pobierz AppWindow dla wersji zestawu Windows App SDK starszych niż 1.3 (lub innych platform aplikacji komputerowych)

Właściwość Window.AppWindow jest dostępna w zestawie SDK aplikacji systemu Windows w wersji 1.3 lub nowszej. W przypadku wcześniejszych wersji można użyć przykładu kodu równoważnego funkcjonalnie w tej sekcji.

C#. Otoki platformy .NET dla funkcji międzyoperacyjnych okien są implementowane jako metody klasy Microsoft.UI.Win32Interop . Zobacz również Wywoływanie międzyoperacyjnych interfejsów API z poziomu aplikacji platformy .NET.

C++. W pliku nagłówka winrt/Microsoft.ui.interop.h zdefiniowano funkcje międzyoperacyjne.

W poniższej sekcji przykładowej kodu przedstawiono rzeczywisty kod źródłowy; ale oto przepis na pobieranie AppWindow obiektu przy użyciu istniejącego okna:

1. Pobierz HWND dla istniejącego obiektu okna (dla frameworka interfejsu użytkownika), jeśli jeszcze go nie posiadasz.
2. Przekaż ten HWND do funkcji międzyoperacyjnej GetWindowIdFromWindow, aby pobrać WindowId.
3. Przekaż ten WindowId do statycznej metody AppWindow.GetFromWindowId, aby pobrać AppWindow.

// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    var hWnd =
        WinRT.Interop.WindowNative.GetWindowHandle(this);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft.UI.WindowId windowId =
        Microsoft.UI.Win32Interop.GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow =
        Microsoft.UI.Windowing.AppWindow.GetFromWindowId(windowId);

    if (appWindow != null)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title = "Title text updated via AppWindow!";
    }
}

// pch.h
#include "microsoft.ui.xaml.window.h" // For the IWindowNative interface.
#include <winrt/Microsoft.UI.Interop.h> // For the WindowId struct and the GetWindowIdFromWindow function.
#include <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the window handle (HWND) of the current (XAML) WinUI 3 window.
    auto windowNative{ this->m_inner.as<::IWindowNative>() };
    HWND hWnd{ 0 };
    windowNative->get_WindowHandle(&hWnd);

    // Retrieve the WindowId that corresponds to hWnd.
    Microsoft::UI::WindowId windowId = 
        Microsoft::UI::GetWindowIdFromWindow(hWnd);

    // Lastly, retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = 
        Microsoft::UI::Windowing::AppWindow::GetFromWindowId(windowId);

    if (appWindow)
    {
        // You now have an AppWindow object, and you can call its methods to manipulate the window.
        // As an example, let's change the title text of the window.
        appWindow.Title(L"Title text updated via AppWindow!");
    }
}

Aby uzyskać więcej przykładów pracy z AppWindow, zobacz przykład galerii z okienkowym interfejsem.

Ograniczenia

Zestaw SDK aplikacji systemu Windows nie udostępnia obecnie metod dołączania zawartości struktury interfejsu użytkownika do elementu AppWindow.

Tematy pokrewne

• Omówienie okien
• Dostosowywanie paska tytułu
• migracja funkcji okien
• Wywoływanie interfejsów API międzyoperacyjnych z poziomu aplikacji .NET
• Pobierz uchwyt okna (HWND)
• przykładowa galerii okien