Перенос функций управления окнами

  • Статья

В этом разделе содержатся рекомендации по управлению окнами, включая переход с ApplicationView/CoreWindow или AppWindow UWP на пакет SDK для приложений Windows Microsoft.UI.Windowing.AppWindow.

Важные API

Сводка по различиям в API и (или) функциях

Windows App SDK предоставляет класс Microsoft.UI.Windowing.AppWindow, основанный на модели HWND Win32. Этот класс AppWindow является версией Windows App SDK приложений UWP ApplicationView/CoreWindow и AppWindow.

Чтобы воспользоваться преимуществами api Windows App SDK оконного управления, необходимо перенести код UWP для использования модели Win32. Дополнительные сведения о Windows App SDK AppWindow см. в статье Управление окнами приложений.

Совет

В разделе Управление окнами приложений содержится пример кода, демонстрирующий извлечение AppWindow из окна WinUI 3. В приложении WinUI 3 используйте этот шаблон кода, чтобы можно было вызывать API AppWindow , упомянутые в оставшейся части этого раздела.

Типы окон в UWP и Windows App SDK

В приложении UWP можно размещать содержимое окна с помощью ApplicationView/CoreWindow или AppWindow. Работа, связанная с переносом этого кода в Windows App SDK, зависит от того, какую из этих двух оконных моделей использует приложение UWP. Если вы знакомы с windows.UI.WindowManagement.AppWindow UWP, то можете увидеть сходство между этим и Microsoft.UI.Windowing.AppWindow.

Типы окон UWP

  • Windows.UI.ViewManagement.ApplicationView/Windows.UI.Core.CoreWindow.
  • Windows.UI.WindowManagement.AppWindow. AppWindow объединяет поток пользовательского интерфейса и окно, которое приложение использует для отображения содержимого. Приложения UWP, использующие AppWindow, будут выполнять меньше работы, чем приложения ApplicationView/CoreWindow для миграции на Windows App SDK AppWindow.

тип окна Windows App SDK

  • Microsoft.UI.Windowing.AppWindow — это высокоуровневая абстракция управляемого системой контейнера содержимого приложения.

Помните, что различия в моделях окон между UWP и Win32 означают, что нет прямого сопоставления 1:1 между поверхностью API UWP и поверхностью API Windows App SDK. Даже для имен классов и членов, которые переносятся из UWP (отражены в таблицах сопоставления этого раздела), поведение также может отличаться.

Экраны-заставки

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

Создание, отображение, закрытие и уничтожение окна

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

Создание и отображение

AppWindow.Create создает окно приложения с конфигурацией по умолчанию. Создание и отображение окна необходимо только в тех случаях, когда вы не работаете с платформой пользовательского интерфейса. Если вы переносите приложение UWP на платформу пользовательского интерфейса, совместимую с Win32, вы по-прежнему можете получить доступ к объекту AppWindow из уже созданного окна с помощью методов взаимодействия с окнами.

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
CoreApplication.CreateNewView
или
CoreWindow.GetForCurrentThread		 AppWindow.TryCreateAsync AppWindow.Create
CoreWindow.Activate AppWindow.TryShowAsync AppWindow.Show

Закрыть

В UWP ApplicationView.TryConsolidateAsync является программным эквивалентом пользователя, инициирующего жест закрытия. Эта концепция консолидации (в модели окна ApplicationView/Core Windows UWP) не существует в Win32. Win32 не требует, чтобы окна существовали в отдельных потоках. Для репликации модели окон ApplicationView/Core Windows в UWP потребуется создать новый поток и создать в нем новое окно. В модели Win32 системное поведение по умолчанию — Close>Hide>Destroy.

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
ApplicationView.TryConsolidateAsync AppWindow.CloseAsync AppWindow.Destroy

Базовая настройка окна

При миграции с UWP на Windows App SDK вы можете ожидать того же взаимодействия с AppWindow по умолчанию. Но при необходимости можно изменить microsoft.UI.Windowing.AppWindow по умолчанию для настраиваемых оконных интерфейсов. Дополнительные сведения о настройке окон см. в статье Microsoft.UI.Windowing.AppWindow .

Изменение размера окна

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
ApplicationView.TryResizeView AppWindow.RequestSize AppWindow.Resize
CoreWindow.Bounds (обычно отображается в C# как CoreWindow.GetForCurrentThread.Bounds) AppWindowPlacement.Size AppWindow.Size

Позиционирование окна

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
Невозможно AppWindow.GetPlacement AppWindow.Position
Невозможно Appwindow.RequestMoveXxx AppWindow.Move

Заголовок окна

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
ApplicationView.Title AppWindow.Title AppWindow.Title

Компактное наложение и полноэкранный режим

Приложения, которые входят в компактный или полноэкранный режим, должны воспользоваться преимуществами Windows App SDK AppWindowPresenter. Если вы знакомы с UWP AppWindow, возможно, вы уже знакомы с концепцией выступающих.

Не существует 1:1 сопоставления функциональности и поведения от выступающих окна приложений UWP с Windows App SDK выступающими окна приложения. Если у вас есть приложение UWP ApplicationView/CoreWindow , вы по-прежнему можете использовать в приложении компактное наложение (изображение в картинке) или полноэкранное окно, но концепция выступающих может быть новой для вас. Дополнительные сведения о выступающих окнах приложений см. в разделе Выступающие. По умолчанию перекрывающийся выступающий применяется к AppWindow во время создания. CompactOverlay и FullScreen являются единственными доступными выступающими, кроме стандартных.

Компактное наложение

Если вы использовали ApplicationViewMode или AppWindowPresentionKind UWP для представления компактного окна наложения, следует использовать компактное наложение AppWindowPresenterKind. Microsoft.UI.Windowing.CompactOverlayPresenter поддерживает только три фиксированных размера окна с пропорциями 16:9 и не может изменяться пользователем. Вместо ApplicationViewMode.TryEnterViewModeAsync или AppWindowPresenterKind.RequestPresentation следует использовать AppWindow.SetPresenter для изменения представления AppWindow.

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
ApplicationViewMode.CompactOverlay AppWindowPresentationKind.CompactOverlay AppWindowPresenterKind.CompactOverlay
ApplicationView.TryEnterViewModeAsync с ApplicationViewMode.CompactOverlay AppWindowPresenter.RequestPresentation с AppWindowPresenterKind.CompactOverlay AppWindow.SetPresenter с AppWindowPresenterKind.CompactOverlay

Полноэкранный режим

Если вы использовали классы ApplicationViewWindowingMode или AppWindowPresentionKind UWP для представления полноэкранного окна, следует использовать полноэкранное приложение AppWindowPresenterKind. Windows App SDK поддерживает только самые строгие возможности полноэкранного режима (то есть, если FullScreen — IsExclusive). Для ApplicationView/CoreWindow можно использовать ApplicationView.ExitFullScreenMode , чтобы вывести приложение из полноэкранного режима. При использовании выступающих можно вывести приложение из полноэкранного режима, задав для него значение перекрывается или по умолчанию с помощью AppWindow.SetPresenter.

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
ApplicationViewWindowingMode.FullScreen AppWindowPresentationKind.FullScreen AppWindowPresenterKind.FullScreen
ApplicationView.TryEnterFullScreenMode AppWindowPresenter.RequestPresentation с AppWindowPresenterKind.FullScreen AppWindow.SetPresenter с AppWindowPresenterKind.FullScreen

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

Настраиваемая строка заголовка

Примечание

API настройки заголовка строки в настоящее время работают только с Windows 11. Перед вызовом этих API рекомендуется проверка AppWindowTitleBar.IsCustomizationSupported в коде.

Если в приложении используется строка заголовка по умолчанию, при переходе на Win32 дополнительная работа с заголовком не требуется. С другой стороны, если приложение UWP имеет настраиваемую строку заголовка, можно повторно создать следующие сценарии в приложении Windows App SDK.

  1. Настройка нарисованной системой строки заголовка
  2. Настраиваемая строка заголовка, нарисованная приложением

Код, использующий классы UWP ApplicationViewTitleBar, CoreApplicationViewTitleBar и AppWindowTitleBar, переносится на Windows App SDK класса Microsoft.UI.Windowing.AppWindowTitleBar.

Настройка нарисованной системой строки заголовка

Ниже приведена таблица API настройки цвета.

Примечание

Если appWindowTitleBar.ExtendsContentIntoTitleBar имеет значение true, прозрачность поддерживается только для следующих свойств: AppWindowTitleBar.ButtonBackgroundColor, AppWindowTitleBar.ButtonInactiveBackgroundColor, AppWindowTitleBar.ButtonPressedBackgroundColor, AppWindowTitleBar.ButtonHoverBackgroundColor и AppWindowTitleBar.BackgroundColor (неявно задано).

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
Свойства ApplicationViewTitleBar Свойства AppWindowTitleBar Свойства AppWindowTitleBar
BackgroundColor BackgroundColor BackgroundColor
ButtonBackgroundColor ButtonBackgroundColor ButtonBackgroundColor
ButtonForegroundColor ButtonForegroundColor ButtonForegroundColor
ButtonHoverBackgroundColor ButtonHoverBackgroundColor ButtonHoverBackgroundColor
ButtonHoverForegroundColor ButtonHoverForegroundColor ButtonHoverForegroundColor
ButtonInactiveBackgroundColor ButtonInactiveBackgroundColor ButtonInactiveBackgroundColor
ButtonInactiveForegroundColor ButtonInactiveForegroundColor ButtonInactiveForegroundColor
ButtonPressedBackgroundColor ButtonPressedBackgroundColor ButtonPressedBackgroundColor
ButtonPressedForegroundColor ButtonPressedForegroundColor ButtonPressedForegroundColor
ForegroundColor ForegroundColor ForegroundColor
InactiveBackgroundColor InactiveBackgroundColor InactiveBackgroundColor
InactiveForegroundColor InactiveForegroundColor InactiveForegroundColor

Эти WINDOWS APP SDK API предназначены для дальнейшей настройки нарисованной системой строки заголовка в дополнение к API AppWindow.Title.

  • AppWindow.SetIcon. Задает заголовок строки и изображение значка панели задач с помощью дескриптора hIcon или строкового пути к ресурсу или файлу.
  • AppWindowTitleBar.IconShowOptions. Возвращает или задает значение, указывающее, как значок окна отображается в строке заголовка. В настоящее время поддерживает два значения— HideIconAndSystemMenu и ShowIconAndSystemMenu.
  • AppWindowTitleBar.ResetToDefault. Сбрасывает текущую строку заголовка до параметров по умолчанию для окна.

Настраиваемая строка заголовка приложения (полная настройка)

Если вы переходите на использование AppWindowTitleBar, рекомендуется проверка AppWindowTitleBar.IsCustomizationSupported в коде, прежде чем вызывать следующие настраиваемые API заголовка.

UWP ApplicationView/CoreWindow Windows App SDK AppWindow
CoreApplicationViewTitleBar.ExtendViewIntoTitleBar AppWindowTitleBar.ExtendsContentIntoTitleBar
Платформа продолжает рисовать кнопки Свернуть/максимально/закрыть и сообщает сведения о окклюзии.
CoreApplicationViewTitleBar.SystemOverlayLeftInset AppWindowTitleBar.LeftInset
CoreApplicationViewTitleBar.SystemOverlayRightInset AppWindowTitleBar.RightInset
CoreApplicationViewTitleBar.Height AppWindowTitleBar.Height
AppWindowTitleBarOcclusion
AppWindowTitleBar.GetTitleBarOcclusions		 Представляет области, зарезервированные системой, в окне приложения, которые будут охватывать содержимое приложения, если свойство ExtendsContentIntoTitleBar имеет значение true. В Windows App SDK AppWindow слева и справа отрезка в сочетании с высотой заголовка окна предоставляются те же сведения.
AppWindowTitleBar.LeftInset, AppWindowTitleBar.RightInset, AppWindowTitleBar.Height

Эти Windows App SDK API предназначены для полной настройки заголовка окна.

Эти API-интерфейсы UWP AppWindow не имеют прямого сопоставления 1:1 с API Windows App SDK.

Дополнительные сведения о работе с AppWindowTitleBar см. в примере коллекции Окон. В ней показано, как создать пользовательскую цветовую строку заголовка и как нарисовать настраиваемую строку заголовка.

Обработка событий

Если приложение UWP использует событие AppWindow.Changed , вы можете перенести этот код в событие Microsoft.UI.Windowing.AppWindow.Changed .

Событие изменения размера

При переносе кода обработки событий с измененным размером следует переключиться на использование свойства Windows App SDK AppWindowChangedEventArgs.DidSizeChange. Значение равно , true если размер окна приложения изменился, в противном случае — falseзначение .

UWP ApplicationView/CoreWindow Приложение UWPWindow Пакет SDK для приложений Windows
CoreWindow.SizeChanged AppWindowChangedEventArgs.DidSizeChange AppWindowChangedEventArgs.DidSizeChange

MainPage и MainWindow

При создании проекта UWP в Visual Studio шаблон проекта предоставляет класс MainPage . Возможно, вы переименовали этот класс для приложения (и /или добавили дополнительные страницы и пользовательские элементы управления). Шаблон проекта также предоставляет код навигации в методах класса App .

При создании проекта Windows App SDK в Visual Studio шаблон проекта предоставляет класс MainWindow (типа Microsoft.UI.Xaml.Window), но не Page. А шаблон проекта не предоставляет код навигации.

Однако вы можете добавить страницы и пользовательские элементы управления в проект Windows App SDK. Например, можно добавить новый элемент страницы в проект (WinUI>Blank Page (WinUI 3)) и присвоить ему MainPage.xamlимя или другое имя. Это добавит в проект новый класс типа Microsoft.UI.Xaml.Controls.Page. Дополнительные сведения о добавлении кода навигации в проект см. в статье Нужно ли реализовать навигацию по страницам?

Для Windows App SDK достаточно простых приложений не нужно создавать страницы или пользовательские элементы управления, и вы можете скопировать разметку XAML и код программной части в MainWindow. Но сведения об исключениях в этом рабочем процессе см. в разделах Диспетчер визуальных состояний и Page.Resources.

Измените CoreWindow.Dispatcher на Window.DispatcherQueue

Некоторые варианты использования класса Windows.UI.Core.Core.Core UWP переносятся в Microsoft.UI.Xaml.Window Windows App SDK.

Например, если вы используете свойство Windows.UI.Core.CoreWindow.Dispatcher в приложении UWP, решение не заключается в переходе на свойство Microsoft.UI.Xaml.Window.Dispatcher (которое всегда возвращает значение NULL). Вместо этого перейдите на свойство Microsoft.UI.Xaml.Window.DispatcherQueue , которое возвращает Microsoft.UI.Dispatching.DispatcherQueue.

Дополнительные сведения и примеры кода см. в статье Изменение windows.UI.Core.CoreDispatcher на Microsoft.UI.Dispatching.DispatcherQueue.