Udostępnij przez

Omówienie okien dla interfejsu WinUI i Windows zestawu SDK aplikacji

Funkcje obsługi okien w aplikacji WinUI są udostępniane przez kombinację klasy XAML Window i AppWindow klasy, z których oba są oparte na modelu Win32 HWND.

Otwórz aplikację Galeria WinUI 3 i zobacz Przykłady obsługi okien 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

XAML Window

W aplikacji obiekt okna jest wystąpieniem klasy Microsoft.UI.Xaml.Window (lub klasy pochodnej), która reprezentuje okno w kodzie programu. Tworzy się go bezpośrednio za pomocą wywołania konstruktora. Język XAML Window to miejsce, w którym dołączasz zawartość aplikacji i zarządzasz cyklem życia okien aplikacji.

HWND

Okno aplikacji jest tworzone przez Windows system operacyjny i jest reprezentowane przez obiekt okna Win32. Jest to kontener zarządzany przez system, w którym jest hostowana zawartość, i reprezentuje jednostkę, z którą użytkownicy wchodzą w interakcję po zmianie rozmiaru i przeniesieniu aplikacji na ekranie. (See About Windows w dokumentacji Win32, aby uzyskać więcej informacji.)

Po tym, jak Windows utworzy okno aplikacji, funkcja tworzenia zwraca wartość window handle (HWND), która jednoznacznie identyfikuje okno. Element window handle ma typ danych HWND, chociaż jest on uwidocznieny w języku C# jako intPtr. Jest to nieprzezroczyste dojście do wewnętrznej Windows struktury danych, która odpowiada oknu, które jest rysowane przez system operacyjny i zużywa zasoby systemowe, gdy jest obecne.

HWND jest tworzony po obiekcie XAML Window, zazwyczaj gdy wywoływana jest metoda Window.Activate.

AppWindow

Zestaw Windows SDK aplikacji udostępnia dodatkowe funkcje obsługi okien za pośrednictwem klasy Microsoft.UI.Windowing.AppWindow AppWindow reprezentuje wysoki poziom abstrakcji 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.

Okres istnienia AppWindow obiektu i HWND jest taki sam — AppWindow jest dostępny natychmiast po utworzeniu okna i jest niszczony po zamknięciu okna.

Diagram interfejsu API okien

Na tym diagramie przedstawiono relację między klasami i interfejsami API używanymi do zarządzania oknami w aplikacji oraz klasami odpowiedzialnymi za każdą część zarządzania oknami. W niektórych przypadkach, takich jak ExtendsContentIntoTitleBar, API jest członkiem AppWindow, aby udostępnić go innym frameworkom interfejsu użytkownika, ale również występuje w klasie Window dla wygody. Diagram nie jest kompleksowy, ale przedstawia najczęściej używane interfejsy API.

Diagram okien win u i

Uwaga / Notatka

Można używać interfejsów API AppWindow z dowolną strukturą interfejsu użytkownika obsługiwaną przez SDK aplikacji Windows — Win32, WPF, WinForms lub WinUI 3. W przypadku struktur innych niż WinUI 3 funkcje przedstawione w polu XAML Window diagramu zostaną zastąpione przez odpowiednie interfejsy API okien specyficzne dla platformy:

Window/AppWindow Porównanie interfejsu API

Jeśli używasz XAML WinUI 3 jako struktury interfejsu użytkownika aplikacji, masz dostęp do obu interfejsów API: Window i AppWindow. Od wersji Windows App SDK 1.4, można użyć właściwości Window.AppWindow w celu pobrania obiektu AppWindow z istniejącego okna XAML. Za pomocą tego AppWindow obiektu masz dostęp do dodatkowych interfejsów API do zarządzania oknami.

Ważne

Jeśli nie używasz WinUI 3 w wersji 1.3 lub późniejszej, użyj API międzyoperacyjnych, aby uzyskać dostęp do API AppWindow. Aby uzyskać więcej informacji na temat interfejsów API interoperacyjności, zobacz Zarządzanie oknami aplikacji — struktura interfejsu użytkownika i interoperacyjność HWND oraz przykładowe rozwiązanie galerii okien .

Zarządzanie okresem istnienia

XAML Window AppWindow
Constructor Tworzenie, GetFromWindowId
Activate Pokaż, Ukryj
Zamknij, zamknięte Niszczenie, niszczenie, zamykanie
>>> Id, OwnerWindowId

Podczas tworzenia nowego projektu WinUI w programie Visual Studio szablon projektu udostępnia klasę MainWindow dla ciebie, która jest podrzędną klasą Window. Jeśli aplikacja potrzebuje tylko jednego okna, to wszystko, czego potrzebujesz. Aby dowiedzieć się, jak tworzyć dodatkowe okna i zarządzać nimi oraz dlaczego warto, zobacz Wyświetlanie wielu okien dla aplikacji.

Klasa ma interfejsy API do tworzenia i niszczenia nowego okna. Jednak AppWindow w przypadku aplikacji WinUI nie zrobisz tego w praktyce, ponieważ nie ma interfejsu API do dołączania zawartości do utworzonego okna. Zamiast tego uzyskasz wystąpienie AppWindow utworzone przez system i skojarzone z XAML Window i HWND. W WinUI 1.4 lub nowszym można użyć właściwości .WindowAppWindow w celu uzyskania instancji AppWindow. W innych przypadkach można użyć statycznej metody AppWindow.GetFromWindowId, aby uzyskać wystąpienie AppWindow. Aby uzyskać więcej informacji, zobacz Zarządzanie oknami aplikacji .

Content

XAML Window AppWindow
Content N/A

Właściwość Window.Content to miejsce, gdzie dołączasz zawartość swojej aplikacji do okna, które ją wyświetla. Można to zrobić w języku XAML lub w kodzie.

Tytuł, ikona i pasek tytułu

XAML Window AppWindow
Tytuł Tytuł
SetTitleBar TitleBar
>>> SetIcon, SetTaskbarIcon, SetTitleBaricon
ExtendsContentIntoTitleBar AppWindow. TitleBar.ExtendsContentIntoTitleBar

Możesz zmodyfikować pasek tytułu aplikacji w różny stopień; ustawianie tytułu i ikony, zmienianie kolorów lub całkowite zastępowanie paska tytułu niestandardową zawartością aplikacji.

Aby uzyskać informacje na temat używania interfejsów API paska tytułu, w tym przykładów kodu, zobacz Dostosowywanie paska tytułu.

Rozmiar i położenie

XAML Window AppWindow
Granice Pozycja, rozmiar, rozmiar klienta
SizeChanged Zmieniono (DidPositionChange, DidSizeChange)
>>> Move, Resize, ResizeClient, MoveAndResize
>>> MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Należy użyć właściwości Window.Bounds i zdarzenia SizeChanged do zarządzania elementami w interfejsie użytkownika aplikacji, takimi jak przesuwanie elementów po zmianie rozmiaru okna. XAML używa effective pixels (epx), a nie rzeczywistych pikseli fizycznych. Effective pixels to wirtualna jednostka miary, która służy do wyrażania wymiarów i odstępów układu niezależnie od gęstości ekranu.

AppWindowz drugiej strony używa Window układu współrzędnych, w którym podstawową jednostką miary są piksele urządzenia fizycznego. Używasz AppWindow API do akcji związanych z oknami, takich jak zmiana rozmiaru okna lub przesuwanie go względem innego elementu na ekranie.

W niektórych przypadkach może być konieczne użycie pomiarów z jednej klasy w innej klasie, w takim przypadku konieczne będzie przeliczenie pomiędzy pikselami effective pixels a pikselami urządzenia. Jeśli na przykład ustawisz regiony przeciągania na niestandardowym pasku tytułu, musisz przekonwertować miary. Aby zapoznać się z przykładem użycia elementu XamlRoot.RasterizationScale do konwertowania miar, zobacz sekcję interaktywną zawartości artykułu dostosowywania paska tytułu .

Wygląd i zachowanie

XAML Window AppWindow
SystemBackdrop N/A
>>> Prezenter, SetPresenter
>>> IsShownInSwitchers
Widoczne, WidocznośćZmień IsVisible, zmieniono (DidVisibilityChange)
DispatcherQueue DispatcherQueue, AssociateWithDispatcherQueue
Compositor N/A

API XAML Window są zazwyczaj odpowiedzialne za wygląd zawartości aplikacji, na przykład tła. Aby uzyskać więcej informacji na temat elementu SystemBackdrop, zobacz Stosowanie micy lub materiałów akrylowych.

AppWindow Interfejsy API są odpowiedzialne za część okna inną niż klient i interakcję aplikacji z Windows systemem operacyjnym.

Uwaga / Notatka

Klasa XAML Window zawiera kilka właściwości przeniesionych z klasy UWP Windows.UI.Xaml.Window, ale te właściwości nie są obsługiwane w aplikacjach WinUI. Te właściwości zawsze mają null wartość i nie są używane w aplikacjach WinUI: CoreWindow, Currenti Dispatcher.

Śledzenie bieżącego okna

Mimo że właściwość Current nie jest obsługiwana w aplikacjach WinUI, nadal może być konieczne uzyskanie dostępu do interfejsów API Window z innych miejsc w aplikacji. Na przykład może być konieczne pobranie Window granic lub obsłużenie zdarzenia Window.SizeChanged w kodzie dla Page. W takim przypadku możesz zapewnić dostęp do Window w sposób podobny jak do właściwości Current, używając publicznej statycznej właściwości w klasie App.

W tym celu zmodyfikuj deklarację Window w klasie App, jak pokazano tutaj.

// App.xaml.cs in a WinUI app
public partial class App : Application
{
    ...
    public static Window Window { get { return m_window; } }
    private static Window m_window;
}

// App.xaml.h in a WinUI app
...
struct App : AppT<App>
{
    ...
    static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };

private:
    static winrt::Microsoft::UI::Xaml::Window window;
};
...

// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...

Następnie, aby uzyskać dostęp do Window obiektu z innych miejsc w aplikacji, użyj polecenia App.Window, w następujący sposób:

// MainPage.xaml.cs in a WinUI app
var width = App.Window.Bounds.Width;

// MainPage.xaml.cpp in a WinUI app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };

Ważne

Użycie właściwości statycznej Window w App klasie jest przydatne, jeśli aplikacja używa tylko jednego okna. Jeśli aplikacja używa wielu okien, należy użyć identyfikatora WindowId do śledzenia instancji Window, aby upewnić się, że uzyskujesz dostęp do poprawnego Window wystąpienia. Aby uzyskać więcej informacji i przykładów, zobacz Show multiple windows for your app (Pokaż wiele okien dla aplikacji ).

  • Last updated on