Visão geral das janelas para WinUI 3 e Windows App SDK

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

A aplicação WinUI 3 Gallery inclui exemplos interativos de controlos e funcionalidades WinUI. Descarrega a aplicação na Microsoft Store ou navega pelo código-fonte no GitHub.

XAML Window

Em seu aplicativo, o objeto window é uma instância da classe Microsoft.UI.Xaml.Window (ou uma classe derivada) que representa a janela no código do programa. Cria-o diretamente através de uma chamada ao 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 doWindows aplicativo é criada pelo sistema operacional e é representada por um objeto de janela Win32. É um contêiner gerenciado pelo sistema no qual seu conteúdo é hospedado e representa a entidade com a qual os usuários interagem quando redimensionam e movem seu aplicativo na tela. (Consulte Sobre Windows na documentação do Win32 para obter mais informações.)

Depois de Windows criar a janela do aplicativo, a função de criação retorna um window handle (HWND) que identifica exclusivamente a janela. A window handle tem o tipo de dados HWND, embora tenha aparecido em C# como um IntPtr. É um identificador opaco para uma estrutura de dados interna Windows que corresponde a uma janela desenhada pelo sistema operativo e que 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 no seu aplicativo. AppWindow e classes relacionadas fornecem APIs que permitem gerir muitos aspetos das janelas de topo da aplicação sem necessidade de aceder diretamente ao HWND.

O tempo de vida de um AppWindow objeto e de um HWND é o mesmo: o AppWindow está disponível imediatamente após a janela ter sido criada e é destruído quando a janela é fechada.

Diagrama de API de janelas

Este diagrama mostra a relação entre as classes e 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 do AppWindow para disponibilizar a outras estruturas 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 comumente usadas.

Window/AppWindow Comparação de API

Se usar o WinUI XAML como framework de interface da sua aplicação, tanto a Window API como a AppWindow API estão disponíveis para si. A partir do Windows App SDK 1.4, você pode usar a Windowpropriedade .AppWindow para obter um AppWindow objeto de uma janela XAML existente. Com este objeto AppWindow tens de access às APIs adicionais de gestão de janelas.

Gestão do tempo de vida

Quando crias um novo project WinUI no Visual Studio, o modelo de project fornece uma classe MainWindow para ti, que é uma subclasse de Window. Se o seu aplicativo só precisa de uma janela, isso é tudo o 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á API para anexar conteúdo à janela que você cria. Em vez disso, obtém uma instância de AppWindow que é criada pelo sistema e associada a XAML Window e HWND. No WinUI 1.4 e posterior, você pode usar a Windowpropriedade .AppWindow para obter a instância de AppWindow. Em outros casos, pode-se usar o método estático AppWindow.GetFromWindowId para obter a instância de AppWindow. Consulte Gerir janelas de aplicações para obter mais informações.

Content

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

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

Você pode modificar a barra de título do seu aplicativo em diferentes graus; definir o título e o ícone, alterar as cores ou substituir completamente a barra de título por conteúdo personalizado da aplicação.

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

Tamanho e posição

Você utiliza a propriedade Window.Bounds e o evento SizeChanged para gerir elementos na interface do utilizador da aplicação, como mover elementos quando o tamanho da janela altera. XAML usa effective pixels (epx), não pixels físicos reais. Effective pixels são uma unidade de medida virtual e são usados para expressar dimensões de layout e espaçamento, independentemente da densidade da tela.

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

Em alguns casos, você pode precisar usar medidas de uma classe na outra classe, caso em que você precisará converter entre effective pixels pixels e dispositivo. Por exemplo, se definires regiões de arrasto numa barra de título personalizada, precisarás de converter medidas. 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

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

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

Acompanhar a janela atual

Apesar de a propriedade Current não ser suportada nas aplicações WinUI, ainda poderá precisar de aceder às APIs Window a partir de outros locais da sua aplicação. Por exemplo, talvez seja necessário obter os Window limites ou manipular o evento Window.SizeChanged de uma Página no código. Neste caso, pode fornecer acesso ao Window de forma semelhante à propriedade Current ao usar uma propriedade pública estática na sua classe App.

Para fazê-lo, modifique a declaração Window na classe App, como 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 };
...

Depois, para aceder ao Window de outros locais na tua aplicação, usa App.Window, assim:

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

Tópicos relacionados

• Gerenciar janelas de aplicativos
• Migração de funcionalidades de sistemas de janelas
• Chamar APIs de interoperação numa aplicação .NET
• Recuperar um window handle (HWND)
• Exemplo de galeria de janelas