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

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

Важные API

• Microsoft.UI.Windowing.AppWindow
• Свойство Windows.UI.Core.CoreWindow.Dispatcher
• Свойство Microsoft.UI.Window.DispatcherQueue

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

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

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

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

В приложении UWP можно разместить содержимое окна, используя ApplicationView, CoreWindow или /. Работа, связанная с переносом этого кода в Windows App SDK, зависит от того, какие из этих двух моделей окон использует приложение UWP. Если вы знакомы с Windows.UI.WindowManagement.AppWindow, вы можете увидеть сходство между этим и 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 означают, что между API UWP surface и API Windows App SDK API surface не существует прямого сопоставления 1:1. Даже для имен классов и членов, которые переходят из UWP (отражённые в таблицах соответствия данного раздела), поведение может отличаться.

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

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

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

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

Создайте и покажите

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

Закрытие

В UWP ApplicationView.TryConsolidateAsync является программным эквивалентом пользователя, инициирующего жест закрытия. Эта концепция консолидации (в оконной модели UWP: ApplicationView и CoreWindow) не существует в Win32. Win32 не требует наличия окон в отдельных потоках. Воспроизведение модели окон ApplicationView и / потребует от разработчика создать новый поток и открыть там новое окно. В модели Win32 системное поведение по умолчанию — Закрыть>Скрыть>Уничтожить.

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

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

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

Размещение окна

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

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

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

Возможности и поведение оконных представлений 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.

Полный экран

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

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

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

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

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

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

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

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

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

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

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

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

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

• AppWindowTitleBar.SetDragRectangles. Задает области перетаскивания для окна.
• AppWindowTitleBar.СбросДоНастроекПоУмолчанию. Сбрасывает текущую строку заголовка обратно в параметры по умолчанию для окна.

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

• AppWindowTitleBarVisibility. Определяет константы, указывающие предпочтительную видимость AppWindowTitleBar.
• AppWindowTitleBar.GetPreferredVisibility. Извлекает предпочтительный режим видимости для строки заголовка.
• AppWindowTitleBar.SetPreferredVisibility. Задает предпочтительный режим видимости для заголовка строки.

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

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

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

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

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

MainPage и MainWindow

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

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

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

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

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

Некоторые варианты использования класса Windows.UI.Core.CoreWindow переносятся в 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".

Связанные темы

• Windows App SDK и поддерживаемые выпуски Windows
• Перенос функциональных возможностей потоков