Visão geral de janelas para WinUI e Windows SDK de Aplicativos

A funcionalidade de janela em um aplicativo WinUI é fornecida por uma combinação da classe XAML Window e da AppWindow classe, ambas baseadas no modelo HWND Win32.

• APIs importantes: Window classe, AppWindow classe

Abra o aplicativo da Galeria do WinUI 3 e veja exemplos de janelas em ação

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou obtenha o código-fonte no GitHub

XAML Window

Em seu aplicativo, o objeto de janela é uma instância da classe Microsoft.UI.Xaml.Window (ou uma classe derivada) que representa a janela no código do programa. Você o cria diretamente com uma chamada para o construtor. O XAML Window é onde você anexa o conteúdo do aplicativo e gerencia o ciclo de vida das janelas do aplicativo.

HWND

A janela do aplicativo é criada pelo Windows sistema operacional e é representada por um objeto de janela Win32. É um contêiner gerenciado pelo sistema no qual seu conteúdo está hospedado e representa a entidade com a qual os usuários interagem quando redimensionam e movem seu aplicativo na tela. (Veja Sobre Windows na documentação do Win32 para mais informações.)

Depois Windows de criar a janela do aplicativo, a função de criação retorna um window handle (HWND) que identifica exclusivamente a janela. Um window handle tem o tipo de dados HWND, embora seja exibido em C# como um IntPtr. É uma alça opaca para uma estrutura de dados Windows interna que corresponde a uma janela desenhada pelo sistema operacional e consome recursos do sistema quando presente.

O HWND é criado após o objeto XAML Window, normalmente quando o método Window.Activate é chamado.

AppWindow

O Windows SDK do Aplicativo fornece funcionalidade de janela adicional por meio da classe Microsoft.UI.Windowing.AppWindow AppWindow representa uma abstração de alto nível do HWND. Há um mapeamento 1:1 entre um AppWindow e um HWND de nível superior em seu aplicativo. AppWindow e suas classes relacionadas fornecem APIs que permitem gerenciar muitos aspectos das janelas de nível superior do aplicativo sem a necessidade de acessar o HWND diretamente.

O tempo de vida de um AppWindow objeto e de um HWND é o mesmo: ele AppWindow está disponível imediatamente após a criação da janela e é destruído quando a janela é fechada.

Diagrama da API de janelas

Este diagrama mostra a relação entre as classes e as APIs que você usa para gerenciar janelas em seu aplicativo e quais classes são responsáveis por cada parte do gerenciamento de janelas. Em alguns casos, como ExtendsContentIntoTitleBar, a API é um membro de AppWindow para torná-la disponível para outros frameworks de interface do usuário, mas também é exposta na classe Window por conveniência. O diagrama não é abrangente, mas mostra as APIs mais usadas.

Observação

Você pode usar AppWindow APIs com qualquer estrutura de interface do usuário compatível com o SDK do Windows Aplicativo – Win32, WPF, WinForms ou WinUI 3. Para estruturas diferentes do WinUI 3, a funcionalidade mostrada na caixa XAML Window do diagrama seria substituída pelas APIs de janela específicas da estrutura apropriadas:

• WPF Window
• Windows Formulários
• APIs de janela do Win32, MFC Windows

Comparação de API Window/AppWindow

Se você usar o WinUI 3 XAML como a estrutura de interface do usuário do aplicativo, as APIs Window e AppWindow estarão disponíveis para você. A partir do Windows App SDK 1.4, você pode usar a propriedade Window.AppWindow para obter um objeto AppWindow de uma janela XAML existente. Com esse AppWindow objeto, você tem acesso às APIs de gerenciamento de janela adicionais.

Importante

Se você não estiver usando o WinUI 3 1.3 ou posterior, use APIs de interoperabilidade para obter o AppWindow a fim de usar as AppWindow APIs. Para obter mais informações sobre as APIs de interoperabilidade, consulte Gerenciar janelas de aplicativo – estrutura da interface do usuário e interoperabilidade do HWND e o exemplo da galeria de janelas.

Gerenciamento de tempo de vida

XAML Window	AppWindow
Constructor	Criar, GetFromWindowId
Activate	Mostrar, Ocultar
Fechar, Fechado	Destruir, Destruindo, Fechar
>>>	Id, OwnerWindowId

Quando você cria um novo projeto WinUI no Visual Studio, o modelo de projeto fornece uma MainWindow classe para você, que é uma sub-classe de Window. Se seu aplicativo precisar apenas de uma janela, isso é tudo que você precisa. Para saber como criar e gerenciar janelas adicionais e por que você pode querer, consulte Mostrar várias janelas para seu aplicativo.

A AppWindow classe tem APIs para criar e destruir uma nova janela; no entanto, para um aplicativo WinUI, você não fará isso na prática porque não há nenhuma API para anexar conteúdo à janela criada. Em vez disso, você obtém uma instância de AppWindow, que é criada pelo sistema e está associada ao XAML Window e ao HWND. No WinUI 1.4 e posterior, você pode usar a Windowpropriedade .AppWindow para obter a instância de AppWindow. Em outros casos, você pode usar o método estático AppWindow.GetFromWindowId para obter a instância AppWindow. Consulte Gerenciar janelas do aplicativo para obter mais informações.

Content

XAML Window	AppWindow
Conteúdo	N/A

A propriedade Window.Content é onde você anexa o conteúdo do seu aplicativo à janela que o exibe. Você pode fazer isso no XAML ou no código.

Título, ícone e barra de título

XAML Window	AppWindow
Title	Title
SetTitleBar	TitleBar
>>>	SetIcon, SetTaskbarIcon, SetTitleBarIcon
ExtendsContentIntoTitleBar	AppWindow.TitleBar.ExtendsContentIntoTitleBar

Você pode modificar a barra de título do aplicativo em diferentes graus; definindo o título e o ícone, alterando as cores ou substituindo completamente a barra de título pelo conteúdo personalizado do aplicativo.

Para obter informações sobre como usar APIs de barra de título, incluindo exemplos de código, consulte a personalização da barra de título.

Tamanho e posição

XAML Window	AppWindow
Limites	Posição, tamanho, clientSize
TamanhoAlterado	Alterado (MudançaDePosição, MudançaDeTamanho)
>>>	Mover, Redimensionar, ResizeClient, MoveAndResize
>>>	MoveInZOrderAtBottom, MoveInZOrderAtTop, MoveInZOrderBelow

Você usa a propriedade Window.Bounds e o evento SizeChanged para gerenciar itens na interface do usuário do aplicativo, como mover os elementos quando o tamanho da janela é alterado. O XAML usa effective pixels (epx), não pixels físicos reais. Effective pixels são uma unidade virtual de medida e são usadas para expressar dimensões de layout e espaçamento, independentemente da densidade da tela.

AppWindow, por outro lado, usa o Window Sistema de Coordenadas, em que a unidade básica de medida é pixels de dispositivo físico. Você usa as APIs de AppWindow para ações relacionadas a janelas, como redimensionar a janela ou movê-la em relação a outra coisa na tela.

Em alguns casos, talvez seja necessário usar medidas de uma classe na outra, e, nesse caso, você precisará converter entre pixels effective pixels e pixels de dispositivo. Por exemplo, se você definir regiões de arrastar em uma barra de título personalizada, precisará converter as unidades de medida. Para obter um exemplo de como usar XamlRoot.RasterizationScale para converter medidas, consulte a seção de conteúdo interativo do artigo de personalização da barra de título.

Aparência e comportamento

XAML Window	AppWindow
SystemBackdrop	N/A
>>>	Apresentador, ConfigurarApresentador
>>>	IsShownInSwitchers
Visible, VisibilityChanged	IsVisible, Alterado (DidVisibilityChange)
DispatcherQueue	DispatcherQueue, AssociateWithDispatcherQueue
Compositor	N/A

As APIs XAML Window geralmente são responsáveis pela aparência do conteúdo do aplicativo, como a tela de fundo. Para obter mais informações sobre SystemBackdrop, consulte Aplicar Mica ou materiais acrílicos.

AppWindow As APIs são responsáveis pela parte não cliente da janela e pela interação do aplicativo com o Windows sistema operacional.

Observação

A classe XAML Window tem várias propriedades que foram transportadas da UWP Windows. UI. Xaml.Window classe, mas não têm suporte em aplicativos WinUI. Essas propriedades sempre têm um null valor e não são usadas em aplicativos WinUI: CoreWindow, Currente Dispatcher.

Acompanhar a janela atual

Embora a propriedade Current não tenha suporte em aplicativos WinUI, talvez você ainda precise acessar as APIs Window de outros locais em seu aplicativo. Por exemplo, talvez seja necessário obter os Window limites ou manipular o evento Window.SizeChanged a partir do código de uma Page. Nesse caso, você pode fornecer acesso ao Window, de maneira semelhante à propriedade Current, usando uma propriedade estática pública em sua classe App.

Para fazer isso, modifique a Window declaração na classe App, conforme mostrado aqui.

// 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 };
...

Em seguida, para acessar o Window de outros locais em seu aplicativo, use App.Window, desta forma:

// 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 };

Importante

Usar uma propriedade estática Window em sua App classe será útil se o aplicativo usar apenas uma única janela. Se seu aplicativo usar várias janelas, você deverá usar WindowId para acompanhar as Window instâncias, para garantir que você esteja acessando a instância correta de Window. Confira Mostrar várias janelas para seu aplicativo para obter mais informações e exemplos.

Tópicos relacionados

• Gerenciar janelas do aplicativo
• Migração da funcionalidade de janela
• Chamar as APIs de interoperabilidade com um aplicativo .NET
• Recuperar um window handle (HWND)
• Exemplo de galeria de janelas