Перенос функций управления окнами
В этом разделе содержатся рекомендации по управлению окнами, включая миграцию с ApplicationView/CoreWindow или AppWindow в пакет SDK приложений Windows Microsoft.UI.Windowing.AppWindow.
Важные API
- Microsoft.UI.Windowing.AppWindow
- Свойство Windows.UI.Core.CoreWindow.Dispatcher
- Свойство Microsoft.UI.Window.DispatcherQueue
Сводка различий между API и (или) функциями
Пакет SDK для приложений Windows предоставляет класс Microsoft.UI.Windowing.AppWindow , основанный на модели Win32 HWND. Этот класс AppWindow — это версия пакета SDK для приложений Windows для Приложения UWP CoreWindow/и AppWindow.
Чтобы воспользоваться преимуществами API окна пакета SDK для приложений Windows, необходимо перенести код UWP для использования модели Win32. Дополнительные сведения о AppWindow пакета SDK для Windows см. в разделе "Управление окнами приложений".
Совет
Раздел "Управление окнами приложений" содержит пример кода, демонстрирующий, как получить AppWindow из окна WinUI 3. В приложении WinUI 3 используйте этот шаблон кода, чтобы можно было вызывать API AppWindow , упомянутые в остальной части этого раздела.
Типы окон в UWP и пакет SDK для приложений Windows
В приложении UWP можно разместить содержимое окна с помощью ApplicationView/CoreWindow или AppWindow. Работа, связанная с переносом этого кода в пакет SDK для приложений Windows, зависит от того, какие из этих двух моделей использует приложение 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 для миграции в AppWindow пакета SDK для Windows.
Тип окна пакета SDK для приложений Windows
- Microsoft.UI.Windowing.AppWindow — это высокоуровневая абстракция управляемого системой контейнера содержимого приложения.
Имейте в виду, что различия в моделях окон между UWP и Win32 означают, что между поверхностью API UWP и поверхностью API пакета SDK для Windows нет прямого сопоставления 1:1. Даже для имен классов и членов, которые переносятся из UWP (отраженные в таблицах сопоставления этого раздела), поведение может отличаться.
Экраны-заставки
В отличие от приложений UWP, приложения Win32 по умолчанию не отображают экран-заставку при запуске. Приложения UWP, использующие эту функцию для их запуска, могут выбрать реализацию пользовательского перехода к первому окну приложения.
Создание, отображение, закрытие и уничтожение окна
Время существования Microsoft.UI.Windowing.AppWindow совпадает с HWND; это означает, что объект AppWindow доступен сразу после создания окна и уничтожается при закрытии окна.
Создание и отображение
AppWindow.Create создает окно приложения с конфигурацией по умолчанию. Создание и отображение окна необходимо только для сценариев, когда вы не работаете с платформой пользовательского интерфейса. Если вы переносите приложение UWP в платформу пользовательского интерфейса, совместимую с Win32, вы все равно можете получить доступ к объекту AppWindow из уже созданного окна с помощью методов взаимодействия с окном.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| CoreApplication.CreateNewView or CoreWindow.GetForCurrentThread |
AppWindow.TryCreateAsync | AppWindow.Create |
| CoreWindow.Activate | AppWindow.TryShowAsync | AppWindow.Show |
Закрытие
В UWP ApplicationView.TryConsolidateAsync является программным эквивалентом пользователя, инициирующего жест закрытия. Эта концепция консолидации (в модели окна ApplicationView/CoreWindow uWP) не существует в Win32. Win32 не требует наличия окон в отдельных потоках. Репликация модели окна ApplicationView/CoreWindow uWP потребует от разработчика создать новый поток и создать там новое окно. В модели Win32 системное поведение по умолчанию — Close Hide>Destroy>.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| ApplicationView.TryConsolidateAsync | AppWindow.CloseAsync | AppWindow.Destroy |
Базовая настройка окна
При переходе из UWP в пакет SDK для приложений Windows вы можете ожидать тот же интерфейс, что и приложение AppWindow по умолчанию. Но при необходимости вы можете изменить параметры по умолчанию Microsoft.UI.Windowing.AppWindow для настраиваемых окон. Дополнительные сведения о настройке окон см. в разделе Microsoft.UI.Windowing.AppWindow.
Изменение размера окна
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| ApplicationView.TryResizeView | AppWindow.RequestSize | AppWindow.Resize |
CoreWindow.Bounds (обычно отображается в C# как CoreWindow.GetForCurrentThread.Bounds) |
AppWindowPlacement.Size | AppWindow.Size |
Размещение окна
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| Невозможно | AppWindow.GetPlacement | AppWindow.Position |
| Невозможно | Appwindow.RequestMoveXxx | AppWindow.Move |
Window title
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| ApplicationView.Title | AppWindow.Title | AppWindow.Title |
Компактный наложение и полноэкранный
Приложения, которые входят в компактную наложение или полный экран, должны воспользоваться преимуществами Пакета SDK для приложений Windows AppWindowPresenter. Если вы знакомы с UWP AppWindow, вы уже знакомы с понятием выступающих.
Отсутствует сопоставление функций и поведения выступающих окон приложений UWP с окнами windows APP SDK для Windows. Если у вас есть приложение UWP ApplicationView/CoreWindow, вы по-прежнему можете иметь компактное наложение (изображение в рисунке) или полноэкранное окно в приложении, но концепция выступающих может быть новой для вас. Дополнительные сведения о выступающих окнах приложений см. в разделе "Выступающие". По умолчанию перекрывающийся выступающий применяется к AppWindow во время создания. CompactOverlay и FullScreen являются единственными доступными выступающими, помимо по умолчанию.
Компактный наложение
Если вы использовали ApplicationViewMode uWP или AppWindowPresentionKind для представления компактного окна наложения, следует использовать компактное наложение AppWindowPresenterKind. Microsoft.UI.Windowing.CompactOverlayPresenter поддерживает только три фиксированных размера окна в пропорции 16:9 и не может быть изменен пользователем. Вместо ApplicationViewMode.TryEnterViewModeAsync или AppWindowPresenterKind.RequestPresentation следует использовать AppWindow.SetPresenter для изменения представления AppWindow.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| ApplicationViewMode.CompactOverlay | AppWindowPresentationKind.CompactOverlay | AppWindowPresenterKind.CompactOverlay |
| ApplicationView.TryEnterViewModeAsync с ApplicationViewMode.CompactOverlay | AppWindowPresenter.RequestPresentation с appWindowPresenterKind.CompactOverlay | AppWindow.SetPresenter с AppWindowPresenterKind.CompactOverla y |
Полный экран
Если вы использовали классы ApplicationViewWindowingMode или AppWindowPresentionKind uWP для представления полноэкранного окна, следует использовать полноэкранное приложение AppWindowPresenterKind. Пакет SDK для приложений Windows поддерживает только наиболее строгий полноэкранный интерфейс (т. е. если FullScreen — IsExclusive). Для ApplicationView CoreWindow можно использовать ApplicationView.ExitFullScreenMode/ для вывода приложения из полноэкранного экрана. При использовании выступающих вы можете выйти из полноэкранного приложения, задав выступающим значение по умолчанию с помощью AppWindow.SetPresenter.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| ApplicationViewWindowingMode.FullScreen | AppWindowPresentationKind.FullScreen | AppWindowPresenterKind.FullScreen |
| ApplicationView.TryEnterFullScreenMode | AppWindowPresenter.RequestPresentation с AppWindowPresenterKind.FullScreen | AppWindow.SetPresenter с AppWindowPresenterKind.FullScreen |
Дополнительные сведения о работе с выступающими окнами приложений см. в примере коллекции windowing. В нем показано, как переключать различные состояния докладчика окна приложения.
Настраиваемая строка заголовка
Примечание.
API настройки строки заголовков в настоящее время работают только в Windows 11. Перед вызовом этих API рекомендуется проверить AppWindowTitleBar.IsCustomizationSupported в коде.
Если приложение использует строку заголовка по умолчанию, при миграции на Win32 не требуется дополнительная строка заголовка. Если с другой стороны приложение UWP имеет настраиваемую строку заголовка, можно создать следующие сценарии в приложении sdk для приложений для Приложений Windows.
- Настройка строки заголовка, нарисованной системой
- Настраиваемая строка заголовка нарисованного приложения
Код, использующий классы ApplicationViewTitleBar UWP, CoreApplicationViewTitleBar и AppWindowTitleBar, переносится на использование класса Microsoft.UI.Windowing.AppWindowTitleBar.
Настройка строки заголовка, нарисованной системой
Ниже приведена таблица API настройки цвета.
Примечание.
Если AppWindowTitleBar.ExtendsContentIntoTitleBartrue , прозрачность поддерживается только для следующих свойств: AppWindowTitleBar.ButtonBackgroundColor, AppWindowTitleBar.ButtonInactiveBackgroundColor, AppWindowTitleBar.ButtonPressedBackgroundColor, AppWindowTitleBar.ButtonowTitleBar.ButtonowToverBackgroundColor и AppWindowTitleBar.BackgroundColor (неявно задано).
Эти API пакета SDK для приложений Для Windows предназначены для дальнейшей настройки строки заголовков на основе системы в дополнение к API AppWindow.Title.
- AppWindow.SetIcon. Задает рисунок заголовка и значка панели задач с помощью дескриптора hIcon или строкового пути к ресурсу или файлу.
- AppWindowTitleBar.IconShowOptions. Возвращает или задает значение, указывающее, как значок окна отображается в строке заголовка. Поддерживает два значения в настоящее время— HideIconAndSystemMenu и ShowIconAndSystemMenu.
- AppWindowTitleBar.ResetToDefault. Сбрасывает текущую строку заголовка обратно в параметры по умолчанию для окна.
Настраиваемая строка заголовка приложения (полная настройка)
Если вы переходите на использование AppWindowTitleBar, рекомендуется проверить AppWindowTitleBar.IsCustomizationSupported в коде перед вызовом следующих пользовательских API строк заголовка.
| UWP ApplicationView/CoreWindow | AppWindow для пакета SDK для Windows |
|---|---|
| CoreApplicationViewTitleBar.ExtendViewIntoTitleBar | AppWindowTitleBar.ExtendsContentIntoTitleBar Платформа продолжает рисование кнопок "Свернуть/максимальное/закрытие" и сообщает сведения о окклюзии. |
| CoreApplicationViewTitleBar.SystemOverlayLeftInset | AppWindowTitleBar.LeftInset |
| CoreApplicationViewTitleBar.SystemOverlayRightInset | AppWindowTitleBar.RightInset |
| CoreApplicationViewTitleBar.Height | AppWindowTitleBar.Height |
| AppWindowTitleBarOcclusion AppWindowTitleBar.GetTitleBarOcclusions |
Представляет области, зарезервированные системой, в окне приложения, которые будут occlude содержимое приложения, если ExtendsContentIntoTitleBar имеет значение true. Сведения о наборе sdk для приложений Windows слева и справа, в сочетании с высотой строки заголовка, предоставляют те же сведения. AppWindowTitleBar.LeftInset, AppWindowTitleBar.RightInset, AppWindowTitleBar.Height |
Эти API пакета SDK для приложений Windows предназначены для настройки полной строки заголовка.
- AppWindowTitleBar.SetDragRectangles. Задает области перетаскивания для окна.
- AppWindowTitleBar.ResetToDefault. Сбрасывает текущую строку заголовка обратно в параметры по умолчанию для окна.
Эти API UWP AppWindow не имеют прямого сопоставления 1:1 с API пакета SDK для приложений Windows.
- AppWindowTitleBarVisibility. Определяет константы, указывающие предпочтительную видимость AppWindowTitleBar.
- AppWindowTitleBar.GetPreferredVisibility. Извлекает предпочтительный режим видимости для строки заголовка.
- AppWindowTitleBar.SetPreferredVisibility. Задает предпочтительный режим видимости для заголовка строки.
Дополнительные сведения о работе с AppWindowTitleBar см. в примере коллекции Windowing. В нем показано, как создать настраиваемую строку заголовка цвета и как нарисовать настраиваемую строку заголовка.
Обработка событий
Если приложение UWP использует событие AppWindow.Changed, можно перенести этот код в событие Microsoft.UI.Windowing.AppWindow.Changed.
Событие изменения размера
При переносе измененного кода обработки событий следует переключиться на использование свойства AppWindow AppWindowChangedEventArgs.DidSizeChange. Значение равно, если размер окна приложения изменился true , в противном случае это falseзначение.
| UWP ApplicationView/CoreWindow | UWP AppWindow | Пакет SDK для приложений Windows |
|---|---|---|
| CoreWindow.SizeChanged | AppWindowChangedEventArgs.DidSizeChange | AppWindowChangedEventArgs.DidSizeChange |
MainPage и MainWindow
При создании проекта UWP в Visual Studio шаблон проекта предоставляет класс MainPage . Возможно, вы переименовали этот класс (или добавили дополнительные страницы и пользовательские элементы управления). Шаблон проекта также предоставляет код навигации в методах класса App .
При создании проекта пакета SDK для приложений Windows в Visual Studio шаблон проекта предоставляет класс MainWindow (типа Microsoft.UI.Xaml.Window), но нет страницы. И шаблон проекта не предоставляет код навигации.
Однако вы можете добавить страницы и пользовательские элементы управления в проект пакета SDK для приложений Windows. Например, можно добавить новый элемент страницы в проект (пустая страница WinUI (WinUI>3)) и присвоить ему имя MainPage.xamlили другое имя. Это добавит в проект новый класс типа Microsoft.UI.Xaml.Controls.Page. Затем сведения о добавлении кода навигации в проект см. в статье "Необходимо ли реализовать навигацию по страницам?".
Для приложений пакета SDK для Приложений Windows, которые достаточно просты, вам не нужно создавать страницы или пользовательские элементы управления, и вы можете скопировать разметку XAML и код программной части в MainWindow. Но сведения об исключениях в этом рабочем процессе см. в разделе "Диспетчер визуальных состояний" и "Page.Resources".
Изменение CoreWindow.Dispatcher на Window.DispatcherQueue
Некоторые варианты использования класса Windows.UI.Core.CoreWindow для UWP переносятся в Microsoft.UI.Xaml.Window пакета SDK для приложений Windows.
Например, если вы используете свойство 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 developer