Verwalten von App-Fenstern (Windows App SDK)

  • Artikel

Dieser Abschnitt enthält den Abschnitt Codebeispiel.

Das Windows App SDK stellt die benutzerfreundliche Microsoft.UI.Windowing.AppWindow-Klasse bereit. AppWindow ist framework-agnostisch und für alle Windows-Apps einschließlich Win32, WPF und WinForms verfügbar. Sie können die framework-agnostische Natur von AppWindow zu Microsoft.UI.Xaml.Window kontrastieren. Dies ist die Fensterklasse speziell für das WinUI 3-Framework. AppWindow ist auch eine Weiterentwicklung der Windows.UI.WindowManagement.AppWindow der universellen Windows-Plattform (UWP).

Die Windows App SDK-Version von Microsoft.UI.Windowing.AppWindow basiert nicht auf asynchronen Mustern, und sie gibt Ihrer App sofortiges Feedback darüber, ob API-Aufrufe erfolgreich waren.

Siehe auch Installieren von Tools für das Windows App SDK, Erstellen Ihres ersten WinUI 3-Projekts und Verwenden des Windows App SDK in einem bestehenden Projekt.

Die AppWindow-Klasse

Microsoft.UI.Windowing.AppWindow ist eine allgemeine Fenster-API, die benutzerfreundliche Fensterszenarien ermöglicht. AppWindow ist gut in die Windows-Benutzeroberfläche/UX und in andere Apps integriert.

AppWindow stellt eine allgemeine Abstraktion eines vom systemseitig verwalteten Containers des Inhalts einer App dar. Es ist der Container, in dem Ihre Inhalte gehostet werden, und repräsentiert die Entität, mit der Benutzer*innen interagieren, wenn sie die Größe Ihrer App ändern und Ihre App auf dem Bildschirm verschieben. Wenn Sie mit Win32 vertraut sind, können im App-Fenster als eine allgemeine Abstraktion von HWND betrachten. Wenn Sie mit UWP vertraut sind, kann das App-Fenster als Ersatz für CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow angesehen werden.

Für die Windows App SDK-Version von Microsoft.UI.Windowing.AppWindow unterstützen wir nur HWND-Elemente der obersten Ebene. Es gibt eine 1:1-Zuordnung zwischen einem AppWindow und einem HWND der obersten Ebene in Ihrer App.

Die Lebensdauer eines AppWindow-Objekts ist identisch mit der eines HWND. Das bedeutet, dass das AppWindow-Objekt unmittelbar nach dem Erstellen des Fensters verfügbar ist und beim Schließen des Fensters gelöscht wird.

Die AppWindowPresenter-Klasse und Unterklassen

Jedes AppWindow hat einen AppWindowPresenter (Presenter) zugewiesen. Wenn Sie UWP-Entwickler sind und mit Windows.UI.WindowManagement.AppWindow gearbeitet haben, ist Ihnen dies vertraut, auch wenn es sich nicht um eine 1:1-Zuordnung von Funktionalität und Verhalten handelt. Siehe auch Informationen zur Migration von Fensterfunktionen.

Als neues Konzept für das Win32-Anwendungsmodell ist ein Presenter eine Kombination aus Fensterstatus und Stilen (aber nicht dasselbe). In einigen Präsentatoren sind auch UI/UX-Verhaltensweisen definiert, die nicht über die klassischen Fensterstatus- und Stileigenschaften eingesehen werden können (z. B. eine automatisch ausgeblendete Titelleiste).

Standardmäßig wird ein Referent vom System erstellt und zum Zeitpunkt der Erstellung auf ein AppWindow angewendet. Im Windows App SDK 1.0 auf dem Windows-Desktop ist der Referenttyp OverlappedPresenter, der eine Unterklasse von AppWindowPresenter ist. Es ist nicht erforderlich, dass Ihre App sie stasht, oder einen Verweis darauf beibehalten muss, um zum Standardreferent für ein Fenster zurückzukehren, nachdem sie einen anderen Referenten angewendet haben. Der Grund dafür ist, dass das System die gleiche Instanz dieses Referenten für die Lebensdauer des AppWindow, für das es erstellt wurde, beibehalten wird. Die App kann sie erneut anwenden, indem sie die AppWindow.SetPresenter-Methode mit AppWindowPresenterKind.Default als Parameter aufruft.

Ein Referent kann jeweils nur auf ein einzelnes Fenster angewendet werden. Wenn Sie versuchen, denselben Referenten auf ein zweites Fenster anzuwenden, wird eine Ausnahme ausgelöst. Das bedeutet, dass Sie, wenn Sie mehrere Fenster haben und die einzelnen Fenster in einen bestimmten Präsentationsmodus wechseln möchten, dann müssen Sie mehrere Referenten derselben Art erstellen und dann jedes auf ein eigenes Fenster anwenden.

Einige Referenten verfügen über Funktionen, mit denen ein Benutzer Änderungen außerhalb des eigenen Steuerelements Ihrer App vornehmen kann. Wenn eine solche Änderung erfolgt, wird Ihre App über ein AppWindow.Changed-Ereignis für das betroffene AppWindow benachrichtigt, wobei die Eigenschaft AppWindowChangedEventArgs.DidPresenterChange auf true festgelegt ist. Ihre App sollte dann die Eigenschaft des angewendeten Referenten überprüfen, um zu sehen, was sich geändert hat.

Der angewendete Referent ist ein Liveobjekt. Eine Änderung an einer beliebigen Eigenschaft des AppWindow.Presenter-Objekts wird sofort wirksam.

Ein Referent kann nicht zerstört werden, während er auf ein Fenster angewendet wird. Um ein Referentenobjekt zu zerstören, wenden Sie zuerst ein anderes Referentenobjekt auf das Fenster an. auf diese Weise wird der Referent, den Sie zerstören möchten, aus dem Fenster entfernt. Dazu können Sie entweder einen anderen bestimmten Referenten auf das Fenster anwenden oder die AppWindow.SetPresenter-Methode mit AppWindowPresenterKind.Default als Argument aufrufen, das den vom System erstellten Standardreferent erneut auf das Fenster anwendet. Wenn Sie einen Verweis auf den vom System erstellten Referenten für das Fenster beibehalten haben, ist es an diesem Punkt gültig (d. h. die Instanz, die zuerst für das Fenster erstellt wurde, wird erneut angewendet).

Verfügbare Referenten

Diese von AppWindowPresenter abgeleiteten Referenten werden bereitgestellt, und sie sind in allen unterstützten Betriebssystemversionen verfügbar.

  • CompactOverlayPresenter. Erstellt ein Always-on-top-Fenster mit einer festen Größe mit einem Seitenverhältnis von 16:9, um bildähnliche Oberflächen zu ermöglichen.
  • FullScreenPresenter. Ermöglicht es einem Fenster, in eine Vollbildansicht zu wechseln.
  • OverlappedPresenter. Der vom System erstellte Standardreferent, mit dem Sie Vorgänge und Zustandsänderungen minimieren/maximieren/wiederherstellen und darauf reagieren können.

UI-Framework und HWND-Interoperabilität

Die AppWindow-Klasse ist für jedeHWND-Klasse auf oberster Ebene in Ihrer App verfügbar. Das bedeutet, dass Sie beim Arbeiten mit einem Desktop-UI-Framework (einschließlich WinUI 3) weiterhin den Einstiegspunkt dieses Frameworks zum Erstellen eines Fensters verwenden und dessen Inhalt anfügen können. Nachdem Sie ein Fenster mit diesem Benutzeroberflächenframework erstellt haben, können Sie die im Windows App SDK bereitgestellten Fensterinteropfunktionen (siehe unten) verwenden, um auf die entsprechenden AppWindow und seine Methoden, Eigenschaften und Ereignisse zuzugreifen.

Einige der Vorteile der Verwendung von AppWindow (auch beim Arbeiten mit einem UI-Framework) sind:

  • Einfache Anpassung der Titelleiste; die standardmäßig die Windows 11-Benutzeroberfläche (abgerundete Ecken, Snap Group Flyout) pflegt.
  • Systemseitige Vollbild- und kompakte Überlagerungsfunktionen (Bild in Bild).
  • Windows-Runtime (WinRT)-API-Oberfläche für einige der wichtigsten Win32-Fensterkonzepte.

Code-Beispiel

In diesem Codebeispiel wird das Abrufen eines Microsoft.UI.Windowing.AppWindow aus einem WinUI 3-Fenster mithilfe der Microsoft.UI.Xaml.Window.AppWindow-Eigenschaft veranschaulicht. Erstellen Sie zum Verwenden des Beispiels ein neues Projekt Leere App, Verpackt (WinUI 3 in Desktop), und fügen Sie den Code ein.

Weitere Informationen zum Arbeiten mit AppWindow finden Sie im Fensterkatalogbeispiel.

// MainWindow.xaml.cs
private void myButton_Click(object sender, RoutedEventArgs e)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft.UI.Windowing.AppWindow appWindow = this.AppWindow;

    if (appWindow != null)
    {
        // With a non-null AppWindow object, 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 <winrt/Microsoft.UI.Windowing.h> // For the AppWindow class.

// mainwindow.xaml.cpp
void MainWindow::myButton_Click(IInspectable const&, RoutedEventArgs const&)
{
    // Retrieve the AppWindow for the current (XAML) WinUI 3 window.
    Microsoft::UI::Windowing::AppWindow appWindow = this->AppWindow();

    if (appWindow)
    {
        // With a non-null AppWindow object, 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!");
    }
}

Codebeispiel für Versionen des Windows App SDK vor 1.3 (oder anderen Desktop-App-Frameworks)

Die Microsoft.UI.Xaml.Window.AppWindow-Eigenschaft (im obigen Codebeispiel verwendet) ist in Windows App SDK Version 1.3 und höher verfügbar. In früheren Versionen können Sie das funktionsäquivalente Codebeispiel in diesem Abschnitt verwenden.

C#. .NET-Wrapper für die Interoperabilitätsfunktionen für Fenster werden als Methoden der Microsoft.UI.Win32Interop-Klasse implementiert. Siehe auch Interop APIs von einer .NET-App aufrufen.

C++. Die Interopfunktionen werden in der Headerdatei winrt/Microsoft.ui.interop.h definiert.

Der Abschnitt Codebeispiel zeigt tatsächlichen Quellcode. Hier sehen Sie jedoch das Rezept zum Abrufen eines AppWindow-Objekts, das einem vorhandenen Fenster gegeben wurde:

  1. Rufen Sie den HWND für Ihr vorhandenes Fensterobjekt (für Ihr UI-Framework) ab, wenn Sie es noch nicht haben.
  2. Übergeben Sie diesen HWND an die Interoperabilitätsfunktion GetWindowIdFromWindow, um eine WindowId abzurufen.
  3. Übergeben Sie diese WindowId an die statische AppWindow.GetFromWindowId-Methode, um die AppWindow abzurufen.
// 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!");
    }
}

Begrenzungen

  • AppWindow ist eine WinUI 3-API. Das bedeutet, dass sie nur für Desktop-Apps verfügbar ist (sowohl verpackt als auch entpackt), nicht für UWP-Apps.
  • Das Windows App SDK stellt derzeit keine Methoden zum Anfügen von UI-Frameworkinhalten an ein AppWindow bereit. Weitere Informationen finden Sie im Abschnitt Code-Beispiel.
  • Die Anpassung der Titelleiste wird in Windows 11 und höher und in Windows 10 für Version 1.2 und höher des Windows App SDK unterstützt. Weitere Informationen finden Sie unter Anpassen der Titelleiste.