Управление окнами приложений (Windows App SDK)

Этот раздел содержит пример кода .

В Windows App SDK предоставляется простой класс Microsoft.UI.Windowing.AppWindow. AppWindow не зависит от платформы и доступна для всех приложений Windows, включая Win32, WPF и WinForms. Вы можете контрастировать не зависящая от платформы природу AppWindow с Microsoft.UI.Xaml.Window, который является классом окон специально для платформы WinUI 3. AppWindow также является эволюцией Windows универсальная платформа Windows (UWP). ПОЛЬЗОВАТЕЛЬСКОГО ИНТЕРФЕЙСА. WindowManagement.AppWindow.

Windows App SDK версия Microsoft.UI.Windowing.AppWindow не зависит от асинхронных шаблонов. Она предоставляет немедленную обратную связь приложению о том, успешно ли выполнены вызовы API. В будущем, когда речь идет о внедрении новых функций, интеграции с Windows пользовательского интерфейса или пользовательского интерфейса и включении новых сценариев окон, Windows App SDK ИНТЕРФЕЙСы API окна будут фокусом. Мы рекомендуем начать использовать эти API для операций с окнами.

См. также статью "Установка" для Windows App SDK, создание первого проекта WinUI 3 и использование Windows App SDK в существующем проекте.

Класс AppWindow

Microsoft.UI.Windowing.AppWindow — это высокоуровневый API окон, который позволяет легко использовать сценарии использования окон. AppWindow хорошо интегрируется с Windows пользовательского интерфейса или пользовательского интерфейса и с другими приложениями.

AppWindow представляет высокоуровневую абстракцию управляемого системой контейнера для содержимого приложения. Это контейнер, в котором размещается содержимое; и представляет сущность, с которыми пользователи взаимодействуют при изменении размера и перемещении приложения на экране. Если вы знакомы с Win32, "окно приложения" можно рассматривать как высокоуровневую абстракцию HWND. Если вы знакомы с UWP, окно приложения можно рассматривать как замену CoreWindow/ApplicationView/Windows. ПОЛЬЗОВАТЕЛЬСКОГО ИНТЕРФЕЙСА. WindowManagement.AppWindow.

Для Windows App SDK версии Microsoft.UI.Windowing.AppWindow поддерживается только HWNDверхнего уровня. Существует сопоставление 1:1 между AppWindow и HWND верхнего уровня.

Время существования объекта AppWindow и HWND совпадает: AppWindow доступен сразу после создания окна; и он уничтожается при закрытии окна.

Класс AppWindowPresenter и подклассы

К каждому приложению AppWindow применяется AppWindowPresenter (выступающий). Если вы являетесь разработчиком UWP, который работал с Windows. ПОЛЬЗОВАТЕЛЬСКОГО ИНТЕРФЕЙСА. WindowManagement.AppWindow, то это будет знакомо; даже если это не сопоставление функциональных возможностей и поведения не равно 1:1. См. также сведения о миграции функций окон.

В качестве новой концепции для модели приложения Win32 выступающий является сродни (но не так же), как сочетание состояния окна и стилей. Некоторые выступающие также имеют поведение пользовательского интерфейса или пользовательского интерфейса, определенное в них, которые не проверяются из состояния классического окна и свойств стиля (например, автоматически скрываемой панели заголовка).

По умолчанию ведущий создается системой и применяется к AppWindow во время создания. В Windows App SDK 1.0 Stable на компьютере Windows тип докладчика — OverlappedPresenter, который является подклассом AppWindowPresenter. Приложению не нужно хранить ссылку на нее, чтобы вернуться к окну докладчика по умолчанию после применения другого докладчика. Это связано с тем, что система сохраняет тот же экземпляр этого докладчика на протяжении всего времени существования AppWindow , для которого она была создана; и приложение может повторно применить его, вызвав метод AppWindow.SetPresenter с AppWindowPresenterKind.Default в качестве параметра.

Выступающий может применяться только к одному окну за раз. При попытке применить тот же ведущий к второму окну возникает исключение. Это означает, что если у вас несколько окон, и вы хотите переключить каждую из них в определенный режим презентации, необходимо создать несколько выступающих одного типа, а затем применить каждый из них к собственному окну.

Некоторые выступающие имеют функциональные возможности, позволяющие пользователю вносить изменения за пределами собственного элемента управления приложения. При таком изменении ваше приложение уведомляется событием AppWindow.Changed в затронутом AppWindow, а для свойства AppWindowChangedEventArgs.DidPresenterChange задано значение true. Затем приложение должно проверить свойство примененного докладчика, чтобы узнать, что изменилось.

Примененный выступающий является динамическим объектом. Изменение любого свойства объекта AppWindow.Presenter вступает в силу немедленно.

Выступающий не может быть уничтожен, пока он применяется к окну. Чтобы уничтожить объект докладчика, сначала примените другой объект докладчика к окну; таким образом, выступающий, который планируется уничтожить, удаляется из окна. Это можно сделать, применив к окну другого конкретного докладчика или вызвав метод AppWindow.SetPresenter с AppWindowPresenterKind.Default в качестве аргумента, который повторно будет применять к окну созданную по умолчанию систему выступающих. Если вы попытались сохранить ссылку на созданный системой выступающий для окна, он будет действителен на этом этапе (то есть экземпляр, который был создан для окна повторно).

Доступные выступающие

Эти выступающие, производные от AppWindowPresenter, предоставляются и доступны во всех поддерживаемых версиях ОС.

  • CompactOverlayPresenter. Создает постоянное окно фиксированного размера с пропорциями 16:9, чтобы обеспечить взаимодействие с изображением в виде рисунка.
  • FullScreenPresenter. Позволяет окну перейти в полноэкранный интерфейс.
  • Перекрывающийсяpresenter. Созданный системой выступающий по умолчанию, который позволяет запрашивать и реагировать на минимизацию, развертывание и восстановление операций и изменение состояния.

Платформа пользовательского интерфейса и взаимодействие HWND

Класс AppWindow доступен для любогоHWND верхнего уровня в приложении. Это означает, что при работе с платформой пользовательского интерфейса можно продолжать использовать точку входа этой платформы для создания окна и присоединения его содержимого. После создания окна можно использовать функции взаимодействия с окнами, предоставляемые в Windows App SDK для доступа к соответствующим методам, свойствам и событиям AppWindow.

C#. .NET оболочки для функций взаимодействия с окнами реализуются как методы класса Microsoft.UI.Win32Interop. См. также API взаимодействия вызовов из приложения .NET.

C++. Функции взаимодействия определяются в файле заголовка winrt/Microsoft.ui.interop.h .

Чтобы получить объект AppWindow , заданный HWND для существующего окна, используйте функцию взаимодействия GetWindowIdFromWindow . См. пример кода ниже.

Некоторые преимущества использования AppWindow даже при работе с платформой пользовательского интерфейса:

  • Простая настройка строки заголовка, которая по умолчанию поддерживает пользовательский интерфейс Windows 11 (скругленные углы, всплывающий элемент группы привязки).
  • Предоставляемые системой полноэкранные и компактные наложения (изображение в изображении).
  • область API среда выполнения Windows (WinRT) для некоторых основных концепций окон Win32.

Пример кода

В этом примере кода показано, как получить AppWindow из окна WinUI 3. Чтобы использовать этот пример, создайте пустое приложение, упаковав (WinUI 3 в классическом приложении) и вставьте код.

C#. В примере кода используются классы WinRT.Interop.WindowNative и Microsoft.UI.Win32Interop (см. api взаимодействия вызовов из приложения .NET). Также см. раздел "Получение дескриптора окна (HWND)".

Дополнительные сведения о работе с AppWindow см. в примере коллекции Windowing.

// 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 AppWindow::GetFromWindowId

// 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->try_as<::IWindowNative>() };
    winrt::check_bool(windowNative);
    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!");
    }
}

Ограничения

  • AppWindow доступен только для классических приложений (упакованных и распакованных); Он недоступен для приложений UWP.
  • В настоящее время Windows App SDK не предоставляет методы для присоединения содержимого платформы пользовательского интерфейса к AppWindow. Вы можете использовать методы доступа к взаимодействию HWND , показанные в разделе "Пример кода ".
  • Настройка TitleBar в настоящее время поддерживается только в Windows 11 или более поздних версиях. Дополнительные сведения см. в разделе "Настройка строки заголовка ".