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

  • Статья

В этом разделе содержится пример кода.

Пакет SDK для приложений Windows предоставляет класс Microsoft.UI.Windowing.AppWindow. AppWindow — это платформа, не зависящая от платформы, и доступна для всех приложений Windows, включая Win32, WPF и WinForms. Вы можете контрастировать характер платформы AppWindow с Microsoft.UI.Xaml.Window, который является классом окна специально для платформы WinUI 3. AppWindow также является эволюцией универсальная платформа Windows (UWP) Windows.UI.WindowManagement.AppWindow.

Версия пакета SDK для приложений Windows Microsoft.UI.Windowing.AppWindow не зависит от асинхронных шаблонов. Она предоставляет немедленную обратную связь приложению о том, успешно ли выполнены вызовы API.

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

Класс AppWindow

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

AppWindow представляет высокоуровневую абстракцию управляемого системой контейнера для содержимого приложения. Это контейнер, в котором размещено содержимое; и представляет сущность, с которую пользователи взаимодействуют при изменении размера и перемещении приложения на экране. Если вы знакомы с Win32, окно приложения можно рассматривать как высокоуровневую абстракцию HWND. Если вы знакомы с UWP, окно приложения можно увидеть как замену CoreWindow/ApplicationView/Windows.UI.WindowManagement.AppWindow.

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

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

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

К каждому приложению AppWindow применяется Приложение AppWindowPresenter (выступающий). Если вы являетесь разработчиком UWP, который работал с Windows.UI.WindowManagement.AppWindow, это будет знакомо, даже если это не сопоставление функций и поведения 1:1. Дополнительные сведения см. в разделе "Миграция функций окна".

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример кода

В этом примере кода показано, как получить microsoft.UI.Windowing.AppWindow из окна WinUI 3 с помощью свойства Microsoft.UI.Xaml.Window.AppWindow. Чтобы использовать пример, создайте пустое приложение, упаковав (WinUI 3 в desktop) и вставьте код в файл.

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

// 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!");
    }
}

Пример кода для версий пакета SDK для приложений Windows до версии 1.3 (или других платформ классических приложений)

Свойство Microsoft.UI.Xaml.Window.AppWindow (используемое в приведенном выше примере кода) доступно в пакете SDK для приложений Windows версии 1.3 и более поздних версий. Для более ранних версий можно использовать функционально эквивалентный пример кода в этом разделе.

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

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

В приведенном ниже разделе "Пример кода" показан фактический исходный код, но ниже приведен рецепт получения объекта AppWindow с существующим окном:

  1. Получите HWND для существующего объекта окна (для платформы пользовательского интерфейса), если у вас его еще нет.
  2. Передайте этот HWND в функцию взаимодействия GetWindowIdFromWindow, чтобы получить WindowId.
  3. Передайте этот идентификатор WindowId в статический метод AppWindow.GetFromWindowId, чтобы получить 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!");
    }
}

Ограничения

  • AppWindow — это API WinUI 3. Это означает, что оно доступно только классическим приложениям (упакованным и распакованным); и недоступен для приложений UWP.
  • Пакет SDK для приложений Windows в настоящее время не предоставляет методы для присоединения содержимого платформы пользовательского интерфейса к AppWindow. Но см. раздел "Пример кода".
  • Настройка строки заголовков поддерживается в Windows 11 и более поздних версиях; и в Windows 10 для версии 1.2 и более поздних версий пакета SDK для приложений Windows. Дополнительные сведения см. в разделе "Настройка строки заголовка".