Поделиться через

Общие сведения о окне для WinUI и Windows пакета SDK для приложений

Функции окна в приложении WinUI предоставляются сочетанием класса XAML Window и AppWindow класса, оба из которых основаны на модели Win32 HWND.

Откройте приложение коллекции WinUI 3 и просмотрите примеры окон в действии

Приложение Галерея WinUI 3 включает интерактивные примеры большинства элементов управления, особенностей и возможностей WinUI 3. Получение приложения из Microsoft Store или получение исходного кода на GitHub

XAML Window

В приложении объект окна является экземпляром класса Microsoft.UI.Xaml (Window или производного класса), представляющего окно в коде программы. Вы создаете его непосредственно вызовом конструктора. XAML Window — это место, в котором вы присоединяете содержимое приложения и управляете жизненным циклом окон приложения.

HWND

Окно приложения создается операционной Windows системой и представлено объектом окна Win32. Это управляемый системой контейнер, в котором размещено содержимое, и представляет сущность, с которой пользователи взаимодействуют при изменении размера и перемещении приложения на экране. ( Дополнительные сведения см Windows . в документации по Win32.)

После того как Windows создаёт окно приложения, функция создания возвращает window handle (HWND), который однозначно идентифицирует окно. A window handle имеет тип данных HWND, хотя он отображается в C# как IntPtr. Это непрозрачный дескриптор внутренней Windows структуры данных, которая соответствует окну, отображаемому ОС и потребляющему системные ресурсы в присутствии.

HWND создается после объекта XAMLWindow, как правило, при вызове метода Window.Activate.

AppWindow

Пакет SDK приложений Windows предоставляет дополнительные функциональные возможности оконного интерфейса через класс Microsoft.UI.Windowing.AppWindow AppWindow представляет высокоуровневую абстракцию HWND. Существует сопоставление 1:1 между AppWindow и HWND верхнего уровня в вашем приложении. AppWindow и связанные с ним классы предоставляют API, которые позволяют управлять многими аспектами окон верхнего уровня приложения без необходимости напрямую получить доступ к HWND.

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

Схема API окна

На этой схеме показана связь между классами и API, которые используются для управления окнами в приложении, и какие классы отвечают за каждую часть управления окнами. В некоторых случаях, например ExtendsContentIntoTitleBar, API является частью AppWindow, чтобы сделать его доступным для других фреймворков пользовательского интерфейса, а также предоставляется в классе Window для удобства. Схема не является комплексной, но показывает наиболее часто используемые API.

Схема окна win u i

Замечание

API можно использовать AppWindow с любым фреймворком пользовательского интерфейса, который поддерживает пакет SDK приложений Windows: Win32, WPF, WinForms или WinUI 3. Для платформ, отличных от WinUI 3, функциональные возможности, показанные в поле XAML Window схемы, будут заменены соответствующими API окна для конкретной платформы:

WindowСравнениеAppWindow API

Если вы используете WinUI 3 XAML в качестве платформы пользовательского интерфейса приложения, вам доступны и Window API и AppWindow API. Начиная с пакета App SDK 1.4, можно использовать свойство Windows, чтобы получить объект Window из существующего окна XAML. С помощью этого AppWindow объекта у вас есть доступ к дополнительным API управления окнами.

Это важно

Если вы не используете WinUI 3 версии 1.3 или более поздней, используйте API взаимодействия, чтобы получить AppWindow для использования API AppWindow. Дополнительные сведения об API взаимодействия см. в разделе «Управление окнами приложений — платформа пользовательского интерфейса и взаимодействие HWND» и в примере коллекции окон.

Управление жизненным циклом

XAML Window AppWindow
Constructor Создать, GetFromWindowId
Activate Показать, скрыть
Закрыть, Закрыто Уничтожение, уничтожение, закрытие
>>> Идентификатор, OwnerWindowId

При создании проекта WinUI в Visual Studio шаблон проекта предоставляет MainWindow класс, который является подклассом Window. Если приложению требуется только одно окно, это все, что вам нужно. Сведения о создании дополнительных окон и управлении ими, а также о том, почему вы хотите, см. статью "Показать несколько окон для приложения".

Класс AppWindow имеет API для создания и уничтожения нового окна. Однако для приложения WinUI это не делается на практике, так как нет API для присоединения содержимого к создаваемому окну. Вместо этого вы получите экземпляр AppWindow , созданный системой и связанный с XAML Window и HWND. В WinUI 1.4 и более поздних версиях можно использовать Windowсвойство .AppWindow для получения экземпляра AppWindow. В других случаях можно использовать статический метод AppWindow.GetFromWindowId для получения экземпляра AppWindow. Дополнительные сведения см. в разделе "Управление окнами приложений ".

Content

XAML Window AppWindow
Content N/A

.Window Свойство содержимого — это место, в котором вы присоединяете содержимое приложения к окну, отображающее его. Это можно сделать в XAML или в коде.

Заголовок, значок и строка заголовка

XAML Window AppWindow
Заголовок Заголовок
SetTitleBar TitleBar
>>> SetIcon, SetTaskbarIcon, SetTitleBarIcon
Расширяет содержимое на панель заголовка AppWindow.TitleBar.ExtendsContentIntoTitleBar

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

Сведения об использовании API строк заголовка, включая примеры кода, см. в разделе "Настройка строки заголовка".

Размер и положение

XAML Window AppWindow
Граница Положение, Размер, Размер клиента
ИзменениеРазмера Изменено (DidPositionChange, DidSizeChange)
>>> Move, Resize, ResizeClient, MoveAndResize
>>> ПереместитьПоПорядкуВниз, ПереместитьПоПорядкуВверх, ПереместитьПоПорядкуНиже

Window.Свойство Bounds и событие SizeChanged используются для управления элементами в пользовательском интерфейсе приложения, например, для перемещения элементов при изменении размера окна. XAML использует effective pixels (epx), а не фактические физические пиксели. Effective pixels — это виртуальная единица измерения, и они используются для выражения измерений макета и интервалов, независимо от плотности экрана.

AppWindowС другой стороны, использует Window систему координат, где основная единица измерения — это физические пиксели устройства. Вы используете AppWindow API для действий с окнами, таких как изменение размера окна или перемещение его в отношении чего-либо другого на экране.

В некоторых случаях вам может потребоваться использовать измерения из одного класса в другом классе, и в этом случае вам нужно будет преобразовать между effective pixels и пикселями устройства. Например, если вы задаете области перетаскивания в настраиваемой строке заголовка, необходимо преобразовать измерения. Пример использования XamlRoot.RasterizationScale для преобразования измерений см. в разделе интерактивного содержимого статьи по настройке строки заголовка .

Внешний вид и поведение

XAML Window AppWindow
SystemBackdrop N/A
>>> Выступающий, SetPresenter
>>> IsShownInSwitchers
Видимый, ИзменениеВидимости IsVisible, Изменено (DidVisibilityChange)
DispatcherQueue DispatcherQueue, AssociateWithDispatcherQueue
Compositor N/A

API XAML Window обычно отвечают за внешний вид содержимого приложения, например фон. Дополнительные сведения о SystemBackdrop см. в разделе Применение материалов Mica или Acrylic.

AppWindow API отвечают за часть окна, не относящегося к клиенту , и взаимодействие приложения с Windows ОС.

Замечание

Класс XAML Window имеет несколько свойств, которые были перенесены из класса UWP Windows.UI.Xaml.Window, но они не поддерживаются в приложениях WinUI. Эти свойства всегда имеют null значение и не используются в приложениях WinUI: CoreWindow, Currentи Dispatcher.

Отслеживание текущего окна

Несмотря на то, что Current свойство не поддерживается в приложениях WinUI, вам может потребоваться доступ к Window API из других мест в приложении. Например, может потребоваться получить Window границы или обработать событие Window.SizeChanged из кода для Page. В этом случае вы можете предоставить доступ к Window аналогично Current, используя общедоступное статическое свойство в классе App.

Для этого измените объявление Window в классе App, как показано здесь.

// App.xaml.cs in a WinUI app
public partial class App : Application
{
    ...
    public static Window Window { get { return m_window; } }
    private static Window m_window;
}

// App.xaml.h in a WinUI app
...
struct App : AppT<App>
{
    ...
    static winrt::Microsoft::UI::Xaml::Window Window(){ return window; };

private:
    static winrt::Microsoft::UI::Xaml::Window window;
};
...

// App.xaml.cpp
...
winrt::Microsoft::UI::Xaml::Window App::window{ nullptr };
...

Затем, чтобы получить доступ к Window из других мест в приложении, используйте App.Window, например:

// MainPage.xaml.cs in a WinUI app
var width = App.Window.Bounds.Width;

// MainPage.xaml.cpp in a WinUI app
#include <App.xaml.h>
auto width{ App::Window().Bounds().Width };

Это важно

Использование статического свойства Window в вашем классе App полезно, если приложение использует только одно окно. Если ваше приложение использует несколько окон, следует использовать WindowId для отслеживания экземпляров Window, чтобы гарантировать, что вы обращаетесь к правильному экземпляру Window. Дополнительные сведения и примеры см. в разделе "Показать несколько окон для приложения ".

  • Last updated on